AGENTS.md

@@ -9,12 +9,16 @@ This repo is the global AI development configuration repository — the authorit
 
 ## Edit `.apm/`, never the flat mirror
 
-Inside a plugin, `plugins/<name>/.apm/` is the **only** hand-edited content source. Everything else in a plugin root is generated:
+Inside a plugin, `plugins/<name>/.apm/` is the **only** hand-edited source for **plugin content** — the skills, agents, commands, instructions, extensions and hooks a host discovers. Everything in a plugin root that mirrors an `.apm/` primitive, plus both `plugin.json` manifests, is generated:
 
 - `scripts/sync-plugin-content.sh` generates the flat `plugins/<name>/{skills,agents,commands,instructions,extensions}/` directories and the merged `plugins/<name>/hooks/hooks.json` (ADR-0017)
 - `apm pack` generates both per-plugin manifests — `plugins/<name>/.claude-plugin/plugin.json` and `plugins/<name>/.github/plugin/plugin.json` — and **two of the three** root marketplace manifests: `.claude-plugin/marketplace.json` (apm's `claude` output profile) and `.agents/plugins/marketplace.json` (its `codex` profile, a differently-shaped file) (ADR-0015)
 - `scripts/sync-marketplace-mirror.sh` generates the third, `.github/plugin/marketplace.json` — Copilot CLI's legacy manifest path. **No apm output profile targets it**: apm ships exactly two marketplace output profiles, `claude` and `codex` (documented in `plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md`). The mirror is a byte-identical copy of `.claude-plugin/marketplace.json`, gated by the `check-marketplace-mirror-sync` pre-push hook. Do not expect `apm pack` to refresh it — that assumption is exactly the drift this pair exists to prevent
 
+**A plugin root is not wholly generated.** Material that is not an `.apm/` primitive is hand-authored there and no compiler touches it: `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json`, plus per-plugin extras like `plugins/git/config.example.json`, `plugins/gitea/references/` and `plugins/bin/evals/`. Edit those in place — they have no `.apm/` source, and looking for one wastes a search. The rule is per-path, not per-directory: `plugins/<name>/skills/` is generated, `plugins/<name>/docs/` is not. `docs/spec/architecture.md` carries the same carve-out.
+
+One qualification: "hand-authored, untouched" holds only at the plugin *root*. A file placed **inside** a mirrored directory is destroyed — `sync_dir` runs `rm -rf "$dst"` before every copy, so a `README.md` under `plugins/<name>/hooks/` or `plugins/<name>/skills/` is deleted on the next sync whether or not `.apm/` has a counterpart. Put root-level plugin documentation in `docs/`, never in a mirrored directory.
+
 Nothing labels a generated file as generated — `plugins/kyberforge/skills/forge/SKILL.md` is byte-identical to its `.apm/` original, with no marker in either. Check the path before you edit. An edit to the mirror is discarded by the next sync and is reported as drift by the `check-plugin-content-sync` pre-push hook, which is the earliest anyone finds out. Details in `docs/spec/architecture.md`.
 
 ## Prefer plugin skills over raw shell
@@ -35,9 +39,10 @@ Fall back to raw shell only when no skill covers it.
 - Install the `apm` CLI — four pre-push hooks shell out to it: `apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`, and `check-plugin-content-sync` (via `scripts/sync-plugin-content.sh`, which wraps `apm pack`). The first three are bare `apm …` hook entries, so without it the push dies with an unhelpful "command not found". Use `kyberforge:apm-install`, or `curl -sSL https://aka.ms/apm-unix | sh`; verify with `apm --version`.
 - Install `jq` — required by `scripts/check-manifests.sh` and `scripts/sync-plugin-content.sh`, both pre-push. These at least fail loudly (`Error: jq is required but not installed`).
 - Install the `vale` binary — required by the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks. Their `files:` patterns are `.apm/`-scoped: `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` and `^plugins/[^/]+/\.apm/agents/[^/]+\.agent\.md$`. Only the authoring source triggers them — a `SKILL.md` in the generated mirror matches neither pattern, so prose findings surface only when you edit the file you are supposed to be editing. Without the binary the hooks fail with a bare "command not found" and no install pointer. `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or see https://vale.sh/docs/vale-cli/installation/. No `vale sync` needed — the `Kyberforge` styles are committed under `plugins/kyberforge/.apm/skills/{skill-audit,agent-audit}/assets/vale/styles/`, not downloaded packages (see ADR-0014).
+- `vale` is also a **pre-push** dependency, not only pre-commit. `check-vale-style-sync` runs six glob-coverage probes by invoking `vale --config` — they are the only assertions in it that catch a `.vale.ini` glob typo, the failure mode where every text-level check stays clean while vale lints zero files. Missing `vale` is therefore a hard failure there. The opt-out is `CHECK_VALE_STYLE_SYNC_ALLOW_MISSING_VALE=1`, and it is **not** `SKIP=`: the hook still runs and still asserts everything verifiable from file text, but the six probes do not, and its summary says so explicitly — `Vale style sync check passed (text-level only, vale unavailable): … 0 glob probe(s) verified`. Use it only on a machine that genuinely cannot install `vale`, and read that summary line as "the glob axis was not checked", not as a pass.
 - Run `bash tests/run-tests.sh` before considering any change done — it runs every `test-*.sh` script in the repo plus the bats suite (`--bats-only` for just bats). First run auto-initializes the bats submodules; no manual `git submodule update` needed.
 - Pushing runs 12 repo-defined pre-push hooks, not just the test suite — `run-tests` and `check-manifests`, plus generated-content drift gates (`check-plugin-content-sync`, `check-marketplace-mirror-sync`, `check-vale-style-sync`, `check-scope-walkup-sync`), apm's own gates (`apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`), host validators (`validate-plugins`, `validate-marketplace`, both needing the `claude` CLI), and `check-release-needed`. Run `pre-commit run --hook-stage pre-push --all-files` locally — one command, the whole gate. That command reports **14**, not 12: pre-commit's own `meta` hooks, `check-hooks-apply` and `check-useless-excludes`, declare no `stages:` and so run at every stage including this one.
-- `apm-marketplace-check` needs the network. It resolves every `marketplace.packages[]` entry including the remote `mattpocock-skills` ref, and it is `always_run`, so an unreachable network hard-fails the push. `--offline` is not an escape hatch — it still exits 1 on that entry (`No cached refs (offline)`). To push without a network, skip that one hook using pre-commit's own mechanism: `SKIP=apm-marketplace-check git push`. Skip that hook alone — it is the only one whose failure mode is "no network". Every other pre-push hook is a real local check, and adding it to `SKIP` disarms it silently.
+- **Two** pre-push hooks need the network, for one shared reason: root `apm.yml`'s `marketplace.packages[]` contains exactly one remote entry (`mattpocock-skills`, `source: mattpocock/skills`), and resolving it needs a `git ls-remote`. `apm-marketplace-check` resolves every entry and is `always_run`, so it fails with `No cached refs (offline)`. `apm-pack-check-clean` (`apm pack --check-versions --check-clean --dry-run`) re-resolves the same entry and fails with `Error: Git network timeout during ls-remote`. Pinning the entry to an exact version does **not** remove the call — an exact pin still ls-remotes. `--offline` rescues neither. To push without a network, skip both using pre-commit's own mechanism: `SKIP=apm-marketplace-check,apm-pack-check-clean git push`. Skip those two alone — verified under `unshare -rn`, the other ten pre-push hooks pass offline because they are real local checks, and adding one of them to `SKIP` disarms it silently.
 - Author commits with `git:git-commits` — it validates Conventional Commits (enforced at `commit-msg`) for you.
 
 ## Key documents

LESSONS.md

@@ -2,7 +2,7 @@
 
 Patterns observed during development of this repo. Three or more entries on the same pattern → promote to CONTEXT.md (or the relevant instruction file) as a standing rule.
 
-**Graduation rule:** When three or more entries cover the same pattern, the human reviews and promotes it to the appropriate standing location: `CONTEXT.md` for domain-level principles, `core/instructions/coding.md` for coding conventions, `core/instructions/git.md` for git conventions, or `core/instructions/testing.md` for testing conventions. The graduated entries are marked `[graduated → target file]` rather than deleted (audit trail).
+**Graduation rule:** When three or more entries cover the same pattern, the human reviews and promotes it to the appropriate standing location: `CONTEXT.md` for domain-level principles, `core/instructions/coding.md` for coding conventions, `core/instructions/testing.md` for testing conventions, or `core/instructions/subagent-orchestration.md` for delegation conventions. Those four are the whole set — `core/instructions/` holds `coding.md`, `governance.md`, `subagent-orchestration.md` and `testing.md`, and nothing else. Git conventions have no standing file of their own: promote them to `core/instructions/coding.md`, or create a new instruction file deliberately rather than assuming one exists. The graduated entries are marked `[graduated → target file]` rather than deleted (audit trail).
 
 **Who writes here:** The session-handoff skill (Chunk 3) prompts LESSONS.md extraction before closing a session. The human may also write directly.
 
@@ -26,6 +26,8 @@ Issue files frequently referenced "the workflow defined in `docs/notes/skill-imp
 
 The repo CLAUDE.md instructs agents to read CONTEXT.md at session start, but agents skip this in practice — defaulting to reading only what's directly relevant to the immediate prompt (e.g. the skills folder). The governance.md works because `@import` is technically enforced by Claude Code. Fix: (1) add `@CONTEXT.md` to repo CLAUDE.md using `@import` to make it always-loaded; (2) add a "Key decisions" section to CONTEXT.md with one-line resolved-ADR summaries so locked choices are always in context.
 
+**Status (2026-08-14): neither part landed.** Root `CLAUDE.md` imports `@AGENTS.md` only — no `@CONTEXT.md` — and `CONTEXT.md` has no "Key decisions" section. The behavioral hope this entry diagnosed is still the only mechanism in place: `AGENTS.md` carries the line "Read CONTEXT.md at the start of every session in this repo," which is loaded but is itself an instruction, not an import. The proposal above is open work, not a record of a completed change.
+
 ## 2026-05-17 — Instruction rules lose to RLHF defaults without specificity
 
 Behavioral tests (2026-05-17) showed three communication/behavior rules failing: exploratory question format (gave verbose multi-bullet answer instead of 2-3 sentences), file edit intent (asked for clarification instead of stating intent and proceeding), and push confirmation (went straight to tool call instead of asking first). All three rules are present in `providers/claude-code/CLAUDE.md` as one-liner statements. The RLHF-trained defaults (thorough answers, risk-averse clarification seeking, fast execution) consistently outcompete thin rules. Fix: rewrite failing rules with specificity, a counter-example, and a boundary statement — not just a single-line imperative.

docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md

@@ -124,12 +124,13 @@ correction) sorted what they document into three buckets:
   adaptation — closed, merged in #93) and #90 (the actual repo conversion, which also deleted
   `plugin-author`/`marketplace-author` — tracked through to merge; treat #90's own state as the
   authority on whether it has landed, not this line).
-- **`displayName` is gone from all six compiled `plugin.json` files, and `owner.email` from the
-  marketplace manifest — accepted, not overlooked.** `apm.yml` has no key that compiles to either,
-  so the conversion dropped both: every `plugins/<name>/.claude-plugin/plugin.json` now carries
+- **`displayName` is gone from all six compiled `plugin.json` files — accepted, not overlooked.**
+  `apm.yml` has no key that compiles to it: `synthesize_plugin_json_from_apm_yml`
+  (`apm_cli/deps/plugin_parser.py`) emits only `name`, `version`, `description`, `author`,
+  `license`, `homepage`, `repository` and `keywords`, and nothing in `plugin_manifest.py` adds
+  `displayName` afterwards. So every `plugins/<name>/.claude-plugin/plugin.json` now carries
   `author`/`description`/`homepage`/`keywords`/`license`/`name`/`repository`/`version` (plus
-  `mcpServers` for `bin`) and no `displayName`, and `.claude-plugin/marketplace.json`'s `owner`
-  block is `{name, url}` only. Both fields are optional —
+  `mcpServers` for `bin`) and no `displayName`. The field is optional —
   `plugins/kyberforge/docs/research/docs/claude-code-plugins/api-reference.md:14` lists
   `displayName` as `Required: No`, "Human-readable name shown in plugin manager" — which is why
   `claude plugin validate --strict` still passes on all six. The visible cost is that the plugin
@@ -138,16 +139,31 @@ correction) sorted what they document into three buckets:
   `reinject_*` workaround of the kind ADR-0017's amendment reserves for fields apm strips on a
   factually wrong premise, and apm's premise here is simply that the key does not exist in its
   schema.
-- **`mattpocock-skills` is now version-pinned, and the pin is maintained by hand.** Pre-conversion
-  the entry was `{"repo": "mattpocock/skills", "source": "github"}` — an unpinned reference that
-  tracked the upstream default branch, so consumers got whatever was on it at install time. Root
-  `apm.yml` now declares `version: "^1.2.0"` for it, which `apm pack` resolves and freezes into
-  `.claude-plugin/marketplace.json` as `ref: v1.2.3` + an explicit `sha`. Consumers get a
-  reproducible version instead of a moving target, which is the improvement; the cost is that
-  nothing advances it. apm has no version-bump automation (established under "Versioning" in issue
-  #90's plan), so picking up a new upstream release means a human editing the `version:` range in
-  root `apm.yml` and re-running `apm pack`. Left un-bumped, the marketplace pins an ageing release
-  indefinitely and silently.
+- **`owner.email` was dropped by mistake and has been restored (2026-08-14).** An earlier revision
+  of this ADR listed `owner.email` alongside `displayName` as a field `apm.yml` "has no key that
+  compiles to." That was wrong. `apm_cli/marketplace/yml_schema.py:186` defines
+  `_AUTHOR_OBJECT_KEYS = frozenset({"name", "email", "url"})`, and an `email:` under root
+  `apm.yml`'s `marketplace.owner` block was empirically confirmed to compile straight through into
+  `.claude-plugin/marketplace.json`'s `owner`. The key is declared in root `apm.yml` again and the
+  compiled `owner` block is `{name, email, url}`. Only `displayName` is a genuine schema gap; this
+  one was a documentation error that removed working configuration.
+- **`mattpocock-skills` is pinned to an exact version, and the pin is advanced by hand.**
+  Pre-conversion the entry was `{"repo": "mattpocock/skills", "source": "github"}` — an unpinned
+  reference that tracked the upstream default branch, so consumers got whatever was on it at
+  install time. The conversion first replaced that with `version: "^1.2.0"`, which was still not a
+  pin: a caret range has nothing to freeze it, because there is no lockfile for
+  `marketplace.packages[]`. `apm pack` re-resolved the range against upstream on **every** run, so
+  an upstream `v1.2.4` would immediately invalidate the committed `ref`/`sha` and fail
+  `apm-pack-check-clean` with exit 4 — blocking every push in the repo, triggered by a third party
+  at an unrelated moment, with no local change to explain it. Root `apm.yml` therefore declares an
+  exact `version: "1.2.3"`, which `apm pack` freezes into `.claude-plugin/marketplace.json` as
+  `ref: v1.2.3` + an explicit `sha`. Two consequences, both intended: the committed ref/sha is
+  genuinely reproducible and cannot move under the repo, and picking up a new upstream release is a
+  deliberate act — a human edits the `version:` string in root `apm.yml` and re-runs `apm pack`.
+  apm has no version-bump automation (established under "Versioning" in issue #90's plan), so an
+  ageing pin is the accepted cost of a push gate that only fires on this repo's own changes.
+  Note the pin does not make the entry offline-resolvable: an exact version still requires a
+  `git ls-remote`, which is why two pre-push hooks need the network (see `AGENTS.md`).
 - **Caveat on "Status: executed" above:** issue #90's own execution comment flagged, before merge,
   that Claude Code's ability to actually load content out of `.apm/` was unverified — that caveat
   turned out to be a real defect, not a formality: the native installer has zero awareness of

docs/adr/0016-apm-agent-primitive-drops-provider-specific-fields.md

@@ -36,6 +36,9 @@ At **plugin scope only** (destination package has an `apm.yml` at its root — a
 package compiled via `apm compile`), `.apm/agents/<name>.agent.md` carries only `name`,
 `description`, `model`, and the prose body. No `tools:` field, no Claude-only fields, at all.
 
+*(Narrowed by the 2026-08-14 amendment below: `disallowedTools` is admitted as a fifth allowed
+field. `tools:` and every other Claude-only knob remain excluded on the reasoning given here.)*
+
 Absent `tools:` means inherit-all-tools on both harnesses — the one value that is never wrong
 on either target, unlike a present, harness-specific value that is guaranteed wrong on at least
 one of them.
@@ -70,11 +73,48 @@ harness. Tracking the breakage doesn't prevent it, and the chosen decision alrea
 equivalent visibility (a SUGGESTION finding) without ever shipping the wrong value in the first
 place.
 
+## Amendment (2026-08-14): the write fence comes back as a denylist
+
+The decision above generalised from `tools:` to "no tool restriction at all". That over-reached.
+The unportability argument is specific to the **allowlist**: Claude Code reads `tools:` as a
+delimited string of its own tool names, Copilot CLI reads it as a list drawn from its
+alias vocabulary (`execute`/`read`/`edit`/`search`/`agent`/`web`), so one value is wrong on one
+harness. That reasoning stands, and `tools:` stays out of every plugin-scope agent.
+
+A **denylist** has no such conflict.
+`plugins/kyberforge/docs/research/docs/claude-code-plugins/agent-definition.md:39` documents
+`disallowedTools` as a "Denylist applied before `tools`… Takes precedence over `tools`", and — the
+part that matters here — it is **not** in that document's plugin-subagent ignore list. Line 99
+names exactly three fields plugin agents silently ignore: `hooks`, `mcpServers`, `permissionMode`.
+`disallowedTools` is absent from that list, so it is honoured for plugin agents. On the Copilot
+side, the same verbatim-copy behaviour that makes `tools:` dangerous makes `disallowedTools`
+harmless: an unrecognised frontmatter key is inert, and unlike a wrong `tools:` value it cannot
+grant or misroute anything — the worst case is that the fence is absent on that harness, which is
+the status quo the decision above already accepted.
+
+So the read-only orchestrator agents regain their write fence: `gitea-orchestrate`,
+`apm-orchestrate` and `lint-runner` each carry `disallowedTools: Edit, Write, NotebookEdit` plus
+explicit prose in the body stating the agent does not edit files. `git-orchestrate` is deliberately
+excluded — it legitimately declared `edit` before the conversion and still needs to write.
+
+Net position: the allowlist stays dropped for the reason originally given; the specific capability
+that mattered (preventing a read-only orchestrator from writing) is restored by the one mechanism
+that is portable by construction. The consequence below is narrowed accordingly.
+
+Enforcement follows the decision: `agent-audit`'s plugin-scope validator reads its allowlist as
+data from the `apm-agent-allowlist` section of
+`plugins/kyberforge/.apm/skills/agent-audit/references/field-inventory.md`, and that line now reads
+`name description model source_keys disallowedTools`. `disallowedTools` also stays in that file's
+`claude-code-only-fields` list, which is not a contradiction — that list governs whether a field
+may cross the CC/Copilot boundary in a real project/user-scope *pair*, a different question from
+whether a field is safe under verbatim copy in a single vendor-neutral file.
+
 ## Consequences
 
-- Every plugin-scope APM agent loses per-agent tool restriction and any Claude-only capability
+- Every plugin-scope APM agent loses per-agent tool *allowlisting* and any Claude-only capability
   (isolation, maxTurns, effort, memory, permissionMode) until APM ships a real per-target
   integrator for the agent primitive. This is a known, accepted regression, not an oversight.
+  Tool **denial** is not part of that loss — see the 2026-08-14 amendment above.
 - **ADR-0005 is partially superseded** — its plugin-scope clause ("directory containing
   `plugin.json` is plugin scope → both files land in `<root>/agents/`") no longer applies.
   Plugin scope is now "directory containing `apm.yml` → single vendor-neutral file lands in

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

@@ -98,18 +98,29 @@ governance status as `.claude-plugin/plugin.json`/`marketplace.json`:
 
 ## Considered options
 
-**Patch `plugin.json`'s `skills`/`agents`/`commands`/`hooks` fields to point directly at `.apm/`
-paths (rejected).** Claude Code's manifest schema documents these as legitimate override fields
-that accept custom paths —
-`plugins/kyberforge/docs/research/docs/claude-code-plugins/configuration.md` shows a real example
-(`"skills": "./custom/skills/"`, `"agents": ["./custom/agents/reviewer.md"]`), so the host side of
-this would work. Rejected because apm's compiler is not a passive pass-through: `build_plugin_manifest`
-unconditionally strips these keys from every manifest it generates, on the stated assumption that
-convention directories are always host-auto-discovered and therefore never need an explicit
-pointer. Honoring this option would mean post-processing apm's compiled output on every
-`apm pack` run to re-inject fields apm actively removes — fighting a stable, intentional apm code
-path indefinitely — rather than reusing `plugin_exporter.py`'s bundle-export mapping, which already
-does the right thing and only needed its output redirected to a path the installer reads.
+**Patch `plugin.json`'s content-pointer fields to point directly at `.apm/` paths (rejected).**
+Claude Code's manifest schema documents these as legitimate override fields that accept custom
+paths — `plugins/kyberforge/docs/research/docs/claude-code-plugins/configuration.md` shows a real
+example (`"skills": "./custom/skills/"`, `"agents": ["./custom/agents/reviewer.md"]`), so the host
+side of this would work. Rejected because apm never emits such a pointer and would have to be
+worked around on every run to make it do so.
+
+Be precise about the mechanism, because an earlier revision of this ADR overstated it. apm 0.28.0's
+`build_plugin_manifest` (`apm_cli/core/plugin_manifest.py`) does carry a strip loop, but its field
+list is `("agents", "skills", "commands", "instructions")` — `hooks` is **not** in it, and
+`instructions` **is**, which this ADR previously did not mention. More to the point, that loop can
+never fire: the manifest it operates on comes from `synthesize_plugin_json_from_apm_yml`
+(`apm_cli/deps/plugin_parser.py`), which only ever emits `name`, `version`, `description`,
+`author`, `license`, `homepage`, `repository` and `keywords`. The pointer fields are absent from
+apm's output because `apm.yml` has no schema for them, not because apm actively removes them — the
+`pop` loop is defensive dead code against a manifest shape apm does not produce.
+
+The rejection is unaffected by that correction, only its framing. Honoring this option would still
+mean post-processing apm's compiled output on every `apm pack` run to add fields apm's schema has
+no way to express, rather than reusing `plugin_exporter.py`'s bundle-export mapping, which already
+does the right thing and only needed its output redirected to a path the installer reads. What it
+is *not* is a fight against a load-bearing apm code path — the honest statement is that apm has no
+input for these fields, and inventing one downstream is a workaround this ADR did not need.
 
 **Point `marketplace.json`'s `source:` at `apm pack`'s `build/<name>-<version>/` output directly
 (rejected).** Would reuse the bundle exporter's correct mapping without adding a new script.
@@ -121,36 +132,50 @@ source and scans directories; it does not execute a package manager's build comm
 Copying the relevant subset back to the stable `plugins/<name>/` path — where `marketplace.json`
 already points — needed no change to the marketplace source model at all.
 
-## Amendment (2026-08-13): `mcpServers` is narrowly reinjected into Copilot's `plugin.json`
+## Amendment (2026-08-13, revised 2026-08-14): Copilot's `plugin.json` gets an `mcpServers` *path*
 
 PR #95's review (a follow-on to this same issue #90 workstream) found a second field apm's
-compiler strips for the Copilot ecosystem: `build_plugin_manifest` unconditionally removes
-`mcpServers` from every Copilot-ecosystem `plugin.json`, its docstring stating the field is "not
-part of the Copilot plugin manifest schema." That claim is contradicted by this repo's own
-researched documentation — `plugins/kyberforge/docs/research/docs/github-copilot-plugins/
-configuration.md:49` documents `mcpServers` as a valid, optional `plugin.json` field for Copilot.
+compiler drops for the Copilot ecosystem: `build_plugin_manifest` runs
+`manifest.pop("mcpServers", None)` on every Copilot-ecosystem `plugin.json`, its docstring stating
+the field is "not part of the Copilot plugin manifest schema." That claim is contradicted by this
+repo's own researched documentation —
+`plugins/kyberforge/docs/research/docs/github-copilot-plugins/configuration.md:49` documents
+`mcpServers` as a valid, optional `plugin.json` field, typed **"string or object — MCP server
+config path or inline definitions."**
 
-This is not the same situation "Considered options" above rejected. That rejection concerned
-fields apm strips *correctly*, on a stable and accurate premise: convention directories
-(`skills/`, `agents/`, `commands/`) are host-auto-discovered, so an explicit pointer is redundant
-by design. Here, apm's own stated justification for stripping `mcpServers` is factually wrong
-against documented Copilot behavior — there is no host-auto-discovery mechanism that makes an
-explicit `mcpServers` declaration redundant, the way there is for skills/agents/commands. Applying
-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.
+This is not the same situation "Considered options" above rejected. There, apm emits no pointer
+because its schema has no input for one and the host auto-discovers the directories anyway, so
+nothing is missing. Here a field Copilot actually reads is actively removed on a premise that is
+wrong against documented Copilot behavior, and there is no auto-discovery mechanism that makes it
+redundant. Shipping the manifest as apm produces it would ship a manifest known to be incomplete.
 
-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.
+`scripts/sync-plugin-content.sh`'s `reinject_mcp_servers()`, called from `sync_one()`, therefore
+sets `mcpServers` on `.github/plugin/plugin.json` after `apm pack` runs — to the **string
+`".mcp.json"`**, the path form of the documented type, not the resolved server objects. Only when
+the plugin's `.mcp.json` declares at least one server, matching apm's own Claude-ecosystem builder,
+which omits the field entirely rather than emitting `mcpServers: {}`.
+
+**The payload is a path because an inlined object is a credential-leak path.** The original
+implementation copied `.mcp.json`'s resolved `mcpServers` object into the manifest with `jq`. That
+route bypasses apm's own `_sanitize_mcp_servers()` (`apm_cli/core/plugin_manifest.py`), which
+strips credential keys and redacts secret values out of `.mcp.json` precisely because — in its own
+words — "copying them verbatim into a committed `plugin.json` would exfiltrate them into the
+distributed artefact." Today's `.mcp.json` files here carry no `env` block, so nothing leaked; the
+first one that did would have written a live token into a tracked, published manifest, with the
+sanitizer sitting one code path away and never invoked. A path reference cannot carry a secret at
+all: the manifest names a file, and resolution happens in the host at load time. This also matches
+apm's documented posture for MCP secrets — `microsoft-apm/configuration.md:96-98` requires `${VAR}`
+indirection so secrets are "never committed to the manifest."
+
+**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 remains scoped to one field found to be incorrectly dropped. It does not reopen the
+content-pointer option rejected above: those fields stay absent because apm has no schema input for
+them and the host needs no pointer, which is a different situation from a documented field being
+actively removed.
 
 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
@@ -166,13 +191,15 @@ A function name is stable enough to grep for; a line number in an ADR is stale b
 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.
+quotes above says so:
+`plugins/kyberforge/docs/research/docs/claude-code-plugins/configuration.md:100` is the row naming
+`hooks/hooks.json`, six lines below the table's preamble at `:94` — "All content directories must
+be at the plugin root, not inside `.claude-plugin/`". The two are not the same line; an earlier
+revision of this amendment said they were. The implementation read the preamble's "at the plugin
+root" and dropped the file there, without reading the row that names the path. 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
@@ -184,9 +211,11 @@ 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.
+for the reason it was made, once stated accurately — apm emits no pointer field for any of these,
+because `apm.yml` has no key that produces one, and none is needed when content sits at the
+convention path. (`hooks` was never in `build_plugin_manifest`'s strip list at all; see the
+corrected mechanism note under "Considered options".) Writing to the convention path is what makes
+the no-pointer premise true here rather than something to work around.
 
 ## Consequences
 

docs/spec/architecture.md

@@ -32,7 +32,9 @@ Two compilers produce the plugin roots you see in the tree:
 - **`apm pack` compiles the manifests** (ADR-0015). Per plugin: `.claude-plugin/plugin.json` and `.github/plugin/plugin.json`, both generated from `plugins/<name>/apm.yml`. Repo-wide, from the root `apm.yml`'s `marketplace:` block: `.claude-plugin/marketplace.json` (apm's `claude` output profile) and `.agents/plugins/marketplace.json` (its `codex` profile, a differently-shaped file). Those two are the only marketplace outputs apm has profiles for — the third root manifest, `.github/plugin/marketplace.json` (Copilot CLI's legacy path), is a byte-identical mirror of the Claude one maintained by `scripts/sync-marketplace-mirror.sh` and gated by the `check-marketplace-mirror-sync` pre-push hook.
 - **`scripts/sync-plugin-content.sh` compiles the content mirror** (ADR-0017). It wraps `apm pack --format plugin` and copies the resulting bundle's flat `agents/`, `skills/`, `commands/`, `instructions/`, `extensions/`, and merged `hooks/hooks.json` back to the plugin root. Claude Code's installer convention-scans those flat paths and has no `.apm/` awareness whatsoever, so the mirror exists solely to satisfy the host's discovery contract.
 
-`.apm/` is the sole hand-edited authoring source for plugin content. An edit made in the flat mirror is discarded by the next sync and is reported as drift by the `check-plugin-content-sync` pre-push hook. Hand-authored material that is not an `.apm/` primitive — `README.md`, `docs/`, `bin/`, `sources.md`, and `.mcp.json` — lives at the plugin root and is untouched by either compiler.
+`.apm/` is the sole hand-edited authoring source for plugin content. An edit made in the flat mirror is discarded by the next sync and is reported as drift by the `check-plugin-content-sync` pre-push hook. Hand-authored material that is not an `.apm/` primitive — `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json`, and per-plugin extras such as `plugins/git/config.example.json`, `plugins/gitea/references/` and `plugins/bin/evals/` — lives at the plugin **root** and is untouched by either compiler.
+
+That immunity is positional, not by filename. Anything placed *inside* a mirrored directory is destroyed regardless of what it is: `sync_dir` runs `rm -rf "$dst"` before every copy, and `sync_hooks_json` does the same to `hooks/`. A hand-written `README.md` under `plugins/<name>/hooks/` or `plugins/<name>/skills/` is deleted by the next sync with no drift report, because a file with no `.apm/` counterpart is simply absent from the regenerated tree. This has already cost the repo one document — `plugins/kyberforge/hooks/README.md`, since restored to `plugins/kyberforge/docs/hooks.md`. Plugin-root documentation belongs in `docs/`.
 
 ## Governance layer
 
@@ -51,7 +53,9 @@ This repo uses two `AGENTS.md` files as the provider-agnostic source of always-o
 
 Both `CLAUDE.md` files are thin adapters: they import from their respective `AGENTS.md` and add only Claude Code-specific syntax (`@import`, content index paths). They carry no original always-on content.
 
-This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for working in this repo. It imports `AGENTS.md` and `CONTEXT.md`, nothing more. This is distinct from `providers/claude-code/CLAUDE.md`, which is the global config deployed to `~/.claude/`.
+This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for working in this repo. It imports `AGENTS.md` and nothing else; there is no `@CONTEXT.md` import. It is not import-only either: below the import sits a fenced `<!-- rtk-instructions v2 -->` … `<!-- /rtk-instructions -->` block carrying the RTK command-prefix convention, which is tool-specific content with no `AGENTS.md` source. This is distinct from `providers/claude-code/CLAUDE.md`, which is the global config deployed to `~/.claude/`.
+
+`CONTEXT.md` is therefore **not** always-loaded. `AGENTS.md` instructs agents to read it at session start, which is a behavioural instruction, not an `@import` guarantee — `LESSONS.md`'s 2026-05-17 entry proposed adding the import and it was never applied. Treat that entry as open work rather than a record of a landed change.
 
 ## Provider model
 
@@ -59,4 +63,4 @@ This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for
 
 ## Architectural decisions
 
-Key hard-to-reverse decisions are recorded as ADRs in `docs/adr/`. See the index there for rationale on choices like the pull distribution model, copy-not-symlink coupling, and the two-tier CLAUDE.md structure.
+Key hard-to-reverse decisions are recorded as ADRs in `docs/adr/`. There is no index file — the directory holds 17 numbered ADRs whose filenames state their decision, so `ls docs/adr/` is the index. Read a superseding ADR before the one it supersedes: ADR-0015 (apm as the authoring source of truth) supersedes ADR-0001 and moots ADR-0006, and ADR-0017 corrects ADR-0015's host-discovery gap. Entry points for the structure described on this page: ADR-0002 (two-tier CLAUDE.md), ADR-0003 (AGENTS.md as the provider-agnostic entry point), ADR-0015 and ADR-0017 (the two compilers behind the plugin roots).

plugins/bin/README.md

@@ -33,10 +33,12 @@ copilot plugin install ./plugins/bin
 | Component | Path | Description |
 |---|---|---|
 | Skills | `.apm/skills/` → `skills/` | Slash commands available after install |
-| MCP servers | `.mcp.json` | The `obsidian` server (`npx @bitbonsai/mcpvault@latest docs/`), hand-authored at the plugin root and reinjected into both compiled `plugin.json` manifests |
+| MCP servers | `.mcp.json` | The `obsidian` server (`npx @bitbonsai/mcpvault@latest docs/`), hand-authored at the plugin root |
 
 `.apm/` is the authoring source; `skills/` is the generated mirror plugin hosts scan (ADR-0017). This plugin ships no agents. It is the only plugin here with a non-empty `.mcp.json`, which is why its compiled manifests are the only ones carrying an `mcpServers` block.
 
+The two compiled manifests get that block by different routes. `.claude-plugin/plugin.json` gets it from apm itself: `build_plugin_manifest`'s Claude branch calls `collect_mcp_servers`, which reads `.mcp.json`, sanitizes it, and inlines the resulting server objects. `.github/plugin/plugin.json` gets nothing from apm — the Copilot branch drops the field — so `scripts/sync-plugin-content.sh`'s `reinject_mcp_servers()` puts it back, as the **string `".mcp.json"`** rather than the resolved objects. Copilot's manifest schema types the field as "string or object — MCP server config path or inline definitions", and a path reference cannot carry a credential into a committed manifest. See ADR-0017's `mcpServers` amendment.
+
 ## Author
 
 Defame1297

plugins/core/.apm/skills/agentsmd-audit/README.md

@@ -24,7 +24,12 @@ Provide the path to the repo root to audit when invoking.
 | `scripts/validate-drift.sh` | Resolves referenced npm/make commands and file paths against the repo |
 | `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to |
 | `scripts/README.md` | Directory documentation for `scripts/` |
-| `tests/README.md` | Bats test dependency and run instructions |
-| `tests/validate-secrets.bats` | Bats test suite for `scripts/validate-secrets.sh` |
-| `tests/validate-structure.bats` | Bats test suite for `scripts/validate-structure.sh` |
-| `tests/validate-drift.bats` | Bats test suite for `scripts/validate-drift.sh` |
+| `tests/README.md` | (source-only) Bats test dependency and run instructions |
+| `tests/validate-secrets.bats` | (source-only) Bats test suite for `scripts/validate-secrets.sh` |
+| `tests/validate-structure.bats` | (source-only) Bats test suite for `scripts/validate-structure.sh` |
+| `tests/validate-drift.bats` | (source-only) Bats test suite for `scripts/validate-drift.sh` |
+
+Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agentsmd-audit/`) but are
+not present in an installed plugin: `scripts/sync-plugin-content.sh` strips `<category>/<name>/tests`
+when it generates the flat mirror, because these are dev-time fixtures no plugin host needs to
+discover (ADR-0017). Run them from a repo checkout, not from an install.

plugins/core/.apm/skills/provider-adapter-author/README.md

@@ -26,5 +26,10 @@ Provide the path to the provider-specific file to convert (and the target repo r
 | `references/sources.md` | Provenance record — the in-repo ADR precedent this skill's design is modeled on |
 | `scripts/validate-adapter.sh` | Self-check gate: reference to AGENTS.md present, no excessive duplication, adapter stays thin |
 | `scripts/README.md` | Directory documentation for `scripts/` |
-| `tests/README.md` | Bats test dependency and run instructions |
-| `tests/validate-adapter.bats` | Bats test suite for `scripts/validate-adapter.sh` |
+| `tests/README.md` | (source-only) Bats test dependency and run instructions |
+| `tests/validate-adapter.bats` | (source-only) Bats test suite for `scripts/validate-adapter.sh` |
+
+Rows marked **(source-only)** exist in the authoring source (`.apm/skills/provider-adapter-author/`)
+but are not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
+`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
+plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.

plugins/kyberforge/.apm/skills/agent-audit/README.md

@@ -46,12 +46,17 @@ Pass the path to either agent file as the argument.
 | `assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml` | Flags CC-specific "Use proactively" phrasing with no effect in Copilot descriptions |
 | `references/README.md` | Directory documentation for references/ |
 | `references/description-quality.md` | Qualitative guide for borderline description findings |
-| `references/field-inventory.md` | Authoritative list of valid CC and Copilot agent fields |
+| `references/field-inventory.md` | Authoritative field lists read as data by `validate.sh`: valid CC and Copilot agent fields, and the vendor-neutral plugin/APM-scope allowlist |
 | `references/sources.md` | Research provenance for skill content |
 | `scripts/README.md` | Directory documentation for scripts/ |
 | `scripts/validate.sh` | Structural validation script for agent file pairs |
 | `scripts/validate-provenance.sh` | Provenance chain validation script for agent pairs against `sources.md` (plugin root) |
 | `scripts/vale-wrap.sh` | Drop-in `vale` wrapper that works around a frontmatter-description NLP scope limitation |
-| `tests/README.md` | Bats test dependency and run instructions |
-| `tests/validate.bats` | Bats tests for validate.sh |
-| `tests/validate-provenance.bats` | Bats tests for validate-provenance.sh |
+| `tests/README.md` | (source-only) Bats test dependency and run instructions |
+| `tests/validate.bats` | (source-only) Bats tests for validate.sh |
+| `tests/validate-provenance.bats` | (source-only) Bats tests for validate-provenance.sh |
+
+Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agent-audit/`) but are
+not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
+`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
+plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.

plugins/kyberforge/.apm/skills/agent-audit/SKILL.md

@@ -44,13 +44,13 @@ The script accepts either the CC file, the Copilot file, or (at plugin/APM scope
 
 At **project/user scope** it derives the counterpart and runs the existing pair-based checks. Note FAILs and SUGGESTIONs for the `### Structure` and `### Provider safety` report dimensions. Findings about missing fields, bad name format, empty body, or missing frontmatter → `### Structure`. Findings about CC-only fields in a Copilot file, Copilot-only fields in a CC file, body length, or subagent-unavailable tools → `### Provider safety`. A missing counterpart file → `### Pair consistency`.
 
-At **plugin/APM scope** there is no counterpart — the script instead checks the single file's frontmatter against the `apm-agent-allowlist` in `references/field-inventory.md` (`name`, `description`, `model`, `source_keys` — nothing else; `source_keys` is provenance metadata, not a provider-specific field, and is validated separately by `validate-provenance.sh` against `sources.md`). Findings about missing fields, bad name format, name/filename-stem mismatch, empty body, or missing frontmatter → `### Structure`, same as project/user scope. Findings about any field outside the allowlist (e.g. `tools`, or any Claude-only/Copilot-only field carried over from a hand-edit) and body length → `### Provider safety` — but the dimension's meaning shifts here: it is no longer a CC-vs-Copilot field-leakage check, it's a vendor-neutral-field-allowlist check, since `apm compile` verbatim-copies this file's frontmatter to every target and there is no per-target integrator to reconcile a CC-only or Copilot-only field (ADR-0016). `### Pair consistency` never applies at this scope — the script never emits a missing-counterpart FAIL here, because there is nothing to pair by design.
+At **plugin/APM scope** there is no counterpart — the script instead checks the single file's frontmatter against the `apm-agent-allowlist` in `references/field-inventory.md`. Read that section for the current list rather than reciting one here; it is the authoritative source and it changes. As of 2026-08-14 it is `name`, `description`, `model`, `source_keys`, `disallowedTools` — `source_keys` is provenance metadata, not a provider-specific field, and is validated separately by `validate-provenance.sh` against `sources.md`; `disallowedTools` is a denylist, admitted because denying a tool by name is safe under `apm compile`'s verbatim copy in a way the `tools` allowlist is not (ADR-0016's 2026-08-14 amendment, and the rationale recorded alongside the list itself). Findings about missing fields, bad name format, name/filename-stem mismatch, empty body, or missing frontmatter → `### Structure`, same as project/user scope. Findings about any field outside the allowlist (e.g. `tools`, or any Claude-only/Copilot-only field carried over from a hand-edit) and body length → `### Provider safety` — but the dimension's meaning shifts here: it is no longer a CC-vs-Copilot field-leakage check, it's a vendor-neutral-field-allowlist check, since `apm compile` verbatim-copies this file's frontmatter to every target and there is no per-target integrator to reconcile a CC-only or Copilot-only field (ADR-0016). `### Pair consistency` never applies at this scope — the script never emits a missing-counterpart FAIL here, because there is nothing to pair by design.
 
 `vale-wrap.sh` ships inside this skill's own `scripts/` — resolve it relative to this skill's directory the same way `scripts/validate.sh` is resolved above, so the invocation works whether this skill is running from this repo or from an installed plugin cache. Pass no `--config`: handed none, the wrapper loads its own sibling `assets/vale/.vale.ini`, located from the script's path rather than from the cwd. Adding an explicit relative `--config` breaks exactly the case the self-location covers — a resolved script path plus an unresolved config path yields `E100 Runtime error ... does not exist`, exit 2, which the fallback below then misreads as "vale unavailable". At project/user scope, run it against both files of the pair (not just the one passed in); at plugin/APM scope, run it against the single file. `Kyberforge` applies to all of these files via the `**/agents/*.md` glob; `KyberforgeCopilot` applies to any `*.agent.md` file — including the plugin/APM-scope file, which already has that extension — via the `**/*.agent.md` glob, since its one rule (`Use proactively`) flags CC-specific phrasing that's meaningless in a vendor-neutral or Copilot description. Every Vale alert is a `FAIL` — all rules are graded `error` — so report each one in the `### Description` / `### Body` dimensions citing its rule ID (e.g. `KyberforgeCopilot.ProactivePhrase`). Skip and fall back to Step 2 judgment if the `vale` binary is unavailable. If Vale reports `0 files` scanned, treat the pass as NOT RUN — not as clean — and fall back to full Step 2 judgment for the dimensions it would have covered.
 
 `validate-provenance.sh` operates at plugin/APM scope only — it walks up from the agent file's directory the same way `validate.sh` does (nearest ancestor `apm.yml` with a top-level `type:` field; skip a `type:`-less marketplace-only `apm.yml`; stop at `.git` or the filesystem root) and exits 0 silently if that walk doesn't land on a package root, or when no provenance data exists. When it does apply, it validates the chain between the single file's own `source_keys` and the package-scoped `sources.md` (package root — see ADR-0010). Note FAILs from this script for the `### Provenance` dimension — surface them verbatim with Why and Fix.
 
-If the scripts cannot run (Bash denied, python3 unavailable), perform checks manually. At project/user scope: counterpart file exists, required fields present (`name`, `description`, non-empty body), `name` is kebab-case, Copilot CLI `.agent.md` `name` must match filename stem (CC files are exempt — the CC platform does not require name to match filename), no `FILL IN:` placeholders, no CC-only fields in Copilot file, no Copilot-only fields in CC file (read `references/field-inventory.md` for the authoritative field lists). At plugin/APM scope: required fields present (`name`, `description`, non-empty body), `name` is kebab-case and matches the filename stem, no `FILL IN:` placeholders, no frontmatter field outside `name`/`description`/`model`/`source_keys` (read the `apm-agent-allowlist` section of `references/field-inventory.md`; `source_keys` carries provenance metadata, checked separately by `validate-provenance.sh` against `sources.md`).
+If the scripts cannot run (Bash denied, python3 unavailable), perform checks manually. At project/user scope: counterpart file exists, required fields present (`name`, `description`, non-empty body), `name` is kebab-case, Copilot CLI `.agent.md` `name` must match filename stem (CC files are exempt — the CC platform does not require name to match filename), no `FILL IN:` placeholders, no CC-only fields in Copilot file, no Copilot-only fields in CC file (read `references/field-inventory.md` for the authoritative field lists). At plugin/APM scope: required fields present (`name`, `description`, non-empty body), `name` is kebab-case and matches the filename stem, no `FILL IN:` placeholders, no frontmatter field outside the allowlist — read the `apm-agent-allowlist` section of `references/field-inventory.md` for it, do not work from memory (`source_keys` carries provenance metadata, checked separately by `validate-provenance.sh` against `sources.md`).
 
 ## Step 2 — Qualitative checks
 

plugins/kyberforge/.apm/skills/agent-audit/references/field-inventory.md

@@ -25,4 +25,25 @@ target disable-model-invocation user-invocable mcp-servers metadata
 
 ## apm-agent-allowlist
 
-name description model source_keys
+name description model source_keys disallowedTools
+
+Parsing note: `validate.sh` reads the **first** non-empty, non-`#`, non-`---` line under each
+heading as a whitespace-separated token list, and stops there. Keep the token line immediately
+below its heading; explanatory prose goes after it, as here.
+
+Why `disallowedTools` is on a list that is otherwise vendor-neutral, when `tools` is not
+(ADR-0016 and its 2026-08-14 amendment): the two are not symmetric. `tools` is an **allowlist**
+whose vocabulary differs per harness — Claude Code names its own tools, Copilot CLI uses aliases
+(`execute`/`read`/`edit`/`search`/`agent`/`web`) — so a value correct for one is wrong for the
+other, and `apm compile` copies frontmatter verbatim with no per-target integrator to reconcile
+them. `disallowedTools` is a **denylist**, and denying by name is safe under verbatim copy: a name
+the other harness does not recognise denies nothing, so the worst case is that the fence is absent
+there, never that the wrong capability is granted. Claude Code honours it for plugin subagents —
+`docs/research/docs/claude-code-plugins/agent-definition.md:99` names the fields plugin agents
+silently ignore (`hooks`, `mcpServers`, `permissionMode`) and `disallowedTools` is not among them.
+
+`disallowedTools` also appears in `claude-code-only-fields` above, and that stays correct: at
+project/user scope it is still a Claude-only field and must not appear in a Copilot `.agent.md`.
+The two lists answer different questions — "may this field cross the CC/Copilot file boundary" for
+a real pair, versus "is this field safe under verbatim copy to every target" for a single
+vendor-neutral APM file.

plugins/kyberforge/.apm/skills/agent-audit/scripts/validate.sh

@@ -241,10 +241,13 @@ def check_apm_agent_file(fpath, allowlist, stem):
         fail(f"frontmatter still contains template HTML comments (<!-- ... -->) "
              f"— delete them before shipping — {local_fname}")
 
-    # Allowlist: only name/description/model may appear — no tools, no
-    # Claude-only or Copilot-only fields. apm compile verbatim-copies
-    # frontmatter to every target, so anything else is unsafe on at least
-    # one harness (ADR-0016).
+    # Allowlist: the permitted keys are data, read at load time from
+    # references/field-inventory.md's `## apm-agent-allowlist` section — do not
+    # restate them here, or this comment goes stale the next time that line
+    # changes. apm compile verbatim-copies frontmatter to every target, so a key
+    # outside the list is unsafe on at least one harness (ADR-0016). Note the
+    # list admits denylist-shaped restrictions (disallowedTools) but never
+    # allowlist-shaped ones (tools), whose value shape differs per harness.
     fm_keys = get_frontmatter_keys(fm)
     for key in sorted(fm_keys):
         if key not in allowlist:

plugins/kyberforge/.apm/skills/agent-author/README.md

@@ -38,8 +38,16 @@ bash scripts/new-agent.sh security-reviewer ~
 | `assets/templates/claude-code.md` | Annotated Claude Code agent definition template (project/user scope) |
 | `assets/templates/copilot.agent.md.template` | Annotated Copilot CLI agent definition template (project/user scope) |
 | `assets/templates/apm-agent.md` | Annotated vendor-neutral APM agent definition template (plugin/APM scope) |
-| `tests/new-agent.bats` | bats tests for `scripts/new-agent.sh` |
+| `tests/new-agent.bats` | (source-only) bats tests for `scripts/new-agent.sh` |
 | `assets/README.md` | Directory meta-documentation for assets/ |
 | `references/README.md` | Directory meta-documentation for references/ |
 | `scripts/README.md` | Directory meta-documentation for scripts/ |
-| `tests/README.md` | bats dependency instructions and run command |
+| `tests/README.md` | (source-only) bats dependency instructions and run command |
+
+Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agent-author/`) but are
+not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
+`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
+plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. The
+`assets/templates/` rows above are unaffected — the exclusion is depth-scoped to
+`<category>/<name>/tests`, so template trees that themselves contain a `tests/` directory ship
+intact.

plugins/kyberforge/.apm/skills/agent-author/scripts/README.md

@@ -10,4 +10,4 @@ Usage: new-agent.sh <agent-name> <root>
 
 Resolves scope by walking up from `<root>`: a `type:`-bearing `apm.yml` found at or above `<root>` → plugin/APM scope (single file at `<package-root>/.apm/agents/<name>.agent.md`; an `apm.yml` without `type:` is a marketplace-only manifest and is skipped); `<root>` exactly `~` → user scope (`~/.claude/agents/` + `~/.copilot/agents/`); otherwise project scope (`<root>/.claude/agents/` + `<root>/.github/agents/`). Each file is a no-op if it already exists. See `--help` for full usage.
 
-Tests: `tests/new-agent.bats` (requires `bats-support` and `bats-assert`).
+Tests: `tests/new-agent.bats` (requires `bats-support` and `bats-assert`) — source-only. `scripts/sync-plugin-content.sh` strips `<category>/<name>/tests` from the generated mirror (ADR-0017), so this file exists in a repo checkout of `.apm/skills/agent-author/` and not in an installed plugin.

plugins/kyberforge/.apm/skills/skill-audit/README.md

@@ -33,6 +33,11 @@ Provide the path to the skill directory to audit when invoking.
 | `references/description-quality.md` | Spec-grounded rubric for description auditing — loaded when a finding is borderline |
 | `references/body-discipline.md` | Spec-grounded rubric for body discipline auditing — loaded when padding vs necessity is unclear |
 | `references/sources.md` | Provenance record — agentskills.io sources that informed this skill and which files each contributed to |
-| `tests/validate.bats` | Bats test suite for validate.sh |
-| `tests/validate-provenance.bats` | Bats test suite for validate-provenance.sh |
-| `tests/README.md` | Setup instructions for bats-support and bats-assert test dependencies |
+| `tests/validate.bats` | (source-only) Bats test suite for validate.sh |
+| `tests/validate-provenance.bats` | (source-only) Bats test suite for validate-provenance.sh |
+| `tests/README.md` | (source-only) Setup instructions for bats-support and bats-assert test dependencies |
+
+Rows marked **(source-only)** exist in the authoring source (`.apm/skills/skill-audit/`) but are
+not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
+`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
+plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.

plugins/kyberforge/.apm/skills/skill-author/README.md

@@ -46,8 +46,16 @@ If the destination resolves inside an APM package, read `references/deployment-m
 | `assets/templates/references/sources.md` | Sources provenance template for new skills |
 | `assets/templates/assets/README.md` | Placeholder for static assets |
 | `assets/templates/tests/README.md` | Placeholder for test files |
-| `tests/new-skill.bats` | Bats test suite for `scripts/new-skill.sh` |
-| `tests/README.md` | Setup instructions for bats-support and bats-assert test dependencies |
+| `tests/new-skill.bats` | (source-only) Bats test suite for `scripts/new-skill.sh` |
+| `tests/README.md` | (source-only) Setup instructions for bats-support and bats-assert test dependencies |
+
+Rows marked **(source-only)** exist in the authoring source (`.apm/skills/skill-author/`) but are
+not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
+`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
+plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. The
+`assets/templates/tests/README.md` row above is **not** source-only — the exclusion is depth-scoped
+to `<category>/<name>/tests`, so the scaffolding template tree ships intact, which
+`scripts/new-skill.sh` depends on at runtime.
 
 ## Spec reference
 

plugins/kyberforge/docs/README.md

@@ -2,7 +2,11 @@
 
 Plugin documentation. Not read automatically by Claude Code or GitHub Copilot CLI — reference specific files from skill bodies or agent prompts as needed.
 
-This directory currently holds no standalone documents of its own — everything under it is research material.
+| Path | Purpose |
+|------|---------|
+| `hooks.md` | Where this plugin's hooks are authored (`.apm/hooks/`), where they are generated to (`hooks/hooks.json`), and the Claude Code and Copilot CLI schemas |
+
+Everything else under this directory is research material.
 
 ## research/
 

plugins/kyberforge/docs/hooks.md

@@ -0,0 +1,54 @@
+# Hooks
+
+Reference for this plugin's hook definitions: where to edit them, where they end up, and what the
+host reads.
+
+This document lives in `docs/` rather than next to the hooks it describes. `plugins/kyberforge/hooks/`
+is a **generated mirror** — `scripts/sync-plugin-content.sh` runs `rm -rf` on it before every
+rebuild, so any hand-written file placed there is deleted on the next sync with no drift warning
+(a prior copy of this document was lost exactly that way). See ADR-0017.
+
+## Where to edit
+
+Author hooks in `plugins/kyberforge/.apm/hooks/*.json`. `apm pack --format plugin` merges every
+file in that directory into a single `hooks.json`, which `sync-plugin-content.sh` copies to
+`plugins/kyberforge/hooks/hooks.json` — the path Claude Code convention-scans. Never edit the
+mirrored file; the `check-plugin-content-sync` pre-push hook reports it as drift.
+
+## Claude Code structure
+
+`hooks/hooks.json` is read by Claude Code. Structure:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "echo 'tool used'" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Supported events: `PreToolUse`, `PostToolUse`, `Notification`, `Stop`.
+
+Use `${CLAUDE_PLUGIN_ROOT}` to reference scripts inside this plugin — the plugin runs from a cache
+path after install, not its original repo location.
+
+## GitHub Copilot CLI
+
+Copilot reads a differently-shaped `hooks.json`: `version: 1` is required, each entry is
+`type: "command"` with separate `bash` and `powershell` scripts, and the lifecycle points are
+lowercase and differently named (`sessionStart`, `sessionEnd`, `userPromptSubmitted`, `preToolUse`,
+`postToolUse`, `errorOccurred`, `agentStop`). See
+`docs/research/docs/github-copilot-plugins/configuration.md`.
+
+There is no separate Copilot hooks file at this plugin root. An earlier revision of this document
+pointed at `hooks.json` at the plugin root for Copilot; that file was a stale artifact of the
+pre-ADR-0017 sync and was deleted. Both ecosystems now resolve to the single generated
+`hooks/hooks.json`, which is currently empty (`{"hooks": {}}`) — the two schemas would need
+reconciling before any real hook ships to both.