fix(scripts): stop check-manifests passing on entries it cannot parse

A marketplace entry missing its source key disabled both directions of the check at once. The helper required source to be a string, so a source-less entry was skipped and its plugin.json existence check never ran; the name axis selected on (.source | type) != "string", and null != "string" is true, so the same entry also marked its on-disk directory as listed. Delete source from an entry and delete its plugin.json and the script exited 0. Because sync-plugin-content.sh --all derives its work list from the same helper, that plugin silently dropped out of the content-mirror gate too. Also in this pass: - a wrongly typed skills value crashed the script mid-loop with a raw jq error and no "Manifest check failed:" line, leaving every later plugin unchecked. Note skills is legally string|string[] per both host schemas, so a string now resolves as a single path rather than erroring - array- and object-valued pointer fields were reported missing even when they resolved, because the whole JSON value was pretty-printed into a path test - an unparseable marketplace.json died inside a process substitution, so the run reported six "no entry in marketplace.json" errors that sent the reader to edit apm.yml when the real fault was a corrupt manifest - a missing marketplace.json exited 0 even with plugin directories present Tests: 14 -> 23 assertions. Every failure case asserts on message text, not exit code alone, since exit 1 here is reachable by several causes that call for opposite fixes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
2026-08-14 11:03:57 +00:00
parent 9e612fd183
commit 3f1ee47f1e
3 changed files with 389 additions and 36 deletions
--- a/scripts/check-manifests.sh
+++ b/scripts/check-manifests.sh
@@ -29,6 +29,12 @@ set -euo pipefail
 # compiled-output drift of exactly the kind ADR-0017 wires pre-push gates for -- and it
 # is the same plugin set the validate-plugins pre-commit hook already globs as
 # plugins/*/.
+#
+# Every pass above reads its plugin set out of marketplace.json, so anything that makes
+# that file yield nothing -- absent, unparseable, or an entry with no `source` -- used to
+# read as "clean" rather than "unchecked". The guards below turn each of those into an
+# explicit, attributable failure instead, because a vacuous pass is the one result a gate
+# must never produce.

 REPO_ROOT="${1:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
 FAIL=0
@@ -41,15 +47,112 @@ if ! command -v jq &>/dev/null; then
 fi

 MARKETPLACE="$REPO_ROOT/.claude-plugin/marketplace.json"
-if [[ ! -f "$MARKETPLACE" ]]; then
-  exit 0
-fi

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # Repo-root-relative, not script-dir-relative -- see tests/run-tests.sh for why.
 # shellcheck source=scripts/lib/marketplace-plugins.sh
 source "$SCRIPT_DIR/lib/marketplace-plugins.sh"

+# Candidate plugin directories on disk. The trigger is any of the three markers that
+# make a directory a plugin rather than scratch -- apm.yml (the ADR-0015 authoring
+# source), .apm/ (its content tree), or a compiled .claude-plugin/plugin.json. Matching
+# all three keeps this set aligned with the plugins/*/ glob the validate-plugins
+# pre-commit hook uses, which is the disagreement the disk -> marketplace pass below
+# exists to close; a directory with none of them is scratch and stays out of scope.
+#
+# It is collected before the marketplace is read because a missing marketplace.json is
+# only "nothing to check" when there is also nothing on disk to check against it.
+PLUGIN_DIRS=()
+for candidate in "$REPO_ROOT"/plugins/*/; do
+  candidate="${candidate%/}"
+  [[ -d "$candidate" ]] || continue
+  if [[ ! -f "$candidate/apm.yml" && ! -d "$candidate/.apm" && ! -f "$candidate/.claude-plugin/plugin.json" ]]; then
+    continue
+  fi
+  PLUGIN_DIRS+=("$candidate")
+done
+
+# An absent marketplace.json used to exit 0 unconditionally -- the same empty-set-reads-
+# as-pass shape this script's other passes were fixed for. Per ADR-0015 the manifest is
+# compiled output of root apm.yml's marketplace.packages[], so its absence alongside
+# on-disk packages is drift, not an opt-out: it leaves every marketplace-derived gate
+# (this one and sync-plugin-content.sh --all) walking an empty plugin set in silence.
+if [[ ! -f "$MARKETPLACE" ]]; then
+  if [[ ${#PLUGIN_DIRS[@]} -eq 0 ]]; then
+    exit 0
+  fi
+  listing=""
+  # Guarded expansion even though the check above makes an empty array unreachable
+  # here: bash 3.2 under `set -u` aborts on a bare expansion of an empty array, and
+  # tests/test-vale-wrap.sh's bash32_glob scan is line-based, so a guard two lines up
+  # cannot clear it. Same form as the disk -> marketplace loop below.
+  for candidate in ${PLUGIN_DIRS[@]+"${PLUGIN_DIRS[@]}"}; do
+    listing+="${listing:+, }${candidate#"$REPO_ROOT"/}"
+  done
+  err ".claude-plugin/marketplace.json does not exist, but plugins/ holds ${#PLUGIN_DIRS[@]} plugin directory/ies ($listing) — every marketplace-derived check (this one, and sync-plugin-content.sh --all) silently walks an empty plugin set without it. Recompile the manifests from root apm.yml with \`apm pack\`."
+  echo "Manifest check failed: $FAIL error(s)" >&2
+  exit 1
+fi
+
+# Preconditions the marketplace walk below cannot report on itself: it runs inside a
+# process substitution, so an abort in there is swallowed (see the helper's comment).
+assert_marketplace_manifest_usable "$MARKETPLACE"
+
+# Validates one plugin.json pointer field against disk, for the non-apm fallback below.
+#
+#   check_pointer_field <plugin_name> <plugin_dir> <field> <test_flag>
+#
+# test_flag is `test`'s: -d where only a directory is meaningful, -e otherwise.
+#
+# Per the vendored host docs (plugins/kyberforge/docs/research/docs/
+# claude-code-plugins/configuration.md and .../github-copilot-plugins/configuration.md)
+# these fields are legally `string | string[] | object`. Reading them with
+# `jq -r ".$field // empty"` collapsed the array and object shapes to their
+# pretty-printed JSON text, which then matched no path on disk -- a manifest that
+# resolves fine reported as broken. Reading `.skills | length` was worse than wrong: on
+# a (legal) string value it returned the character count, and the `.skills[$i]` that
+# followed aborted the whole script mid-loop under `set -e` with no summary line, so
+# every plugin later in the marketplace went unchecked.
+check_pointer_field() {
+  local name="$1" plugin_dir="$2" field="$3" test_flag="$4"
+  local manifest="$plugin_dir/.claude-plugin/plugin.json"
+  local field_type count i elem_type
+
+  field_type="$(jq -r ".${field} | type" "$manifest")"
+  case "$field_type" in
+    null) ;;
+    # An inline definition (a hooks or mcpServers object written straight into the
+    # manifest) declares no path, so there is nothing on disk to resolve.
+    object) ;;
+    string)
+      check_pointer_path "$name" "$plugin_dir" "$field" "$(jq -r ".${field}" "$manifest")" "$test_flag"
+      ;;
+    array)
+      count="$(jq ".${field} | length" "$manifest")"
+      for ((i = 0; i < count; i++)); do
+        elem_type="$(jq -r ".${field}[$i] | type" "$manifest")"
+        if [[ "$elem_type" != "string" ]]; then
+          err "plugin '$name': ${field}[$i] must be a path string, got $elem_type"
+          continue
+        fi
+        check_pointer_path "$name" "$plugin_dir" "$field" "$(jq -r ".${field}[$i]" "$manifest")" "$test_flag"
+      done
+      ;;
+    *)
+      err "plugin '$name': $field must be a path string, an array of path strings, or an inline object, got $field_type"
+      ;;
+  esac
+}
+
+check_pointer_path() {
+  local name="$1" plugin_dir="$2" field="$3" ref="$4" test_flag="$5"
+  local full_path="$plugin_dir/$ref"
+  full_path="${full_path%/}"
+  if ! test "$test_flag" "$full_path"; then
+    err "plugin '$name': $field path not found: $ref"
+  fi
+}
+
 # Every local plugin directory marketplace.json claimed, canonicalized, so the
 # disk -> marketplace pass below can tell "listed" from "unlisted" regardless of how
 # the `source:` string was spelled (./plugins/x, plugins/x, plugins/x/).
@@ -78,33 +181,14 @@ while IFS=$'\t' read -r name plugin_dir; do

  # Fallback for a non-apm plugin: validate that any skills/hooks/mcpServers/agents
  # pointer fields in its hand-authored plugin.json still resolve to real paths.
-  skill_count=$(jq '.skills | if . then length else 0 end' "$manifest")
-  for ((s = 0; s < skill_count; s++)); do
-    skill_path=$(jq -r ".skills[$s]" "$manifest")
-    full_path="$plugin_dir/$skill_path"
-    full_path="${full_path%/}"
-    if [[ ! -d "$full_path" ]]; then
-      err "plugin '$name': skills path not found: $skill_path"
-    fi
-  done
-
-  for field in hooks mcpServers agents; do
-    ref=$(jq -r ".${field} // empty" "$manifest")
-    [[ -z "$ref" ]] && continue
-    full_path="$plugin_dir/$ref"
-    full_path="${full_path%/}"
-    if [[ ! -e "$full_path" ]]; then
-      err "plugin '$name': $field path not found: $ref"
-    fi
-  done
+  # skills/agents point at directories; hooks/mcpServers may point at a file.
+  check_pointer_field "$name" "$plugin_dir" skills -d
+  check_pointer_field "$name" "$plugin_dir" agents -e
+  check_pointer_field "$name" "$plugin_dir" hooks -e
+  check_pointer_field "$name" "$plugin_dir" mcpServers -e
 done < <(list_marketplace_local_plugins "$REPO_ROOT" "$MARKETPLACE")

-# Disk -> marketplace. The trigger is any of the three markers that make a directory
-# a plugin rather than scratch -- apm.yml (the ADR-0015 authoring source), .apm/ (its
-# content tree), or a compiled .claude-plugin/plugin.json. Matching all three keeps
-# this set aligned with the plugins/*/ glob the validate-plugins pre-commit hook uses,
-# which is the disagreement this check exists to close; a directory with none of them
-# is scratch and stays out of scope.
+# Disk -> marketplace, over the PLUGIN_DIRS candidate set collected above.
 #
 # A candidate counts as listed if it is either a directory some local entry pointed at
 # (path match, canonicalized above) or a directory whose name matches a REMOTE entry's
@@ -117,18 +201,19 @@ done < <(list_marketplace_local_plugins "$REPO_ROOT" "$MARKETPLACE")
 # the basename of the directory it points at: an entry named "beta" pointing at
 # ./plugins/alpha would mark an unrelated, entirely unlisted plugins/beta/ as listed.
 # Local entries already have an exact path to match on, so they need no name fallback.
+#
+# `.source == null` has to be excluded explicitly: `(null | type) != "string"` is TRUE,
+# so before this guard an entry with no `source` at all landed here and marked its
+# same-named directory listed -- while the local walk above skipped it for lacking a
+# string source. One malformed entry thus disabled BOTH directions of the check at once.
+# assert_marketplace_manifest_usable now rejects such an entry outright; the guard stays
+# because this select must not depend on that check running first.
 MARKETPLACE_NAMES=()
 while IFS= read -r entry_name; do
  [[ -n "$entry_name" ]] && MARKETPLACE_NAMES+=("$entry_name")
-done < <(jq -r '.plugins[]? | select((.source | type) != "string") | .name // empty' "$MARKETPLACE")
-
-for candidate in "$REPO_ROOT"/plugins/*/; do
-  candidate="${candidate%/}"
-  [[ -d "$candidate" ]] || continue
-  if [[ ! -f "$candidate/apm.yml" && ! -d "$candidate/.apm" && ! -f "$candidate/.claude-plugin/plugin.json" ]]; then
-    continue
-  fi
+done < <(jq -r '.plugins[]? | select(.source != null and (.source | type) != "string") | .name // empty' "$MARKETPLACE")

+for candidate in ${PLUGIN_DIRS[@]+"${PLUGIN_DIRS[@]}"}; do
  candidate_abs="$(cd "$candidate" && pwd -P)"
  candidate_name="$(basename "$candidate")"
  listed=0
--- a/scripts/lib/marketplace-plugins.sh
+++ b/scripts/lib/marketplace-plugins.sh
@@ -7,6 +7,44 @@
 #
 # Requires jq. Not meant to be executed directly -- source it.

+# assert_marketplace_manifest_usable <marketplace_json_path>
+#
+# Checks the preconditions list_marketplace_local_plugins depends on but cannot
+# report on. Both callers run the walk inside a process substitution
+# (`done < <(list_marketplace_local_plugins ...)`), which is its own subshell: a
+# jq abort in there kills only that subshell, so an unparseable manifest yields
+# zero lines and reads exactly like "this marketplace declares no local plugins".
+# The caller then blames whatever its empty-set branch blames -- for
+# check-manifests.sh, every plugin directory on disk being unlisted.
+#
+# It also rejects an entry with no `source` at all. Such an entry is not a local
+# plugin (the walk below requires a string `source`) and not a remote one either,
+# so it silently drops out of every marketplace-derived work list -- this walk's
+# and, through it, sync-plugin-content.sh --all's.
+#
+# Exits 1 with a specific message on any violation, so call it from the caller's
+# own shell -- never inside `< <(...)`, which is the exact swallowing this guards.
+assert_marketplace_manifest_usable() {
+  local marketplace="$1" plugins_type sourceless
+
+  if ! jq empty "$marketplace" >/dev/null 2>&1; then
+    echo "Error: $marketplace is not valid JSON -- every marketplace-derived check reads as \"no plugins declared\" until it parses. Fix it, or recompile it with \`apm pack\`." >&2
+    exit 1
+  fi
+
+  plugins_type="$(jq -r '.plugins | type' "$marketplace")"
+  if [[ "$plugins_type" != "array" && "$plugins_type" != "null" ]]; then
+    echo "Error: $marketplace has a \`plugins\` field of type $plugins_type; expected an array of plugin entries." >&2
+    exit 1
+  fi
+
+  sourceless="$(jq -r '[.plugins[]? | select(.source == null) | .name // "<unnamed>"] | join(", ")' "$marketplace")"
+  if [[ -n "$sourceless" ]]; then
+    echo "Error: $marketplace has entries with no \`source\` field: $sourceless. An entry without a \`source\` is neither local nor remote, so it is skipped by every marketplace-derived check while still claiming its name. Give it a \`source\` in root apm.yml's marketplace.packages[] and recompile." >&2
+    exit 1
+  fi
+}
+
 # list_marketplace_local_plugins <repo_root> <marketplace_json_path>
 #
 # Prints one "<name>\t<absolute_plugin_dir>" line per local (string `source:`)
--- a/tests/test-check-manifests.sh
+++ b/tests/test-check-manifests.sh
@@ -9,6 +9,56 @@ FAIL=0
 pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
 fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }

+# Several distinct faults all end in exit 1, and the bugs fixed below were precisely
+# about the WRONG one being reported (a corrupt manifest blamed on six unlisted plugin
+# directories, a legal manifest blamed for unresolvable paths). Exit-code-only
+# assertions cannot see that, so these cases assert on the message text.
+RUN_OUT=""
+RUN_RC=0
+run_script() { RUN_OUT="$(bash "$SCRIPT" "$1" 2>&1)" && RUN_RC=0 || RUN_RC=$?; }
+
+# assert_fails_with <fixture> <label> <expected substring>...
+assert_fails_with() {
+  local fixture="$1" label="$2"
+  shift 2
+  run_script "$fixture"
+  if [[ $RUN_RC -eq 0 ]]; then
+    fail "$label -- expected exit 1, got 0. Output: $RUN_OUT"
+    return
+  fi
+  local needle
+  for needle in "$@"; do
+    if [[ "$RUN_OUT" != *"$needle"* ]]; then
+      fail "$label -- exited $RUN_RC but message lacked '$needle'. Output: $RUN_OUT"
+      return
+    fi
+  done
+  pass "$label"
+}
+
+# assert_passes <fixture> <label>
+assert_passes() {
+  run_script "$1"
+  if [[ $RUN_RC -eq 0 ]]; then
+    pass "$2"
+  else
+    fail "$2 -- expected exit 0, got $RUN_RC. Output: $RUN_OUT"
+  fi
+}
+
+# Writes a marketplace.json listing every "<name>=<source>" pair given.
+write_marketplace() {
+  local dir="$1" entries="" pair name src
+  shift
+  for pair in "$@"; do
+    name="${pair%%=*}"
+    src="${pair#*=}"
+    entries+="${entries:+,}"$'\n'"    { \"name\": \"$name\", \"source\": \"$src\" }"
+  done
+  mkdir -p "$dir/.claude-plugin"
+  printf '{\n  "name": "test-marketplace",\n  "plugins": [%s\n  ]\n}\n' "$entries" > "$dir/.claude-plugin/marketplace.json"
+}
+
 # One trap over a registry rather than a fresh `trap 'rm -rf "$FIXTUREn"' EXIT`
 # per fixture: each such trap REPLACES the previous one, so only the last
 # fixture was ever cleaned and the rest leaked into TMPDIR every run. Same
@@ -393,6 +443,186 @@ else
  fail "flagged a listed plugin because its source: string was spelled differently"
 fi

+# --- 11. A marketplace entry with no `source` at all is rejected outright ---
+# It used to disable BOTH directions of the check for that plugin at once:
+# list_marketplace_local_plugins requires a string `source`, so the entry was skipped and
+# its .claude-plugin/plugin.json never checked; and the disk -> marketplace name axis
+# selected on `(.source | type) != "string"`, which is TRUE for null, so the same entry
+# also marked its on-disk directory "listed". Net effect: a plugin with a broken manifest
+# and a malformed entry passed clean, and silently dropped out of
+# sync-plugin-content.sh --all's work list too, since that derives from the same helper.
+echo ""
+echo "--- a marketplace entry with no source: field is a hard error ---"
+FIXTURE11="$(mktemp -d)"
+FIXTURES+=("$FIXTURE11")
+mkdir -p "$FIXTURE11/.claude-plugin" "$FIXTURE11/plugins/lint"
+cat > "$FIXTURE11/.claude-plugin/marketplace.json" <<'JSON'
+{
+  "name": "test-marketplace",
+  "plugins": [
+    { "name": "lint" }
+  ]
+}
+JSON
+printf 'name: lint\nversion: 0.1.0\ntype: skill\n' > "$FIXTURE11/plugins/lint/apm.yml"
+assert_fails_with "$FIXTURE11" \
+  "an entry with no source: is reported by name instead of silently disabling both checks" \
+  'no `source` field' 'lint'
+
+# --- 12. A `skills` string (a legal shape per the host docs) is resolved, not counted ---
+# `jq '.skills | if . then length else 0 end'` is null-safe but not type-safe: on the
+# string "./skills/x" it returned the CHARACTER count, and the `.skills[0]` that followed
+# errored ("Cannot index string with number"), killing the whole script under `set -e`
+# with no "Manifest check failed:" line -- and every plugin later in the marketplace
+# unchecked. Both configuration.md references document `skills` as string | string[].
+echo ""
+echo "--- a string-valued skills field resolves instead of crashing the script ---"
+FIXTURE12="$(mktemp -d)"
+FIXTURES+=("$FIXTURE12")
+mkdir -p "$FIXTURE12/plugins/strskills/.claude-plugin" "$FIXTURE12/plugins/strskills/custom/skills"
+write_marketplace "$FIXTURE12" "strskills=./plugins/strskills"
+cat > "$FIXTURE12/plugins/strskills/.claude-plugin/plugin.json" <<'JSON'
+{
+  "name": "strskills",
+  "skills": "./custom/skills/"
+}
+JSON
+assert_passes "$FIXTURE12" "a resolving string-valued skills field passes"
+
+# --- 13. A broken string `skills` is reported, and later plugins are still checked ---
+# The mid-loop `set -e` abort meant a fault in the FIRST plugin hid every fault after it.
+# The second entry here is broken in an unrelated way; both messages must appear.
+echo ""
+echo "--- a broken string skills field is reported without aborting the marketplace walk ---"
+FIXTURE13="$(mktemp -d)"
+FIXTURES+=("$FIXTURE13")
+mkdir -p "$FIXTURE13/plugins/first/.claude-plugin" "$FIXTURE13/plugins/second"
+write_marketplace "$FIXTURE13" "first=./plugins/first" "second=./plugins/second"
+cat > "$FIXTURE13/plugins/first/.claude-plugin/plugin.json" <<'JSON'
+{
+  "name": "first",
+  "skills": "./skills/does-not-exist"
+}
+JSON
+assert_fails_with "$FIXTURE13" \
+  "a broken string skills field is reported and the walk continues to later plugins" \
+  'skills path not found: ./skills/does-not-exist' \
+  "plugin 'second': .claude-plugin/plugin.json not found" \
+  'Manifest check failed: 2 error(s)'
+
+# --- 14. A genuinely wrong-typed `skills` is named as such, walk still continues ---
+echo ""
+echo "--- a wrong-typed skills field is reported as a type error, not a missing path ---"
+FIXTURE14="$(mktemp -d)"
+FIXTURES+=("$FIXTURE14")
+mkdir -p "$FIXTURE14/plugins/first/.claude-plugin" "$FIXTURE14/plugins/second"
+write_marketplace "$FIXTURE14" "first=./plugins/first" "second=./plugins/second"
+cat > "$FIXTURE14/plugins/first/.claude-plugin/plugin.json" <<'JSON'
+{
+  "name": "first",
+  "skills": 42
+}
+JSON
+assert_fails_with "$FIXTURE14" \
+  "a wrong-typed skills field names the type and does not abort the walk" \
+  'skills must be a path string, an array of path strings, or an inline object, got number' \
+  "plugin 'second': .claude-plugin/plugin.json not found" \
+  'Manifest check failed: 2 error(s)'
+
+# --- 15. Array- and object-valued pointer fields that resolve are not reported missing ---
+# `ref=$(jq -r ".$field // empty")` returned the PRETTY-PRINTED JSON for an array or an
+# object, which `[[ ! -e ]]` then rejected: a manifest whose paths all resolve was
+# reported broken. Both host docs give `agents` as string | string[] and `hooks` /
+# `mcpServers` as string | object (an inline definition, with no path to resolve).
+echo ""
+echo "--- array- and inline-object pointer fields that resolve are accepted ---"
+FIXTURE15="$(mktemp -d)"
+FIXTURES+=("$FIXTURE15")
+mkdir -p "$FIXTURE15/plugins/shapes/.claude-plugin" "$FIXTURE15/plugins/shapes/agents" "$FIXTURE15/plugins/shapes/skills/one"
+touch "$FIXTURE15/plugins/shapes/agents/real.md"
+write_marketplace "$FIXTURE15" "shapes=./plugins/shapes"
+cat > "$FIXTURE15/plugins/shapes/.claude-plugin/plugin.json" <<'JSON'
+{
+  "name": "shapes",
+  "skills": ["./skills/one"],
+  "agents": ["./agents/real.md"],
+  "hooks": { "PreToolUse": [{ "hooks": [{ "type": "command", "command": "true" }] }] },
+  "mcpServers": { "demo": { "command": "true" } }
+}
+JSON
+assert_passes "$FIXTURE15" \
+  "an array-valued agents and an inline-object hooks/mcpServers are not reported missing"
+
+# --- 16. A broken element inside an array-valued pointer field is still caught ---
+# Guards the fix in #15 against over-correcting into "arrays are always fine".
+echo ""
+echo "--- a broken path inside an array-valued pointer field is still caught ---"
+FIXTURE16="$(mktemp -d)"
+FIXTURES+=("$FIXTURE16")
+mkdir -p "$FIXTURE16/plugins/shapes/.claude-plugin" "$FIXTURE16/plugins/shapes/agents"
+touch "$FIXTURE16/plugins/shapes/agents/real.md"
+write_marketplace "$FIXTURE16" "shapes=./plugins/shapes"
+cat > "$FIXTURE16/plugins/shapes/.claude-plugin/plugin.json" <<'JSON'
+{
+  "name": "shapes",
+  "agents": ["./agents/real.md", "./agents/ghost.md"]
+}
+JSON
+assert_fails_with "$FIXTURE16" \
+  "a missing path in an array-valued agents field is reported with its own path" \
+  'agents path not found: ./agents/ghost.md'
+
+# --- 17. An unparseable marketplace.json is reported as such, not as unlisted plugins ---
+# The walk runs in a process substitution, so the helper's `set -e` abort on invalid JSON
+# never reached the caller. The run still exited 1 -- backstopped by the disk -> marketplace
+# pass -- but printed one "has no entry in .claude-plugin/marketplace.json ... add it to
+# root apm.yml" per plugin directory, sending the reader to edit apm.yml when the actual
+# fault was a corrupt manifest.
+echo ""
+echo "--- an unparseable marketplace.json is attributed to the manifest, not to the plugins ---"
+FIXTURE17="$(mktemp -d)"
+FIXTURES+=("$FIXTURE17")
+mkdir -p "$FIXTURE17/.claude-plugin" "$FIXTURE17/plugins/one/.claude-plugin" "$FIXTURE17/plugins/two/.claude-plugin"
+printf '{ "name": "test-marketplace", "plugins": [ { "name": "one",\n' > "$FIXTURE17/.claude-plugin/marketplace.json"
+echo '{ "name": "one" }' > "$FIXTURE17/plugins/one/.claude-plugin/plugin.json"
+echo '{ "name": "two" }' > "$FIXTURE17/plugins/two/.claude-plugin/plugin.json"
+run_script "$FIXTURE17"
+if [[ $RUN_RC -eq 0 ]]; then
+  fail "exited 0 on an unparseable marketplace.json -- expected exit 1"
+elif [[ "$RUN_OUT" != *"is not valid JSON"* ]]; then
+  fail "an unparseable marketplace.json was not named as such. Output: $RUN_OUT"
+elif [[ "$RUN_OUT" == *"has no entry in .claude-plugin/marketplace.json"* ]]; then
+  fail "an unparseable marketplace.json was misreported as unlisted plugin directories. Output: $RUN_OUT"
+else
+  pass "an unparseable marketplace.json is reported as invalid JSON, not as unlisted plugin directories"
+fi
+
+# --- 18. A missing marketplace.json with plugins on disk is drift, not an opt-out ---
+# `[[ ! -f "$MARKETPLACE" ]] && exit 0` was the same empty-set-reads-as-pass shape as the
+# rest: per ADR-0015 the manifest is compiled from root apm.yml, so its absence next to
+# on-disk packages means the compiled output is missing, and every marketplace-derived
+# gate walks an empty plugin set in silence.
+echo ""
+echo "--- a missing marketplace.json alongside on-disk plugin directories fails ---"
+FIXTURE18="$(mktemp -d)"
+FIXTURES+=("$FIXTURE18")
+mkdir -p "$FIXTURE18/plugins/orphan/.apm/skills"
+assert_fails_with "$FIXTURE18" \
+  "a missing marketplace.json with plugin directories present is reported as drift" \
+  '.claude-plugin/marketplace.json does not exist' \
+  'plugins/orphan'
+
+# --- 18b. A missing marketplace.json with nothing to check still exits 0 ---
+# Guards the fix above against over-correcting into "always fail without a manifest":
+# a repo with no plugin directories genuinely has nothing for this gate to check.
+echo ""
+echo "--- a missing marketplace.json with no plugin directories still exits 0 ---"
+FIXTURE18B="$(mktemp -d)"
+FIXTURES+=("$FIXTURE18B")
+mkdir -p "$FIXTURE18B/plugins/scratch/notes" "$FIXTURE18B/docs"
+assert_passes "$FIXTURE18B" \
+  "no marketplace.json and no plugin-marked directories is a genuine no-op, not a failure"
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]