fix(kyberforge): stop the content mirror amputating a shipped template asset

The mirror's `tests/` exclusion was depth-agnostic, so it deleted
`skill-author/assets/templates/tests/` — a template the skill scaffolds FROM —
alongside the depth-2 dev fixtures it was meant to drop. Since ADR-0017 makes the
mirror the installed content, the shipped scaffolder was broken: the mirror copy of
`new-skill.sh` exited 2 on `sed: can't read .../tests/README.md`, leaving a
half-written skill, while the byte-identical `.apm/` copy exited 0. `--check` was
green about it.

Check mode was restructured rather than patched because `diff -x` matches a basename
at any depth and cannot express the depth-2 scoping the fix needs — the two modes
could not be made to agree by construction. Check mode now runs the real `sync_dir`
into a throwaway root and diffs with no exclusions, leaving the exclusion rule and
the hooks destination each in exactly one place.

Also fixed here, all previously invisible to `--check`:

- Merged hooks were written to `<plugin>/hooks.json`, which Claude Code does not
  convention-scan, while ADR-0017 itself quoted `hooks/hooks.json` as the contract.
  Moved, with the legacy path cleaned up as stale. No `hooks` pointer is added to
  `plugin.json`, so this does not reopen the option ADR-0017 rejected.
- Only the first drift per plugin was reported: `diff | sed` returns 1 under
  `pipefail`, and `set -e` killed the subshell before the remaining checks and
  before `FAIL=1`.
- File-mode and symlink drift were invisible, so `--check` and a real sync
  disagreed; a find-based type/mode manifest now covers both.

The tests pinned almost none of this — the stale-skill wipe, the check-mode stale
branch, three `MIRROR_DIRS` entries and the hooks newline normalization could each
be deleted with the suite still green. All are now mutation-tested.

Refs: #90
ADR: 0017

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT

docs/adr/0017-plugin-content-mirror-bridges-apm-to-host-discovery.md

@@ -9,7 +9,9 @@ could not.
 
 **Status: executed (2026-08-13, issue #90).** `scripts/sync-plugin-content.sh` has been run
 against all 6 plugins; flat `agents/`, `skills/`, `commands/` (etc., wherever `.apm/` populates
-them), and a merged `hooks.json` now exist at each plugin root as tracked, generated files.
+them), and a merged hooks file now exist at each plugin root as tracked, generated files. The
+merged hooks file lands at `hooks/hooks.json`, not at the plugin root itself — see the second
+amendment below, which corrects the path this ADR originally recorded.
 
 ## Context
 
@@ -57,8 +59,9 @@ plugins from.
 
 Each plugin root gains a second, generated content category, produced by
 `scripts/sync-plugin-content.sh` (wraps `apm pack --format plugin`, copies the resulting bundle's
-`agents/`, `skills/`, `commands/`, `instructions/`, `extensions/`, and merged `hooks.json` back to
-the plugin root) — same governance status as `.claude-plugin/plugin.json`/`marketplace.json`:
+`agents/`, `skills/`, `commands/`, `instructions/`, `extensions/`, and merged hooks file back to
+the plugin root — the hooks file to `hooks/hooks.json`, per the second amendment below) — same
+governance status as `.claude-plugin/plugin.json`/`marketplace.json`:
 **compiled output of `.apm/`, never hand-edited.**
 
 - `.apm/` remains the sole hand-edited authoring source, unchanged from ADR-0015.
@@ -69,10 +72,21 @@ the plugin root) — same governance status as `.claude-plugin/plugin.json`/`mar
   `plugin.json` is already correctly generated by a separate, already-verified apm code path
   (`build_plugin_manifest`, run in the same `apm pack` invocation); `.mcp.json` is hand-authored
   at the plugin root per ADR-0015 and is not an `.apm/` primitive.
-- Drift is enforced by a pre-push gate (`scripts/sync-plugin-content.sh --check`, wired into
+- Dev-fixture `tests/` directories are excluded too — they are dev-time fixtures no plugin host
+  ever needs to discover, and several reference their own repo root through a hardcoded relative
+  walk-up sized for `.apm/`-nested depth, so a copy one directory level shallower breaks the
+  duplicate and double-runs the original under repo-wide bats discovery. The exclusion is
+  **depth-scoped to `<category>/<name>/tests`**, deliberately: a skill may legitimately ship a
+  directory literally named `tests` as a template asset it scaffolds *from*
+  (`skills/skill-author/assets/templates/tests`, at depth 4). A depth-agnostic `-name tests`
+  matched that too and stripped it, making the mirrored `new-skill.sh` die mid-run on
+  `sed: can't read .../tests/README.md` — the scaffolder seds its way through the template tree
+  file by file. Scaffolding assets survive; fixtures do not.
+- Drift is enforced by a pre-push gate (`scripts/sync-plugin-content.sh --check --all`, wired into
   `.pre-commit-config.yaml` as hook id `check-plugin-content-sync` by a parallel workstream on
   issue #90) — the same enforcement model `check-manifests.sh` already applies to the other
-  compiled-output category.
+  compiled-output category. `--check` alone is not the gate: the script requires either `--all` or
+  an explicit list of plugin directories, and run bare it prints usage and exits 1.
 - Verified two ways before landing: `claude plugin validate --strict` passes on all 6 real
   (non-scratch) plugin directories, and a live behavioral test
   (`claude --plugin-dir plugins/kyberforge -p "list your skills and agents"`) against the real
@@ -125,24 +139,61 @@ explicit `mcpServers` declaration redundant, the way there is for skills/agents/
 the same "don't fight a stable, intentional apm code path" reasoning here would mean shipping a
 plugin manifest known to be missing a field Copilot actually reads.
 
-Given that, `scripts/sync-plugin-content.sh`'s `reinject_mcp_servers()` (line 190, called from
-`sync_one()` at line 269, real syncs only) narrowly re-injects `mcpServers` into
-`.github/plugin/plugin.json` after a real sync, sourced from the plugin's own `.mcp.json`, and
-only when it declares at least one server — matching apm's own Claude-ecosystem builder, which
-omits the field entirely rather than emitting `mcpServers: {}`. This is scoped to one field found
-to be incorrectly stripped, not a reversal of the broader position above: the rejection of
-patching `skills`/`agents`/`commands`/`hooks` pointers still holds, since apm's premise for
-stripping those remains accurate.
+Given that, `scripts/sync-plugin-content.sh`'s `reinject_mcp_servers()`, called from `sync_one()`,
+narrowly re-injects `mcpServers` into `.github/plugin/plugin.json` after `apm pack` runs, sourced
+from the plugin's own `.mcp.json`, and only when it declares at least one server — matching apm's
+own Claude-ecosystem builder, which omits the field entirely rather than emitting
+`mcpServers: {}`. **Both modes re-inject**, not just real syncs: real mode writes into the plugin
+root directly, `--check` into its throwaway copy first, so the manifest diff compares against the
+same content a real sync would actually produce (see the script's own header). A check-mode
+re-injection is what keeps `--check` from reporting permanent phantom drift on every plugin that
+ships an `.mcp.json`. This is scoped to one field found to be incorrectly stripped, not a
+reversal of the broader position above: the rejection of patching
+`skills`/`agents`/`commands`/`hooks` pointers still holds, since apm's premise for stripping those
+remains accurate.
 
 Consequence: if a future apm release corrects the Copilot `mcpServers` omission, `reinject_mcp_servers()`
 and its call site become dead code and should be deleted — nothing else in this ADR depends on the
 reinjection existing beyond working around this specific upstream gap.
 
+Line numbers are deliberately omitted above. An earlier revision of this amendment cited
+`reinject_mcp_servers()` at line 190 and its call site at line 269; both had already moved by the
+next review round of the same PR, and moved again with the edits recorded in the amendment below.
+A function name is stable enough to grep for; a line number in an ADR is stale by the next commit.
+
+## Amendment (2026-08-14): the merged hooks file lands at `hooks/hooks.json`, not the plugin root
+
+As originally executed, `sync-plugin-content.sh` wrote the merged hooks file to
+`plugins/<name>/hooks.json`. That path is scanned by nothing. Claude Code convention-scans
+`hooks/hooks.json`, and the "Plugin Directory Layout" table this ADR's own root-cause analysis
+quotes above says so on the same line it says "All content directories must be at the plugin root,
+not inside `.claude-plugin/`"
+(`plugins/kyberforge/docs/research/docs/claude-code-plugins/configuration.md:100`). The
+implementation read "at the plugin root" and dropped the file there; the row it was reading names
+`hooks/hooks.json`. So this ADR shipped with the contract quoted correctly in its diagnosis and
+violated in its output — the flat mirror bridged skills and agents into discovery and left hooks
+exactly as undiscoverable as before the fix.
+
+The merged file therefore moves to `plugins/<name>/hooks/hooks.json`. A root-level `hooks.json`
+left over from a prior sync is stale output: a real sync deletes it, `--check` reports it as
+drift. The real sync produced exactly these working-tree changes — `plugins/kyberforge/hooks.json`
+and `plugins/lint/hooks.json` deleted, `plugins/kyberforge/hooks/hooks.json` and
+`plugins/lint/hooks/hooks.json` created. Only those two plugins have an `.apm/hooks/` tree, so
+only those two grow a mirrored hooks file at all.
+
+This does **not** reopen the "patch `plugin.json` pointer fields" option rejected above. The move
+needs no `hooks` pointer in `plugin.json`: `hooks/hooks.json` *is* the convention path, so the
+host finds it by auto-discovery, exactly as it finds `skills/` and `agents/`. The rejection stands
+for the reason it was made — apm's `build_plugin_manifest` strips pointer fields unconditionally
+and is right to, because convention directories need no pointer. Writing to the convention path is
+what makes that premise true here rather than something to fight.
+
 ## Consequences
 
 - Git now tracks real, visible duplication: `.apm/skills/<name>/SKILL.md` and
   `skills/<name>/SKILL.md` both exist and must match, likewise `.apm/agents/*.agent.md` vs.
-  `agents/*.agent.md`, and `.apm/hooks/*.json` vs. the merged `hooks.json`. This is an accepted
+  `agents/*.agent.md`, and `.apm/hooks/*.json` vs. the merged `hooks/hooks.json` (see the
+  2026-08-14 amendment above for that path). This is an accepted
   tradeoff of bridging a gap apm itself doesn't close, not a bug — `.apm/` stays the single
   hand-edited source, and the drift gate (`check-plugin-content-sync`) is what keeps the mirror
   honest rather than trusting authors to remember to regenerate it by hand.