ci: no gate detects a duplicate key in a plugin manifest — schema validation cannot, and every consumer is last-wins

[kyle-sexton]

#1492 was a duplicate "version" member in plugins/skill-quality/.claude-plugin/plugin.json that shipped to main through a fully green 27-context CI suite. The manifest fix is #1494. This issue is the systemic half: no gate in CI can detect a duplicate key in a plugin manifest.

Verified, not assumed

Each of these was run against a probe manifest carrying two version members (0.11.0 then 0.12.0):

Check	Result	Why it cannot catch it
check-jsonschema + json.schemastore.org/claude-code-plugin-manifest.json (the hygiene job's Validate plugin manifests step)	ok -- validation done, exit 0	JSON Schema has no vocabulary for duplicate object keys. Duplicates are a document-level concern, not a schema-level one, so no schemafile can express the constraint.
claude plugin validate <dir> (via scripts/validate-plugins.sh)	exit 0, warned only about a missing author	Parses last-wins; never inspects key uniqueness.
scripts/validate-plugin-contracts.mjs, scripts/generate-catalog.mjs	pass	JSON.parse is last-wins per ECMA-262.
changelog-parity-gate (scripts/check-changelog-parity.sh)	pass	Reads the version with jq -r '.version' — last-wins. This gate is also the one most harmed by the defect, since it compares a version it cannot trust.

So every consumer in the pipeline resolves the same last-wins value and reports the intended version whether or not the duplicate is present. The green suite was not a fluke — it is the expected behaviour of every tool involved.

Why this defect class keeps appearing

The conflict shape that produces it recurred three times in one night across #1085, #1096, and the CHANGELOG resolutions alongside them: two branches independently bump the same plugin to the same version, so the version line becomes common context outside the conflict region while only the neighbouring differing line lands inside it. Any resolution that re-emits the field rather than editing the surviving one produces a duplicate key. That is a mechanical trap, not a lapse of attention, and it is exactly what a gate is for.

Impact when it does ship

The advertised release becomes parser-dependent: last-wins readers resolve the newer version, first-wins readers retain the stale one, and duplicate-rejecting consumers can reject the manifest outright — so a plugin update can be misidentified or blocked.

Which gate should own the check, and why

The hygiene job, adjacent to its existing Validate plugin manifests step.

• It already enumerates exactly the right file set (plugins/*/.claude-plugin/plugin.json) for schema validation, so the glob and the ownership already exist there — no new file-discovery logic is needed.
• The defect class is document-level JSON integrity, the same tier as "does it parse" and "does it match the schema." That is hygiene's concern; plugin-gate owns manifest semantics (contracts, catalog parity), which is a different tier.
• Most importantly, the schema step is the check a reader would assume already covers this. Putting the duplicate-key check next to it removes the false assurance at the point where the assurance is currently implied, rather than burying it in a semantics job.
• Wiring is cheap: the job's step outcomes are already aggregated by scripts/aggregate-hygiene-results.sh, where any non-success outcome fails the job. It is one step plus one line in the checks block.

Not implemented here, per direction. Two notes for whoever picks it up:

• The detector is cheap and needs no new toolchain: Python's json.load(..., object_pairs_hook=...) sees the raw key/value pairs before de-duplication, and Python is already present in that job because check-jsonschema is a Python tool.
• Worth scoping to .claude-plugin/marketplace.json as well as the plugin manifests — same defect class, same conflict shape, same blast radius.

Related

• skill-quality: plugin.json ships two version members (0.11.0 and 0.12.0) — advertised release is parser-dependent #1492 — the shipped duplicate-key instance.
• fix(skill-quality): drop the duplicate version member from plugin.json #1494 — the manifest fix.
• feat(skill-quality): fresh-eyes delegation doctrine + conformance gate (check 21) #1096, feat(skill-quality): add the shared listing-budget report, fix check 2's joiner #1450 — the version collision that produced the conflict shape.

[kyle-sexton]

This was generated by AI during triage.

Triage

Verification: CONFIRMED.

• .github/workflows/ci.yml's hygiene job runs check-jsonschema against
  https://json.schemastore.org/claude-code-plugin-manifest.json for plugin manifests — JSON Schema
  operates on the already-parsed document, so it structurally cannot express a duplicate-object-key
  constraint; this matches the issue's claim exactly.
• I confirmed the real precedent this issue cites: skill-quality: plugin.json ships two version members (0.11.0 and 0.12.0) — advertised release is parser-dependent #1492 ("plugin.json ships two version members")
  is closed, and its fix, fix(skill-quality): drop the duplicate version member from plugin.json #1494, is merged — so the defect class already shipped through this
  exact green-suite path once.
• scripts/validate-plugins.sh and the manifest-consuming scripts (validate-plugin-contracts.mjs,
  generate-catalog.mjs, the changelog-parity gate) all resolve JSON via standard last-wins parsing
  (JSON.parse / jq), which is standard, well-established behavior per ECMA-262 and jq's own
  object-construction semantics — none of them can see a duplicate key either. No gate anywhere in
  the pipeline can catch this today.

Classification

• Type: Task
• Priority: high — this is not hypothetical: the exact defect class already shipped to main
  once (skill-quality: plugin.json ships two version members (0.11.0 and 0.12.0) — advertised release is parser-dependent #1492) through a fully green 27-context CI suite, and the same conflict shape (two branches
  independently bumping the same plugin/version) recurred three times in one night per the issue's
  own account.
• Work class: work-class: scoped — one new detector script plus one step/one line of wiring in
  an existing job (hygiene), using a stdlib-only approach (json.load(..., object_pairs_hook=...))
  in a job that already runs Python.
• Routing: autonomous-eligible (agent-ready). Fully specified: the issue names the exact job to
  extend (hygiene, adjacent to "Validate plugin manifests"), the exact detection technique
  (object_pairs_hook sees raw key/value pairs before de-duplication), the file scope
  (plugins/*/.claude-plugin/plugin.json, plus .claude-plugin/marketplace.json), and the wiring
  point (scripts/aggregate-hygiene-results.sh's checks block, any non-success outcome fails the
  job). No open design decision remains.

Agent Brief

Type: Task
Summary: Add a hygiene-job CI step that detects a duplicate top-level key in any plugin manifest
or the marketplace manifest, since JSON Schema validation and every consumer's last-wins JSON parsing
cannot.

Current behavior: A plugin manifest (or the marketplace manifest) carrying a duplicate top-level
key — e.g. two "version" members — parses successfully under JSON Schema validation and every
downstream consumer (validate-plugins.sh, the contract/catalog scripts, the changelog-parity gate),
each silently resolving to the last-declared value. No CI signal distinguishes this from a
well-formed manifest.

Desired behavior: A CI check in the hygiene job fails when any
plugins/*/.claude-plugin/plugin.json or .claude-plugin/marketplace.json contains a duplicate
top-level key, using the raw key/value pairs as encountered (before any de-duplicating parse), and is
wired into the job's existing outcome-aggregation step so a failure here fails the job the same way
any other hygiene check does.

Key interfaces: a new detector step in the hygiene job (Python, using the interpreter already
present for check-jsonschema), reading each target manifest's raw key/value pairs in file order
rather than through a de-duplicating JSON parse; one added line in the job's outcome-aggregation
checks block.

Acceptance criteria:

• A manifest with a duplicate top-level key fails the hygiene job with a message identifying the
  file and the duplicated key.
• A well-formed manifest with no duplicate keys passes unaffected.
• Both plugins/*/.claude-plugin/plugin.json and .claude-plugin/marketplace.json are covered.
• The new check's outcome is wired into scripts/aggregate-hygiene-results.sh's existing
  aggregation so a failure here fails the job.

Out of scope: re-validating #1494's fix (already merged); changing the schema-validation step
itself, which correctly does its own job and is not being replaced.

[kyle-sexton]