docs(skill-author): route hook token guidance to primitive-author

deployment-modes.md told authors to use ${CLAUDE_PLUGIN_ROOT} in hook
commands. Hook authoring now belongs to primitive-author, which
specifies the target-neutral ${PLUGIN_ROOT}; point there instead.

Refs #94

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KkT7RSDwDbmrM9T34b6sTi

.claude-plugin/marketplace.json

@@ -1,59 +1,59 @@
 {
   "name": "holocron",
   "description": "AI development skills for Claude Code, and for GitHub Copilot through apm — factory, design, implement, review, and cross-cutting workflows.",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "owner": {
     "name": "Defame1297",
     "email": "defame1297@rkdr.net",
-    "url": "https://git.dev.rkdr.net/Defame1297/"
+    "url": "https://git.rkdr.net/Defame1297/"
   },
   "plugins": [
     {
       "name": "kyberforge",
       "description": "Skills and agents for creating, maintaining, and managing an apm plugin marketplace for Claude Code and GitHub Copilot.",
-      "version": "2.0.0",
+      "version": "2.1.0",
       "category": "Developer Tools",
       "source": "./plugins/kyberforge"
     },
     {
       "name": "bin",
       "description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
-      "version": "1.1.8",
+      "version": "1.1.9",
       "category": "Utilities",
       "source": "./plugins/bin"
     },
     {
       "name": "git",
       "description": "Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.",
-      "version": "1.3.8",
+      "version": "1.3.9",
       "category": "Version Control",
       "source": "./plugins/git"
     },
     {
       "name": "gitea",
       "description": "Skills and agents for working with a Gitea forge through its HTTP API — the forge's own objects, as distinct from the local git clone.",
-      "version": "1.3.9",
+      "version": "1.3.10",
       "category": "Version Control",
       "source": "./plugins/gitea"
     },
     {
       "name": "onedev",
       "description": "Skills and agents for working with a OneDev forge through the TOD CLI — the forge's own objects, as distinct from the local git clone.",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "category": "Version Control",
       "source": "./plugins/onedev"
     },
     {
       "name": "core",
       "description": "Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.",
-      "version": "1.1.3",
+      "version": "1.1.4",
       "category": "Productivity",
       "source": "./plugins/core"
     },
     {
       "name": "lint",
       "description": "Skills and agents for configuring and running linters.",
-      "version": "1.1.8",
+      "version": "1.1.9",
       "category": "Developer Tools",
       "source": "./plugins/lint"
     }

.gitmodules

@@ -12,4 +12,4 @@
 	ignore = dirty
 [submodule "docs/wiki"]
 	path = docs/wiki
-	url = git@git.dev.rkdr.net:Defame1297/holocron.wiki.git
+	url = git@git.rkdr.net:Defame1297/holocron.wiki.git

CONTEXT.md

@@ -48,7 +48,31 @@ _Avoid_: agent hygiene
 A reusable slash command defined as a `SKILL.md` file following the
 [Agent Skills open standard](https://agentskills.io), authored at
 `plugins/<plugin>/.apm/skills/<skill>/SKILL.md`.
-_Avoid_: command, prompt, macro
+_Avoid_: command, macro; and "prompt" for a skill — a **Prompt** is a different artifact
+
+**Prompt**:
+A single-intent, user-triggered message with parameters, authored as
+`plugins/<plugin>/.apm/prompts/<name>.prompt.md` — the text a user would otherwise type repeatedly.
+It carries no procedure beyond steering existing skills or agents by name; once it holds reusable
+know-how, bundled files, or anything the model should find on its own, it is a **Skill** in the
+wrong container. This is a house rule, stricter than apm, which frames a prompt as a full workflow.
+_Avoid_: command (the Claude-side deployed form), workflow, macro
+
+**Instruction**:
+A scoped rule authored as `plugins/<plugin>/.apm/instructions/<name>.instructions.md`, applied when
+the agent touches files matching its `applyTo` glob. Omitting `applyTo` makes it always-on in every
+session of every repo that installs the package — a legitimate way for a package to ship guidance to
+consumers, but a deliberate choice, never a default. A rule for this repo alone belongs in
+**AGENTS.md**, not in an instruction.
+_Avoid_: rule (the Claude-side deployed form under `.claude/rules/`), guideline, standard
+
+**Hook**:
+A runtime callback a harness fires inside its own tool loop, authored as one JSON file per concern
+under `plugins/<plugin>/.apm/hooks/` in apm's canonical shape — nested entries, PascalCase events,
+`${PLUGIN_ROOT}` script paths — which apm renders per target. Reach is narrowed in the package's
+`apm.yml` `targets:`, never by filename. The last resort among apm primitives: procedure belongs in
+a **Skill**, and a hook is only for "this must always happen at this event".
+_Avoid_: trigger, callback script (the script is the hook's payload, not the hook)
 
 **apm package**:
 The deployable unit apm builds and installs — one or more skills, agents, hooks, commands, and MCP
@@ -58,6 +82,13 @@ _Avoid_: bundle, module, source tree; and bare "plugin" for the *installable art
 ADR-0024 is an apm package and not a Claude Code plugin. "Plugin" stays correct as a modifier in the
 repo's settled compounds — **Plugin marketplace**, "plugin units", `plugins/`.
 
+**apm primitive**:
+Any content type authored under `plugins/<name>/.apm/` — skills, agents, hooks, instructions, and
+prompts. Skills and agents each have their own author skill; `primitive-author` covers the other
+three, so its name is narrower in practice than the term. `factory-audit` audits all five.
+_Avoid_: component, asset, artifact (unqualified); bare "primitive" when only the three
+non-skill, non-agent types are meant — say "hook, instruction, or prompt"
+
 **Output profile**:
 A named ecosystem format `apm pack` can compile the marketplace manifest into, declared per profile
 under root `apm.yml`'s `marketplace.outputs:`. apm defines `claude` and `codex`; each writes to its
@@ -193,3 +224,8 @@ _Avoid_: namespace, category
   an audit running in the same context as the work it checks shares that work's blind spots. The
   recheck belongs to `factory-audit`, not to `forge`, which routes only to the author
   skills and never to an audit.
+- "prompt" meant both apm's `.prompt.md` primitive and, loosely, any slash command or a skill — resolved:
+  a **Prompt** is the `.prompt.md` primitive under the house rule above. apm calls a prompt "a
+  callable program for an LLM", but on Claude it deploys as a model-invocable command with fewer
+  frontmatter keys than a skill, and Codex receives nothing. A fat prompt is a worse skill on every
+  harness, so the procedure goes in the skill and the prompt only steers it.

apm.yml

@@ -1,5 +1,5 @@
 name: holocron
-version: 0.5.0
+version: 0.5.2
 description: AI development skills for Claude Code, and for GitHub Copilot through apm — factory, design, implement, review, and cross-cutting workflows.
 license: MIT
 
@@ -16,17 +16,17 @@ targets:
   - claude
 dependencies:
   apm:
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
+    - git: git@git.rkdr.net:Defame1297/holocron.git
       path: plugins/bin
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
+    - git: git@git.rkdr.net:Defame1297/holocron.git
       path: plugins/core
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
+    - git: git@git.rkdr.net:Defame1297/holocron.git
       path: plugins/git
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
+    - git: git@git.rkdr.net:Defame1297/holocron.git
       path: plugins/gitea
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
+    - git: git@git.rkdr.net:Defame1297/holocron.git
       path: plugins/kyberforge
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
+    - git: git@git.rkdr.net:Defame1297/holocron.git
       path: plugins/lint
     # TOD's skills arrive transitively through this wrapper rather than as a
     # direct entry, so the marketplace and this repo consume onedev by the same
@@ -38,7 +38,7 @@ dependencies:
     # `apm install` fails, which includes the copy kyberforge's SessionStart
     # hook runs on launch. Accepted deliberately: this branch is merging
     # immediately.
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
+    - git: git@git.rkdr.net:Defame1297/holocron.git
       path: plugins/onedev
   mcp: []
 
@@ -61,7 +61,7 @@ dependencies:
 # an apm mechanic.
 executables:
   allow:
-    kyberforge#2.0.0:
+    kyberforge#2.1.0:
       hooks: true
       bin: true
 
@@ -71,11 +71,11 @@ marketplace:
   # top-level apm.yml description:/version: above are NOT inherited into the
   # compiled output despite being used elsewhere (e.g. by `apm audit`).
   description: AI development skills for Claude Code, and for GitHub Copilot through apm — factory, design, implement, review, and cross-cutting workflows.
-  version: 0.5.0
+  version: 0.5.2
   owner:
     name: Defame1297
     email: defame1297@rkdr.net
-    url: https://git.dev.rkdr.net/Defame1297/
+    url: https://git.rkdr.net/Defame1297/
 
   # Default tag pattern used to resolve version ranges for each package.
   build:

docs/adr/0019-session-start-hook-keeps-the-apm-install-current.md

@@ -124,6 +124,9 @@ A test pins the reference.
 > `plugins/kyberforge/hooks/` no longer exists at all — so `${CLAUDE_PLUGIN_ROOT}/hooks/...` still
 > names a path with nothing at it, now because the directory is gone rather than because a sync
 > emptied it. `tests/test-apm-current-hook.sh` still pins the literal string.
+>
+> *Superseded in part by the 2026-09-28 amendment below: the token is now `${PLUGIN_ROOT}`. The
+> `.apm/`-path conclusion is unchanged.*
 
 **Session startup gets slower when the install is stale.** Measured: ~0.7 s for the `apm outdated`
 check when everything is current, ~10.4 s when six packages are behind and the refresh runs. The
@@ -234,6 +237,30 @@ no hook at all, for the reasons already documented in `plugins/kyberforge/docs/h
 > lockfile there is nothing for `apm update` to refresh, so exiting silently is the correct
 > behaviour rather than a defensive measure aimed at a second installer. The Copilot CLI sentence is
 > unaffected.
+>
+> *The Copilot CLI sentence is superseded by the 2026-09-28 amendment below.*
+
+> **Amendment (2026-09-28) — target-neutral token; the hook reaches Copilot and Codex, accepted.**
+> Two corrections from the apm 0.28.0 research pass behind `primitive-author` (issue #94;
+> `plugins/kyberforge/docs/research/docs/microsoft-apm/hooks-primitive-schema.md`).
+>
+> *The token.* `hooks.json` now references `${PLUGIN_ROOT}/.apm/hooks/check-apm-current.sh`. apm
+> documents `${PLUGIN_ROOT}` as its target-neutral token and rewrites it exactly as it rewrites
+> `${CLAUDE_PLUGIN_ROOT}`: two scratch packages differing only in the token deploy byte-identical
+> `SessionStart` entries, matching the one committed in `.claude/settings.json`. The `.apm/`-path
+> rule above is unchanged, and `tests/test-apm-current-hook.sh` pins the new literal.
+>
+> *The reach.* "Copilot CLI sees no hook at all" was wrong for apm installs. `targets:` is
+> package-wide, and kyberforge declares `claude`, `copilot` and `codex`, so apm also writes the hook
+> to `.github/hooks/kyberforge-hooks.json` — event renamed to `sessionStart`, path rewritten,
+> `version: 1` added, the nested Claude shape otherwise passed through unreshaped — and merges it
+> into `.codex/hooks.json` whenever `.codex/` exists. Whether Copilot CLI executes a nested entry or
+> honours `matcher` is unverified. This is **accepted**: the hook's behaviour is Claude-specific (the
+> `startup` matcher, `CLAUDE_PROJECT_DIR`, the `reloadSkills` output) and the `apm.lock.yaml` guard
+> keeps it inert where there is nothing to refresh. Keeping it Claude-only the apm-native way would
+> need a separate package declaring `target: claude` — the seventh-plugin alternative below, still
+> rejected as disproportionate — because per-file routing (`claude-hooks.json`) is deprecated and
+> narrowing kyberforge's own `targets:` would drop its skills from Copilot and Codex.
 
 **`scripts/git-hooks/` is now empty.** `post-push` and `test-post-push.sh` are deleted.
 `install.sh`'s copy block is generic and is kept; `test-git-hooks-install.sh` now synthesizes its

docs/adr/0020-skill-description-and-body-context-contract.md

@@ -414,6 +414,56 @@ and rises to a blocking ERROR the moment a resolving sibling joins it. The reaso
 the point of enforcement in `_add()`'s docstring in `scripts/skill-size-check.sh` and its two
 mirrored copies, and the verdict table in `docs/spec/gates.md` states the corrected shape.
 
+## Amendment (2026-09-22): body-level routing targets are resolved too
+
+The Decision section's routing-target resolver (`boundary_targets()` / `unresolved_targets()`) reads
+the **description** only. A target named in the **body** — a dispatch table row, a "run X" step, both
+routine in a 900-word procedure — was checked by nothing. Two real instances shipped before either
+was caught: `bin/write-docs` routed twice to a deleted `to-prd` skill, and `bin/triage` told an agent
+to run a nonexistent `/setup-matt-pocock-skills`. Both were found by reading, not by a gate, during
+the #99 retrofit and its follow-up audit; both were fixed in `03abcff`. **The fix this amendment
+records is the gate, not those two edits** (issue #124).
+
+The body gate is a **separate, narrower** extractor (`body_targets()` /
+`unresolved_body_targets()`), not the description resolver reused at wider scope. The description
+resolver's sentence-level heuristics — `BOUNDARY_MARKER`, the follower test, in-sentence
+corroboration — are tuned for a one-to-three-sentence routing clause and misfire on dispatch-table
+and procedure prose in both directions: under-firing on a table row that carries no "do not" /
+"instead", over-firing on a procedure step naming a file, a CLI verb or a config key exactly the way
+a route names a skill. Retuning those heuristics for the body genre was considered and rejected as
+the harder half of the problem, with a materially worse cost of getting it wrong (a body is loaded
+on every invocation, so a false-positive-prone body gate is felt far more often than a
+false-positive-prone description gate).
+
+So the body gate reads **only** explicit route notation — `/name` and backticked-or-slash-prefixed
+`-> name` / `→ name` — already the description gate's own unconditionally-blocking tier, and nothing
+softer: no SUGGESTION tier, no bare-word forms, no corroboration. Two further restrictions, both
+earned by a real corpus false positive rather than assumed up front:
+
+- **the target must be hyphenated**, even in notation. `` `/fork` `` (`forge/SKILL.md`, citing
+  Claude Code's own `/fork` subagent command) and `` `/name` `` (`skill-author/SKILL.md`, a
+  placeholder for the skill's own name) are real corpus citations of a tool or a placeholder, not
+  routes, and both hard-FAILed with no escape hatch before this restriction. This is the same
+  "single-word targets are ordinary English" trade the Decision section already makes for the bare
+  form, extended to notation because the body genre has no boundary-sentence signal to fall back on;
+- **a bare hyphenated word after any arrow is not notation.** The description gate's own bare-arrow
+  sweep (`NOTATION_ARROW`) reads ordinary process-chain prose as a route: `caveman`'s "Inline obj
+  prop -> new ref -> re-render." dangled to `re-render` under it. The body gate uses `ARROW_MARKED`
+  instead, which requires the target to be backticked or slash-prefixed — true of the one real
+  historical target (`` -> `to-prd` ``, confirmed against `03abcff`'s diff), so this costs no real
+  coverage;
+- a target immediately preceded by `<` is a closing tag (`</what-to-do>`, `<supporting-info>` — this
+  repo's own `grill-with-docs/SKILL.md` uses these as prompt section delimiters), not `/name`
+  notation, and is discarded on that basis alone.
+
+Both consumers — `scripts/skill-size-check.sh` and `factory-audit/scripts/lib-checks-skill.sh` —
+call the shared functions independently over the same `known_targets()` universe the description
+check already computed, so a body target folds into the existing "DID NOT RUN" INFO tier rather than
+adding a second one. `tests/test-adr0020-targets.sh` pins the two live true positives, all three
+guards above, and the fenced-code-block mask; the corpus-wide dangling assertion now covers body
+targets the same way it already covered description ones. `docs/spec/gates.md`'s "Body-level routing
+targets" section states the enforced shape in full.
+
 ## Consequences
 
 **Editing any non-compliant skill now requires retrofitting it first.** At decision time, 30 of 39

docs/adr/0029-prompts-are-thin-user-triggered-steering-messages.md

@@ -0,0 +1,62 @@
+# Prompts are thin, user-triggered steering messages; procedure belongs in a skill
+
+**Status: accepted (2026-09-28).** Refs #94. Sets the house rule that `primitive-author` enforces
+when it writes a `.prompt.md`, and that `factory-audit` checks in its prompt flow.
+
+A **Prompt** (the term is in `CONTEXT.md`) is a single-intent, user-triggered message with
+parameters. It is the text a user would otherwise type again and again. It carries no procedure
+beyond steering existing skills or agents by name. Once it holds reusable know-how, bundled files,
+or anything the model should find on its own, it is a **Skill** in the wrong container.
+
+This is stricter than apm. apm's docs call a prompt "a callable program for an LLM", and 0.28.0
+scaffolds one as a numbered-steps workflow (`apm_cli/workflow/discovery.py`). On every harness this
+repo targets, a prompt with a full workflow in it is a worse skill:
+
+- **Claude Code.** Custom commands have been merged into skills. "Both create `/deploy` and work
+  the same way", and both are model-invocable by default (code.claude.com/docs/en/skills.md).
+  apm 0.28.0 keeps only `description`, `allowed-tools`, `model`, `argument-hint` and `input` for
+  Claude (`_PRESERVED_COMMAND_KEYS`) and drops `disable-model-invocation`. A deployed prompt is
+  therefore a model-visible skill with fewer frontmatter keys, and it cannot be made user-only.
+- **Copilot / VS Code.** Prompt files are marked deprecated for Agent Host, and VS Code offers a
+  migration to agent skills.
+- **Codex.** Codex receives no prompts at all.
+
+The one job a prompt does better than a skill is a short, parameterised "do this now, using X and Y"
+message, where `input:` → `$arguments` is the whole point.
+
+## Description contract
+
+A prompt's `description` is one plain, human-facing sentence that names the skills or agents it
+steers. For example: "Review the current PR with `gitea-prs` and `factory-audit`, then summarise."
+It has no "Use when…" trigger clause and no `Not X -> Y` boundary clause. This is the same shape
+`factory-audit` already applies to `disable-model-invocation: true` skills. Without a trigger clause,
+the router has little reason to pick the prompt over the skills it wraps. So when the model routes,
+it tends to reach the real capability.
+
+**Unverified:** how strongly Claude avoids routing to a description with no trigger clause. The
+contract lowers the chance of the model invoking the prompt, but does not prevent it. If it does
+happen, the cost is bounded: the prompt is a thin wrapper that calls the right skills anyway.
+
+## Enforcement
+
+- **`primitive-author`.** The prompt reference opens with a boundary gate. A request that carries
+  procedure is redirected to `skill-author`.
+- **`factory-audit`, script checks.**
+  - `description` is present and non-empty (FAIL).
+  - It is 250 characters or fewer (SUGGESTION).
+  - It has no "Use when" trigger clause (SUGGESTION).
+- **`factory-audit`, judgment step.** A body that clearly carries reusable procedure is a FAIL. A
+  borderline body is a SUGGESTION. There is deliberately no line-count or heading heuristic: the
+  call is made by reading the content, because any threshold misfires.
+
+## Considered options
+
+- **Fat workflow prompts as peers of skills (rejected).** This follows apm's framing. But every
+  "make me a command" request becomes a coin flip between two near-identical containers. The prompt
+  also carries worse metadata on Claude and does not arrive on Codex.
+- **The full ADR-0020 description contract for prompts (rejected).** A trigger clause and a boundary
+  clause would make prompts route well. That actively invites the model to invoke the prompt, which
+  contradicts "user-triggered".
+- **Skill-by-default with prompts as a grudging exception (superseded during the grill).** This
+  framed a prompt as a weaker skill competing for the same job. Giving it a distinct role, a thin
+  caller over skills, is a boundary that can be checked, which "prefer skills" is not.

docs/spec/gates.md

@@ -360,6 +360,68 @@ at a real sentence end. **Read the second bullet forward as well as back:** a ba
 after a dotted filename is now extracted, resolved, and a blocking ERROR when it dangles, where the
 same clause used to pass unchecked in silence.
 
+### Body-level routing targets (issue #124)
+
+Everything above resolves targets named in the **description** — the one field `boundary_targets()`
+and `unresolved_targets()` read. Until issue #124, a target named in the **body** — a dispatch table
+or a "run X" step, both routine in a 900-word procedure — was checked by nothing: `bin/write-docs`
+routed twice to a deleted `to-prd` skill and `bin/triage` told an agent to run a nonexistent
+`/setup-matt-pocock-skills`, and both were found by reading, not by any gate (fixed in `03abcff`;
+the gate itself is the ask this section documents).
+
+`body_targets()` / `unresolved_body_targets()` (`lib-boundary-resolver.sh`) are a **separate,
+narrower** extractor, not a reuse of the description one at wider scope. A body is dispatch-table
+and procedure prose, not a one-to-three-sentence routing clause, so `BOUNDARY_MARKER`, the follower
+test and in-sentence corroboration all misfire on it in both directions — under-firing on a table
+row that carries no "do not"/"instead", over-firing on a procedure step that names a file, a CLI verb
+or a config key exactly the way a route names a skill. So the body gate reads only **notation**,
+already the description gate's own "always blocks" tier, and nothing softer:
+
+| Form | Pattern | Requires |
+|---|---|---|
+| `/name` | `NOTATION_SLASH` | a hyphen in `name`; not preceded by `<` |
+| `-> name` / `→ name` | `ARROW_MARKED` | the name **backticked or slash-prefixed** — `NOTATION_ARROW`'s bare form is not used here |
+
+Both constraints exist because the corpus, not intuition, said so — each is a real false positive
+this gate produced once and was narrowed to remove:
+
+- **No SUGGESTION tier, no continuation, one arrow per target.** Both forms are notation, and
+  notation is unconditionally blocking — there is no ambiguous prose reading left to soften, so
+  there is nothing to report at a softer tier. `CONT_MARKED`/`CONT_ANY` are not run either, so
+  `-> \`a\` or \`b\`` resolves only `a`, same as the one-arrow-one-target convention **#107** already
+  states for descriptions — enforced here by construction instead of by a second SUGGESTION.
+- **A bare hyphenated word after any arrow is not notation here.** `NOTATION_ARROW` (used for the
+  description gate's own `Not X -> name` sweep) matches a bare `-> name` unconditionally, and a body
+  is full of ordinary arrow prose that is not a route: `caveman`'s own `Inline obj prop -> new ref ->
+  re-render.` read as a dangling route to `re-render` under that pattern. `ARROW_MARKED` requires the
+  target to be backticked or slash-prefixed, which the one real historical target (`` -> `to-prd` ``,
+  per `03abcff`'s diff) already was, so the narrowing costs no real coverage.
+- **A single-word target is discarded, even in notation.** `` `/fork` `` (`forge/SKILL.md`,
+  contrasting `context: fork` with Claude Code's own `/fork` subagent command) and `` `/name` ``
+  (`skill-author/SKILL.md`, "the user types `/name`" — a placeholder for the skill's *own* name, not
+  a route) are both real corpus citations of a tool or a placeholder, not routes, and both hard-FAILed
+  with no escape hatch before the hyphen requirement was added. This is a real, accepted recall loss:
+  a body dispatch entry to a genuinely single-word skill (`forge`, `research`, `triage`, `tdd`,
+  `prototype`) cannot be checked through this extractor. Same trade the description gate already
+  makes for the *bare* form (the known gap above), extended here to notation as well because the body
+  genre has no boundary-sentence signal to lean on instead.
+- **A name immediately preceded by `<` is a closing tag, not a route.** `grill-with-docs/SKILL.md`
+  uses XML-style prompt delimiters (`<what-to-do>...</what-to-do>`, `<supporting-info>...`), and
+  `</what-to-do>` is indistinguishable from `/what-to-do` notation by every other rule above. No route
+  is ever written directly after `<` in this corpus, so the guard costs nothing else.
+
+Fenced code blocks are masked first (`mask_fenced()`, the same masking `gotcha_stats()` and the
+references/-pointer check already use): an illustrative ` ```/some-skill``` ` in `skill-author` or
+`factory-audit` — which document this very notation — is not a live dispatch entry.
+
+Both consumers agree by construction: `scripts/skill-size-check.sh` and
+`factory-audit/scripts/lib-checks-skill.sh` each call `body_targets()`/`unresolved_body_targets()`
+independently, over the same `known_targets()` universe the description check already computed, so
+the "DID NOT RUN" INFO tier covers both description and body targets in one message rather than
+firing twice. `tests/test-adr0020-targets.sh`'s "body-level routing targets (issue #124)" section
+pins both the two live true positives and every guard above; the corpus-wide dangling assertion
+(`EXPECTED_DANGLING`) covers body targets the same way it already covered description ones.
+
 ### SUGGESTION-only checks
 
 Deterministic to measure, judgment to act on:

plugins/bin/README.md

@@ -9,7 +9,7 @@ apm is the only supported install path (ADR-0024). Declare this package in the c
 ```yaml
 dependencies:
   apm:
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
+    - git: git@git.rkdr.net:Defame1297/holocron.git
       path: plugins/bin
 ```
 
@@ -19,7 +19,7 @@ Then:
 apm install
 ```
 
-The entry above is unpinned and tracks the remote's default branch — add `ref: <tag>` to pin a release. Registering the catalogue instead (`apm marketplace add git@git.dev.rkdr.net:Defame1297/holocron.git --name holocron`) gets you the `bin@holocron` short name, but writes to `~/.apm/marketplaces.json` at user scope; the git+path object needs nothing beyond the manifest.
+The entry above is unpinned and tracks the remote's default branch — add `ref: <tag>` to pin a release. Registering the catalogue instead (`apm marketplace add git@git.rkdr.net:Defame1297/holocron.git --name holocron`) gets you the `bin@holocron` short name, but writes to `~/.apm/marketplaces.json` at user scope; the git+path object needs nothing beyond the manifest.
 
 **Native plugin installs do not work.** This package ships no per-plugin manifest and no flat content directories, so a host that installs it natively gets zero skills — and Claude Code raises no error while doing it (ADR-0024).
 

plugins/bin/apm.yml

@@ -1,13 +1,13 @@
 name: bin
-version: 1.1.8
+version: 1.1.9
 description: Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.
 author:
   name: Defame1297
   email: defame1297@rkdr.net
-  url: https://git.dev.rkdr.net/Defame1297/
+  url: https://git.rkdr.net/Defame1297/
 license: MIT
-homepage: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/bin
-repository: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/bin
+homepage: https://git.rkdr.net/Defame1297/holocron/src/branch/main/plugins/bin
+repository: https://git.rkdr.net/Defame1297/holocron/src/branch/main/plugins/bin
 keywords:
   - utility
   - diagnostics

plugins/core/.apm/skills/provider-adapter-author/tests/validate-adapter.bats

@@ -298,14 +298,14 @@ EOF
 
 @test "a doubled UTF-8 BOM does not hide the @import line" {
     ADAPTER="$TMPDIR/CLAUDE.md"
-    python3 -c "import sys; open(sys.argv[1], 'wb').write(('@AGENTS.md\n').encode('utf-8'))" "$ADAPTER"
+    python3 -c "import sys; open(sys.argv[1], 'wb').write(('\ufeff\ufeff@AGENTS.md\n').encode('utf-8'))" "$ADAPTER"
     run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
     assert_success
 }
 
 @test "a BOM in front of a mid-file @import line does not hide it" {
     ADAPTER="$TMPDIR/CLAUDE.md"
-    python3 -c "import sys; open(sys.argv[1], 'wb').write(('# Claude notes\n\n@AGENTS.md\n').encode('utf-8'))" "$ADAPTER"
+    python3 -c "import sys; open(sys.argv[1], 'wb').write(('# Claude notes\n\n\ufeff@AGENTS.md\n').encode('utf-8'))" "$ADAPTER"
     run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
     assert_success
 }

plugins/core/README.md

@@ -9,7 +9,7 @@ apm is the only supported install path (ADR-0024). Declare this package in the c
 ```yaml
 dependencies:
   apm:
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
+    - git: git@git.rkdr.net:Defame1297/holocron.git
       path: plugins/core
 ```
 
@@ -19,7 +19,7 @@ Then:
 apm install
 ```
 
-The entry above is unpinned and tracks the remote's default branch — add `ref: <tag>` to pin a release. Registering the catalogue instead (`apm marketplace add git@git.dev.rkdr.net:Defame1297/holocron.git --name holocron`) gets you the `core@holocron` short name, but writes to `~/.apm/marketplaces.json` at user scope; the git+path object needs nothing beyond the manifest.
+The entry above is unpinned and tracks the remote's default branch — add `ref: <tag>` to pin a release. Registering the catalogue instead (`apm marketplace add git@git.rkdr.net:Defame1297/holocron.git --name holocron`) gets you the `core@holocron` short name, but writes to `~/.apm/marketplaces.json` at user scope; the git+path object needs nothing beyond the manifest.
 
 **Native plugin installs do not work.** This package ships no per-plugin manifest and no flat content directories, so a host that installs it natively gets zero skills — and Claude Code raises no error while doing it (ADR-0024).
 

plugins/core/apm.yml

@@ -1,13 +1,13 @@
 name: core
-version: 1.1.3
+version: 1.1.4
 description: Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.
 author:
   name: Defame1297
   email: defame1297@rkdr.net
-  url: https://git.dev.rkdr.net/Defame1297/
+  url: https://git.rkdr.net/Defame1297/
 license: MIT
-homepage: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/core
-repository: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/core
+homepage: https://git.rkdr.net/Defame1297/holocron/src/branch/main/plugins/core
+repository: https://git.rkdr.net/Defame1297/holocron/src/branch/main/plugins/core
 keywords:
   - agents-md
   - documentation

plugins/git/README.md

@@ -9,7 +9,7 @@ apm is the only supported install path (ADR-0024). Declare this package in the c
 ```yaml
 dependencies:
   apm:
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
+    - git: git@git.rkdr.net:Defame1297/holocron.git
       path: plugins/git
 ```
 
@@ -19,7 +19,7 @@ Then:
 apm install
 ```
 
-The entry above is unpinned and tracks the remote's default branch — add `ref: <tag>` to pin a release. Registering the catalogue instead (`apm marketplace add git@git.dev.rkdr.net:Defame1297/holocron.git --name holocron`) gets you the `git@holocron` short name, but writes to `~/.apm/marketplaces.json` at user scope; the git+path object needs nothing beyond the manifest.
+The entry above is unpinned and tracks the remote's default branch — add `ref: <tag>` to pin a release. Registering the catalogue instead (`apm marketplace add git@git.rkdr.net:Defame1297/holocron.git --name holocron`) gets you the `git@holocron` short name, but writes to `~/.apm/marketplaces.json` at user scope; the git+path object needs nothing beyond the manifest.
 
 **Native plugin installs do not work.** This package ships no per-plugin manifest and no flat content directories, so a host that installs it natively gets zero skills and zero agents — and Claude Code raises no error while doing it (ADR-0024).
 

plugins/git/apm.yml

@@ -1,13 +1,13 @@
 name: git
-version: 1.3.8
+version: 1.3.9
 description: Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.
 author:
   name: Defame1297
   email: defame1297@rkdr.net
-  url: https://git.dev.rkdr.net/Defame1297/
+  url: https://git.rkdr.net/Defame1297/
 license: MIT
-homepage: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/git
-repository: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/git
+homepage: https://git.rkdr.net/Defame1297/holocron/src/branch/main/plugins/git
+repository: https://git.rkdr.net/Defame1297/holocron/src/branch/main/plugins/git
 keywords:
   - git
   - vcs

plugins/gitea/apm.yml

@@ -1,13 +1,13 @@
 name: gitea
-version: 1.3.9
+version: 1.3.10
 description: Skills and agents for working with a Gitea forge through its HTTP API — the forge's own objects, as distinct from the local git clone.
 author:
   name: Defame1297
   email: defame1297@rkdr.net
-  url: https://git.dev.rkdr.net/Defame1297/
+  url: https://git.rkdr.net/Defame1297/
 license: MIT
-homepage: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/gitea
-repository: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/gitea
+homepage: https://git.rkdr.net/Defame1297/holocron/src/branch/main/plugins/gitea
+repository: https://git.rkdr.net/Defame1297/holocron/src/branch/main/plugins/gitea
 keywords:
   - gitea
   - issues

plugins/kyberforge/.apm/hooks/hooks.json

@@ -4,7 +4,7 @@
       {
         "hooks": [
           {
-            "command": "${CLAUDE_PLUGIN_ROOT}/.apm/hooks/check-apm-current.sh",
+            "command": "${PLUGIN_ROOT}/.apm/hooks/check-apm-current.sh",
             "timeout": 380,
             "type": "command"
           }

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

@@ -1,13 +1,13 @@
 ---
 name: factory-audit
 description: >
-  Use when the user wants a skill directory or agent definition audited,
-  including "is this ready to ship", or after hand-editing one outside its
-  author skill. Not applying skill fixes -> skill-author. Not applying agent
-  fixes -> agent-author.
+  Use when a skill, agent, or apm hook, instruction or prompt needs auditing,
+  or "is this ready to ship". Not fixing a skill -> skill-author.
+  Not fixing an agent -> agent-author.
+  Not fixing a hook, instruction or prompt -> primitive-author.
 allowed-tools: Bash Read
 metadata:
-  version: "1.0.4"
+  version: "1.1.1"
   category: factory
   source_keys:
     - agentskills-home
@@ -20,6 +20,8 @@ metadata:
     - claude-code-subagents-docs
     - context7-github-en-copilot
     - github-custom-agents-configuration
+    - apm-cli-installed-source
+    - apm-docs-llms-full
 ---
 
 ## Gotchas
@@ -30,21 +32,24 @@ metadata:
 
 ## Step 0 — Dispatch
 
-Resolve the flow from the target path **before running anything**. The two flows run different validators over different dimension vocabularies, so dispatching after Step 1 means the wrong validator has already produced the wrong findings. The rows mirror the shapes `scripts/validate.sh` accepts; take the first that matches.
+Resolve the flow from the target path **before running anything**. The flows run different validators over different dimension vocabularies, so dispatching after Step 1 means the wrong validator has already produced the wrong findings. The rows mirror the shapes `scripts/validate.sh` accepts; take the first that matches.
 
 | Target | Flow | Read |
 |---|---|---|
 | A directory containing `SKILL.md` | skill | `references/skill-flow.md` |
 | A file named `SKILL.md` — audit its parent directory | skill | `references/skill-flow.md` |
 | A file named `*.agent.md` | agent | `references/agent-flow.md` |
+| A file named `*.instructions.md` | instruction | `references/instruction-flow.md` |
+| A file named `*.prompt.md` | prompt | `references/prompt-flow.md` |
 | A `.md` file whose immediate parent directory is `agents/` (`.apm/agents`, `.claude/agents`, `.github/agents`, `.copilot/agents`) | agent | `references/agent-flow.md` |
+| A `.json` file whose immediate parent directory is `hooks/` (`.apm/hooks`, or a package's root `hooks/`) | hook | `references/hook-flow.md` |
 | Anything else — a missing path, a directory without `SKILL.md`, any other file | none | — |
 
 Read only the file its row matched. Each carries Steps 1 to 3 — the deterministic checks, the read, and the qualitative audit — and is self-contained. Return here for Step 4.
 
-On the last row, stop: run no validator and tell the user the two accepted shapes — a skill directory (or its `SKILL.md`), or an agent file (`*.agent.md`, or a `.md` directly under an `agents/` directory). Guessing a flow audits the path against the wrong spec.
+On the last row, stop: run no validator and tell the user the shapes the other rows accept. Guessing a flow audits the path against the wrong spec.
 
-The scripts re-detect the flow from the path. If `validate.sh` reports on the other artifact type than your row, discard what you have and restart here — the flow file, not the script, picked your rubrics, coverage line and remediation line.
+The scripts re-detect the flow from the path. If `validate.sh` reports on a different artifact type than your row, discard what you have and restart here — the flow file, not the script, picked your rubrics, coverage line and remediation line.
 
 ## Step 4 — Report
 
@@ -64,6 +69,8 @@ Checked: structure · provider-safety · description · body · delegation · co
 
 On the agent flow at plugin/APM scope, drop `pair-consistency` — there is no pair to check.
 
+Hook, instruction and prompt flows: the line their flow file ends with.
+
 Then output only the dimensions that have findings, grouped under H3 headings, FAILs before SUGGESTIONs within each. Omit clean dimensions — their absence is what confirms they passed.
 
 Each finding:
@@ -74,4 +81,4 @@ FAIL/SUGGESTION  <finding> — file:line
                  Fix: <exact change — quote before/after where applicable>
 ```
 
-Close with a `## Result` block holding one line: `PASS`, `PASS (N suggestions)`, or `FAIL (N fails · M suggestions)`, each optionally followed by ` · P info`. INFO findings are observational and never change PASS/FAIL; omit `· P info` when there are none. Add a second line whenever there is at least one finding — `Run skill-author to address findings.` on the skill flow, `Run agent-author to address findings.` on the agent flow. Do not apply fixes — report and propose only.
+Close with a `## Result` block holding one line: `PASS`, `PASS (N suggestions)`, or `FAIL (N fails · M suggestions)`, each optionally followed by ` · P info`. INFO findings are observational and never change PASS/FAIL; omit `· P info` when there are none. Add a second line whenever there is at least one finding — `Run skill-author to address findings.` on the skill flow, `Run agent-author to address findings.` on the agent flow, `Run primitive-author to address findings.` on the other three. Do not apply fixes — report and propose only.

plugins/kyberforge/.apm/skills/factory-audit/assets/vale/.vale.ini

@@ -6,5 +6,13 @@ BasedOnStyles = Kyberforge
 [**/agents/*.md]
 BasedOnStyles = Kyberforge
 
+[**/*.instructions.md]
+BasedOnStyles = Kyberforge
+
+[**/*.prompt.md]
+BasedOnStyles = Kyberforge
+
+# Stays the last section: tests/test-vale-wrap.sh case 31 appends a rule
+# override to the end of this file and relies on it landing here.
 [**/*.agent.md]
 BasedOnStyles = Kyberforge, KyberforgeCopilot

plugins/kyberforge/.apm/skills/factory-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml

@@ -1,5 +1,5 @@
 extends: existence
-message: "Description opens with '%s' — use an imperative 'Use when...' opener instead"
+message: "Description opens with '%s' — lead with the action or trigger, not 'This'"
 level: error
 scope: text.frontmatter.description
 ignorecase: true

plugins/kyberforge/.apm/skills/factory-audit/references/hook-flow.md

@@ -0,0 +1,61 @@
+---
+source_keys:
+  - apm-cli-installed-source
+  - apm-docs-llms-full
+---
+
+# Hook Flow
+
+Steps 1 to 3 for an apm hook — the target Step 0 matched as a `.json` file directly under a
+`hooks/` directory. Work them in order, then return to `SKILL.md` Step 4 to report.
+
+## Gotchas
+
+- apm checks almost nothing here. Invalid JSON is skipped without a word, an all-lowercase event deploys and never fires, and a missing script only warns — so `apm install` exiting 0 says nothing about whether the hook works. Never cite a clean install as evidence against a finding.
+- Copilot receiving a Claude-shaped file is not a finding. apm renders one source for every target and documents that it owns the per-target shape; whether Copilot CLI honours a nested entry or `matcher` is unverified upstream, not a defect in the file.
+
+## Step 1 — Deterministic checks
+
+Resolve the path against this skill's own directory. Run exactly:
+
+```bash
+bash scripts/validate.sh <hook-file>
+```
+
+Its findings become the `### Structure` dimension, FAILs and SUGGESTIONs both, at the tier the script assigned: JSON validity, the wrapped-or-naked shape, event lists and nested handler lists (the checks whose failure makes the Copilot install fail), a file contributing no entries, event names that never fire, referenced scripts that are missing, outside the package, not executable when run directly, or referenced by an absolute or bare relative path apm will not bundle, deprecated filename routing, and `${CLAUDE_PLUGIN_ROOT}` where `${PLUGIN_ROOT}` would do. It exits **0** with no FAIL, **1** on real findings, **2** when it never ran — report that as `### Structure` unverified, quoting the stderr reason.
+
+There is no provenance and no Vale step: a hook carries no `source_keys` and no prose.
+
+Three tiers deliberately differ from `primitive-author`'s checklist or the research's. Do not re-tier them by judgment:
+
+- A hook file directly under a package-root `hooks/` passes. apm discovers both `.apm/hooks/` and `hooks/`, and this audit may target a third-party package; `primitive-author` authors only in `.apm/hooks/`.
+- Deprecated filename routing is a SUGGESTION, matching the author's Should: the research allows it when deprecated routing is intended.
+- A non-executable script run as the command's first token is a FAIL, stricter than the research's Should, because it fails every time it fires.
+
+## Step 2 — Read the hook and its scripts
+
+Read the hook file, every script it references, and the package's `apm.yml` `targets:` — reach is narrowed there, never in the hook file.
+
+## Step 3 — Qualitative audit
+
+Cite file and line for every finding.
+
+**purpose** — apm's own rule is to reach for a skill, instruction or prompt first; a hook is for "this must always happen at this event".
+
+- FAIL: the script carries procedure the agent should follow — instructions printed to the model, a multi-step workflow — rather than a runtime callback. That is a skill.
+- SUGGESTION: the behaviour is harness-specific (a Claude-only event, a Claude-only matcher value) in a package whose `targets:` includes other harnesses, and nothing records that the other targets receiving it was accepted. The apm-native fix is a separate package with its own `targets:`, not a routing filename.
+
+**handlers** — the research checklist's Should and audit-only items, which apm never checks:
+
+- SUGGESTION: a handler without `"type": "command"` or an explicit numeric `timeout` in seconds.
+- SUGGESTION: a tool event (`PreToolUse`, `PostToolUse`) or `SessionStart` with no `matcher` — Claude receives `"*"`. A `matcher` on an event Claude ignores it for (`Stop`, `UserPromptSubmit`) is inert, not wrong.
+- SUGGESTION: a PascalCase event name that is not a real Claude Code event (a misspelling deploys verbatim and never fires; the script cannot tell a typo from an event it does not know).
+- SUGGESTION: `bash`/`powershell`/`timeoutSec` keys in a Claude-shaped file — they render, but leave stray keys in `settings.json`.
+- SUGGESTION: an unquoted script path that could contain spaces.
+- SUGGESTION: a helper `.json` file in the hook directory without a `hooks` key — Copilot's loader scans the bundled scripts directory and rejects it. Keep helper configuration non-JSON.
+
+Then return to `SKILL.md` Step 4, opening the report with this coverage line:
+
+```text
+Checked: structure · purpose · handlers
+```

plugins/kyberforge/.apm/skills/factory-audit/references/instruction-flow.md

@@ -0,0 +1,57 @@
+---
+source_keys:
+  - apm-cli-installed-source
+  - apm-docs-llms-full
+---
+
+# Instruction Flow
+
+Steps 1 to 3 for an apm instruction — the target Step 0 matched as a `*.instructions.md` file.
+Work them in order, then return to `SKILL.md` Step 4 to report.
+
+## Gotchas
+
+- `apm compile --validate` is not a gate. Every message `Instruction.validate()` produces is a warning, and it reports success on a file with no description and an empty body — never cite it as evidence against a finding.
+- `description` never reaches Claude, and it is index text elsewhere, never a routing description. Do not hold it to the skill description contract: no trigger clause, no boundary clause. A Vale `Kyberforge.DescriptionOpener` alert here means rewrite it as a plain statement of what the rule covers.
+
+## Step 1 — Deterministic checks
+
+Resolve both paths against this skill's own directory. Run exactly:
+
+```bash
+bash scripts/validate.sh <instruction-file>
+bash scripts/vale-wrap.sh <instruction-file>
+```
+
+`validate.sh` findings become the `### Structure` dimension, FAILs and SUGGESTIONs both, at the tier the script assigned: path, frontmatter, `description`, body, an `applyTo` that is present but empty or has unbalanced braces or brackets, a missing or list-form `applyTo`, extra keys, and a stem duplicated at the package root. It exits **0** with no FAIL, **1** on real findings, **2** when it never ran — report that as `### Structure` unverified, quoting the stderr reason.
+
+`vale-wrap.sh` applies the bundled `Kyberforge` style. Every alert is a FAIL under `### Prose`, cited by rule ID; do not re-derive it by judgment. `0 files` scanned means NOT RUN, not clean — say so and judge prose by reading.
+
+There is no provenance step: an instruction carries no `source_keys`.
+
+## Step 2 — Read the instruction and its context
+
+Read the file, the package's `apm.yml`, and the repo's root `AGENTS.md`. For a scoped file, list the tracked files its `applyTo` matches (`rtk git ls-files` filtered by the glob). List the instruction stems the installed dependencies ship (`apm_modules/**/.apm/instructions/*.instructions.md`) — the script checks only the package root for a duplicate.
+
+## Step 3 — Qualitative audit
+
+Cite file and line for every finding.
+
+**scope** — an instruction applies when files matching `applyTo` are touched; with no `applyTo` it loads into every session of every repo that installs the package.
+
+- FAIL: an always-on file whose content is a rule for this repo alone — it belongs in `AGENTS.md`, which is the repo's single always-on source, not in a package that ships it to every consumer.
+- FAIL: the stem matches an instruction an installed dependency ships — both deploy to `.claude/rules/<stem>.md`, and one silently overwrites the other.
+- SUGGESTION: an `applyTo` glob that matches no tracked file here. It is legitimate for files the package's consumers have and this repo does not, so name the mismatch rather than failing it.
+- SUGGESTION: an always-on file whose content is really file-type specific — narrow it with `applyTo`.
+- SUGGESTION: a glob much broader than the content (`**` for a rule about Python).
+
+**description**
+
+- SUGGESTION: the description does not say what the rule covers, or contradicts the body. Any rationale Claude readers need belongs in the body, because Claude drops the description.
+- SUGGESTION: a relative markdown link that does not resolve from the source file — apm rewrites links on deploy, and a broken one stays broken on every target.
+
+Then return to `SKILL.md` Step 4, opening the report with this coverage line:
+
+```text
+Checked: structure · prose · scope · description
+```

plugins/kyberforge/.apm/skills/factory-audit/references/prompt-flow.md

@@ -0,0 +1,57 @@
+---
+source_keys:
+  - apm-cli-installed-source
+  - apm-docs-llms-full
+---
+
+# Prompt Flow
+
+Steps 1 to 3 for an apm prompt — the target Step 0 matched as a `*.prompt.md` file. Work them in
+order, then return to `SKILL.md` Step 4 to report.
+
+## Gotchas
+
+- A prompt is judged against ADR-0029, not against apm's framing. apm calls a prompt "a callable program"; this repo holds it to a single-intent, user-triggered message that steers existing skills or agents by name and carries no procedure of its own.
+- A prompt's description is not a skill description. It is one plain user-facing sentence with no "Use when" trigger clause and no boundary clause — so never raise a missing trigger or boundary as a finding. A Vale `Kyberforge.DescriptionOpener` alert here means rewrite it as an imperative action ("Review the current PR with …"), not add a trigger.
+
+## Step 1 — Deterministic checks
+
+Resolve both paths against this skill's own directory. Run exactly:
+
+```bash
+bash scripts/validate.sh <prompt-file>
+bash scripts/vale-wrap.sh <prompt-file>
+```
+
+`validate.sh` findings become the `### Structure` dimension, FAILs and SUGGESTIONs both, at the tier the script assigned: path and name, frontmatter, `description` presence, length and trigger clause, keys Claude drops, `input:` names and shapes, and `${input:x}` references against `input:`. Keys Claude drops are a SUGGESTION, not a FAIL, on purpose: a Copilot-only key is legitimate when its Claude drop is intended, and only the author can say which. It exits **0** with no FAIL, **1** on real findings, **2** when it never ran — report that as `### Structure` unverified, quoting the stderr reason.
+
+`vale-wrap.sh` applies the bundled `Kyberforge` style. Every alert is a FAIL under `### Prose`, cited by rule ID; do not re-derive it by judgment. `0 files` scanned means NOT RUN, not clean — say so and judge prose by reading.
+
+There is no provenance step: a prompt carries no `source_keys`.
+
+## Step 2 — Read the prompt and what it steers
+
+Read the file end to end, then the description of every skill or agent its body names, and confirm each resolves in this repo or in a package the prompt's package declares.
+
+## Step 3 — Qualitative audit
+
+Cite file and line for every finding.
+
+**role** — whether this is a prompt at all. Decide it by reading the body, not by its length or headings; there is no threshold.
+
+- FAIL: the body clearly carries reusable procedure — steps, gotchas, domain know-how the agent could not act without — rather than steering skills or agents that hold it. Fix: move the procedure into a skill (new, or the one it belongs to) and reduce the prompt to the message that invokes it.
+- FAIL: the body names a skill or agent that does not resolve, or one carrying `disable-model-invocation: true`, which the model cannot invoke.
+- SUGGESTION: borderline — some how-to detail beyond steering, but not a full procedure.
+- SUGGESTION: more than one intent in one prompt.
+- SUGGESTION: the body is not written as second-person instructions to the agent.
+- SUGGESTION: a `model` value that is not a model slug the package's Claude target accepts. Copilot ignores `model` and `allowed-tools`, so neither constrains a Copilot run.
+
+**description**
+
+- SUGGESTION: the description does not read as one user-facing action, or does not name the skills or agents the prompt steers. On Claude the description is model-visible and apm drops `disable-model-invocation`, so naming what it steers keeps the router pointed at the capability rather than the wrapper.
+
+Then return to `SKILL.md` Step 4, opening the report with this coverage line:
+
+```text
+Checked: structure · prose · role · description
+```

plugins/kyberforge/.apm/skills/factory-audit/references/sources.md

@@ -10,6 +10,8 @@ source_keys:
   - claude-code-subagents-docs
   - context7-github-en-copilot
   - github-custom-agents-configuration
+  - apm-cli-installed-source
+  - apm-docs-llms-full
 ---
 
 # Sources
@@ -151,3 +153,19 @@ source_keys:
 - **Description:** SDK custom agent API — CustomAgentConfig fields in all five languages, session config, sub-agent lifecycle events, tool scoping, permission handling
 - **Contributing files:** (none)
 - **Status:** `extracted`
+
+## apm-cli-installed-source
+
+- **URL:** file:///root/.local/pipx/venvs/apm-cli/lib/python3.11/site-packages/apm_cli/
+- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
+- **Description:** Installed apm-cli 0.28.0 source — ground truth for what apm deploys from a hook, instruction or prompt file and what it silently skips, warns on, or fails the install for; every deterministic check in `scripts/lib-checks-primitive.sh` traces to it via the research docs' Authoring checklists
+- **Contributing files:** SKILL.md, references/hook-flow.md, references/instruction-flow.md, references/prompt-flow.md
+- **Status:** `extracted`
+
+## apm-docs-llms-full
+
+- **URL:** https://microsoft.github.io/apm/llms-full.txt
+- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
+- **Description:** Published apm docs bundle — the "Hooks and commands", "Instructions and agents" and "Author a prompt" guides: canonical hook shape and `${PLUGIN_ROOT}`, reach narrowed by `targets:` rather than filename routing, and "reach for a skill, instruction, or prompt first"
+- **Contributing files:** SKILL.md, references/hook-flow.md, references/instruction-flow.md, references/prompt-flow.md
+- **Status:** `extracted`

plugins/kyberforge/.apm/skills/factory-audit/scripts/lib-boundary-resolver.sh

@@ -898,6 +898,103 @@ def unresolved_targets(description, known):
                 reported.add(name)
     return sorted(blocking), sorted(reported - blocking)
 
+
+# --- Body-level routing targets (issue #124) -------------------------------
+# boundary_targets()/unresolved_targets() above are tuned for a description:
+# one to three sentences, where BOUNDARY_MARKER, the follower test and
+# in-sentence corroboration all exist to tell a routing sentence apart from
+# ordinary prose about a hyphenated tool. A SKILL.md body is a different
+# genre — up to 900 words of procedure and dispatch tables — where those same
+# heuristics would misfire in both directions: a dispatch table rarely reads
+# as a "boundary sentence" (under-fire), and a procedure step naming a file, a
+# CLI verb or a config key looks exactly like a route (over-fire). Retuning
+# the sentence-level heuristics for that genre is the hard half of this gate
+# and is deliberately NOT attempted here — see the issue for why.
+#
+# So the body extractor takes the narrow route instead: only two EXPLICIT
+# ROUTE NOTATION forms count, and each is measured against the real corpus
+# (39 SKILL.md bodies) rather than assumed correct from the description gate's
+# behaviour — a body is dense with prose that LOOKS like this notation and
+# genuinely is not, in ways a one-to-three-sentence description never is:
+#
+#   * ARROW_MARKED — `-> name` / `→ name` where the target is BACKTICKED or
+#     slash-prefixed (MARKED_TARGET). NOT NOTATION_ARROW, which matches a bare
+#     hyphenated word after any arrow: the corpus's own process-chain prose
+#     ("Inline obj prop -> new ref -> re-render.", caveman/SKILL.md) reads as
+#     a route under that pattern and does not under this one, because a
+#     process chain is never itself backticked or slash-prefixed. The one
+#     live true positive this was filed over, write-docs' "-> `to-prd`", IS
+#     backticked (03abcff's diff shows the original), so ARROW_MARKED still
+#     catches it losslessly.
+#   * NOTATION_SLASH — free-standing `/name`, unconditionally, the same
+#     pattern the description gate sweeps with. Two guards narrow it for body
+#     text specifically, each one measured against a real corpus false
+#     positive rather than hypothesised:
+#       - a name with NO hyphen is discarded. A real dispatch entry in this
+#         corpus always names a multi-word skill (`to-prd`,
+#         `setup-matt-pocock-skills`); a single bare or backticked word after
+#         a `/` is prose citing a CLI command, a Claude Code built-in or a
+#         placeholder — `` `/fork` `` (forge/SKILL.md, contrasting
+#         `context: fork` with Claude Code's own /fork subagent command) and
+#         `` `/name` `` (skill-author/SKILL.md, "the user types `/name`" —
+#         `name` is a placeholder for the skill's OWN name, not a route) are
+#         both real corpus hits this guard removes. This is a real recall
+#         loss — `/forge`, `/triage` and other single-word skill names are
+#         unreachable through this extractor — accepted deliberately, the
+#         same "start narrow" trade the issue itself recommends.
+#       - a name immediately preceded by `<` is discarded. An XML/HTML-style
+#         closing tag used as a prompt section delimiter — `</what-to-do>`,
+#         `</supporting-info>` (grill-with-docs/SKILL.md) — is indistinguishable
+#         from `/what-to-do` notation by every other rule in this pattern; no
+#         route is ever written directly after `<` in this corpus, so the
+#         guard costs nothing else.
+#
+# Every surviving hit is unconditionally blocking: both forms are explicit
+# notation with the ambiguous single-word and closing-tag readings already
+# removed, so there is no SUGGESTION tier here — that tier exists to soften
+# an ambiguous prose form, and none is admitted at this point.
+#
+# No conjunction continuation (CONT_*) either: `-> \`to-prd\` or \`grill-me\``
+# resolves only `to-prd`, the same one-arrow-one-target convention
+# multi_target_arrow_clauses() already enforces on descriptions (issue #107),
+# applied here by construction instead of by a second SUGGESTION.
+def body_targets(body):
+    """Every /name or -> `name` routing target named in a SKILL.md body.
+
+    Fenced code blocks are masked first, the same way gotcha_stats() and
+    missing_reference_pointers() mask them: a ```-fenced example quoting
+    `/some-skill` or `-> \`some-skill\`` as illustration is not a live
+    dispatch entry, and skill-author/factory-audit — which document this
+    very notation — are exactly the skills most likely to carry one.
+    """
+    masked = mask_fenced(body)
+    names = set()
+    for match in NOTATION_SLASH.finditer(masked):
+        if match.start() > 0 and masked[match.start() - 1] == '<':
+            continue  # </closing-tag>, not /route-notation
+        name = match.group(1)
+        if '-' in name:
+            names.add(name)
+    for match in ARROW_MARKED.finditer(masked):
+        name, _, _ = _first(match)
+        if name and '-' in name:
+            names.add(name)
+    return sorted(names)
+
+
+def unresolved_body_targets(body, known):
+    """Body routing targets (notation only) that resolve to nothing.
+
+    Unlike unresolved_targets(), this has one outcome, not two: every name
+    body_targets() finds is already route notation, and notation always
+    blocks. `known` is the resolved universe from known_targets(); passing an
+    empty set is not meaningful — callers check for that first and decline
+    out loud instead, exactly as they do for the description gate.
+    """
+    return sorted(name for name in body_targets(body)
+                  if normalize_target(name) not in known)
+
+
 # --- Frontmatter ----------------------------------------------------------
 # Tolerant on the way in, HARD-FAILING on the way out. A UTF-8 BOM, a leading
 # blank line, trailing whitespace after either `---`, or CRLF line endings all
@@ -919,7 +1016,7 @@ FRONTMATTER_RE = re.compile(
 
 
 def strip_bom(text):
-    return text[1:] if text.startswith(u'') else text
+    return text[1:] if text.startswith(u'\ufeff') else text
 
 
 class FrontmatterError(Exception):

plugins/kyberforge/.apm/skills/factory-audit/scripts/lib-checks-primitive.sh

@@ -0,0 +1,576 @@
+#!/usr/bin/env bash
+# lib-checks-primitive.sh — SOURCED, never executed.
+#
+# The structural check suite for the three apm primitives with no
+# SKILL.md-shaped container, all authored by primitive-author: hooks
+# (.apm/hooks/*.json), instructions (*.instructions.md) and prompts
+# (*.prompt.md). validate.sh detects which one it was handed from the path and
+# feeds $KYBERFORGE_PRIMITIVE_PY to python3 with the target as argv[1] and the
+# primitive kind (hook | instruction | prompt) as argv[2].
+#
+# Every check here exists because apm itself does not make it. apm 0.28.0
+# silently skips invalid hook JSON, only warns on an instruction with no
+# description or body, and never validates a prompt's input: names against its
+# ${input:x} references — so `apm install` and `apm compile --validate` both exit
+# 0 on files that deploy nothing, or deploy something that never fires. The
+# checks follow the Authoring checklists at the end of
+# plugins/kyberforge/docs/research/docs/microsoft-apm/{hooks,instructions,prompt}-primitive-schema.md,
+# which trace each rule to the apm source that makes it matter, except where
+# references/{hook,instruction,prompt}-flow.md documents a deliberate deviation
+# (a tier moved, or a check the research leaves audit-only). A Must in
+# primitive-author is a FAIL here, a Should a SUGGESTION.
+#
+# No boundary resolver and no word budgets: none of these files is routed on a
+# description the way a skill is. A prompt's description IS model-visible on
+# Claude, which is why it gets the two ADR-0029 SUGGESTIONs below — but whether
+# a prompt body carries procedure that belongs in a skill is a judgment call the
+# prompt flow makes by reading it, and deliberately has no heuristic here.
+#
+# Output follows lib-checks-agent.sh: FAIL lines on stderr, SUGGESTION and INFO
+# on stdout, exit 1 on any FAIL, 0 otherwise.
+#
+# Consumed by: validate.sh, hook / instruction / prompt modes.
+# shellcheck shell=bash
+# shellcheck disable=SC2034
+
+kyberforge_primitive_preflight() {
+  # Interpreter and library are checked separately so the message names the
+  # thing to install; see lib-checks-agent.sh for the history. PyYAML is needed
+  # for the two markdown kinds, and is required for hooks too so that one
+  # dependency set covers the whole suite rather than a hook audit passing on a
+  # machine where the next instruction audit cannot run.
+  if ! command -v python3 > /dev/null 2>&1; then
+    echo "Error: python3 is required but was not found on PATH." >&2
+    echo "  Why: every primitive check parses the file; without python3 no check runs, and reporting that as a pass would be vacuous." >&2
+    echo "  Fix: install python3." >&2
+    exit 2
+  fi
+
+  if ! python3 -c 'import yaml' > /dev/null 2>&1; then
+    echo "Error: PyYAML is required but is not importable by python3." >&2
+    echo "  Why: instruction and prompt frontmatter has to be parsed the way apm parses it; a hand-rolled reader would disagree with it on exactly the edge cases these checks exist for." >&2
+    echo "  Fix: python3 -m pip install PyYAML   (or your distro's python3-yaml package)." >&2
+    exit 2
+  fi
+}
+
+IFS='' read -r -d '' KYBERFORGE_PRIMITIVE_PY <<'KYBERFORGE_PRIMITIVE' || true
+import sys
+import os
+import re
+import json
+
+import yaml
+
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding='utf-8')
+    except AttributeError:  # pragma: no cover — Python < 3.7
+        pass
+
+target = os.path.abspath(sys.argv[1])
+kind = sys.argv[2]
+fname = os.path.basename(target)
+parent_dir = os.path.dirname(target)
+
+failed = False
+suggestions = []
+
+
+def fail(msg):
+    global failed
+    failed = True
+    print(f"FAIL  {msg}", file=sys.stderr)
+
+
+def suggest(msg):
+    suggestions.append(msg)
+
+
+def info(msg):
+    print(f"INFO  {msg}")
+
+
+def read_text(path):
+    try:
+        with open(path, encoding='utf-8') as f:
+            return f.read()
+    except UnicodeDecodeError as exc:
+        fail(f"not valid UTF-8 ({exc.reason} at byte {exc.start}) — apm reads primitives as UTF-8 — {fname}")
+    except OSError as exc:
+        fail(f"cannot be read ({exc.strerror}) — {fname}")
+    return None
+
+
+def check_not_linked(hardlinks=True):
+    # apm's find_files_by_glob (instructions, prompts) rejects symlinks and
+    # hardlinks (link count > 1); find_hook_files skips symlinks only, so hooks
+    # pass hardlinks=False. A rejected file is silently never deployed.
+    if os.path.islink(target):
+        fail(f"is a symlink — apm's discovery skips symlinks, so it is never deployed — {fname}")
+        return
+    if not hardlinks:
+        return
+    try:
+        if os.stat(target).st_nlink > 1:
+            fail(f"is a hardlink (link count > 1) — apm's discovery rejects hardlinks, so it is never deployed — {fname}")
+    except OSError:
+        pass
+
+
+def package_root_for(subdir):
+    # <pkg>/.apm/<subdir>/<file> -> <pkg>. Returns None for any other layout.
+    if os.path.basename(parent_dir) != subdir:
+        return None
+    apm_dir = os.path.dirname(parent_dir)
+    if os.path.basename(apm_dir) != '.apm':
+        return None
+    return os.path.dirname(apm_dir)
+
+
+FRONTMATTER_RE = re.compile(r'\A---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n|\Z)', re.DOTALL)
+
+
+def split_frontmatter(content):
+    """Return (frontmatter dict | None, body, ok). ok is False on a parse FAIL."""
+    if content.startswith('\ufeff'):
+        content = content[1:]
+    m = FRONTMATTER_RE.match(content)
+    if not m:
+        fail(f"has no YAML frontmatter block (--- ... ---) — description and every other key live there — {fname}")
+        return None, content, False
+    try:
+        fm = yaml.safe_load(m.group(1))
+    except yaml.YAMLError as exc:
+        mark = getattr(exc, 'problem_mark', None)
+        where = f" at line {mark.line + 2}" if mark is not None else ''
+        fail(f"frontmatter is not valid YAML{where} — apm cannot read any key from it — {fname}")
+        return None, content[m.end():], False
+    if fm is None:
+        fm = {}
+    if not isinstance(fm, dict):
+        fail(f"frontmatter is not a YAML mapping — {fname}")
+        return None, content[m.end():], False
+    return fm, content[m.end():], True
+
+
+def check_description(fm):
+    desc = fm.get('description')
+    if not isinstance(desc, str) or not desc.strip():
+        fail(f"'description' is missing or empty — apm does not require it, so nothing else will catch this — {fname}")
+        return None
+    return desc.strip()
+
+
+# ---------------------------------------------------------------------------
+# Hooks
+# ---------------------------------------------------------------------------
+
+ROUTING_TOKENS = ('copilot', 'vscode', 'cursor', 'claude', 'codex', 'gemini',
+                  'antigravity', 'windsurf', 'kiro')
+_TOK = '|'.join(ROUTING_TOKENS)
+ROUTING_STEM_RE = re.compile(rf'^hooks-(?:{_TOK})$|(?:^|-)(?:{_TOK})-hooks$')
+
+# Claude's rename map, 0.28.0: the only camelCase names that reach Claude as a
+# native event. Any other camelCase name is deployed verbatim and never fires.
+CLAUDE_MAPPED_CAMEL = {'preToolUse', 'postToolUse', 'sessionStart', 'agentStop'}
+
+HOOK_COMMAND_KEYS = ('command', 'bash', 'powershell', 'windows', 'linux', 'osx')
+ROOT_TOKENS = ('PLUGIN_ROOT', 'CLAUDE_PLUGIN_ROOT', 'CURSOR_PLUGIN_ROOT', 'KIRO_PLUGIN_ROOT')
+ROOT_TOKEN_RE = re.compile(r'\$\{(' + '|'.join(ROOT_TOKENS) + r')\}')
+
+
+def extract_script_refs(cmd):
+    """Yield (kind, relpath, is_first_token) for each package-relative script
+    reference in a hook command string. kind is 'root' for a ${*_PLUGIN_ROOT}
+    token, 'rel' for a leading ./path."""
+    refs = []
+    for m in ROOT_TOKEN_RE.finditer(cmd):
+        start, end = m.start(), m.end()
+        opened = start > 0 and cmd[start - 1] in '"\''
+        quote = cmd[start - 1] if opened else None
+        rest = cmd[end:]
+        if opened and rest.startswith(quote):
+            # split-quoted form: "${PLUGIN_ROOT}"/scripts/my\ hook.sh
+            rest = rest[1:]
+            path = re.match(r'((?:\\.|[^\s"\'])*)', rest).group(1).replace('\\', '')
+        elif opened:
+            path = rest.split(quote, 1)[0]
+        else:
+            path = re.match(r'((?:\\.|[^\s"\'])*)', rest).group(1).replace('\\', '')
+        prefix = cmd[:start - 1] if opened else cmd[:start]
+        refs.append(('root', path.lstrip('/'), not prefix.strip()))
+    stripped = cmd.lstrip().lstrip('"\'')
+    if stripped.startswith('./'):
+        path = re.match(r'((?:\\.|[^\s"\'])*)', stripped).group(1).replace('\\', '')
+        refs.append(('rel', path, True))
+    return refs
+
+
+SCRIPT_EXT_RE = re.compile(r'\.(?:sh|bash|zsh|py|js|mjs|cjs|ts|ps1|rb|pl)$', re.IGNORECASE)
+
+
+def first_token(cmd):
+    m = re.match(r'\s*(["\']?)((?:\\.|[^\s"\'])*)\1', cmd)
+    return m.group(2).replace('\\', '') if m else ''
+
+
+def check_unanchored_script(cmd, pkg_root, where):
+    # apm rewrites and bundles only ${*_PLUGIN_ROOT}/... and ./... references;
+    # a bare command (`npx foo`, `echo hi`) passes through untouched, which is
+    # fine. An absolute script path, or a bare relative path to a file in the
+    # package, also passes through untouched — so the script is not bundled
+    # and the deployed hook points at a path that does not exist on the
+    # consumer's machine.
+    tok = first_token(cmd)
+    if not tok or tok.startswith('./') or '$' in tok or tok.startswith('~'):
+        return
+    if tok.startswith('/'):
+        real_root = os.path.realpath(pkg_root)
+        inside = os.path.realpath(tok).startswith(real_root + os.sep)
+        if inside or SCRIPT_EXT_RE.search(tok):
+            fail(f"script '{tok}' is an absolute path — apm neither bundles nor rewrites it, so it breaks on every other machine; reference it as ${{PLUGIN_ROOT}}/<path> — {where}")
+        return
+    if '/' in tok:
+        for base in (parent_dir, pkg_root):
+            if os.path.isfile(os.path.join(base, tok)):
+                fail(f"script '{tok}' is a bare relative path — apm bundles and rewrites only ${{PLUGIN_ROOT}}/... and ./... references, so this one deploys unbundled; prefix it with ${{PLUGIN_ROOT}}/ or ./ — {where}")
+                return
+
+
+def check_script(kind_, rel, first, pkg_root, where):
+    if not rel:
+        return
+    if '$' in rel or '`' in rel:
+        fail(f"script path '{rel}' contains '$' or a backtick — apm refuses to rewrite it for Claude — {where}")
+        return
+    candidates = []
+    if kind_ == 'root':
+        candidates.append(os.path.join(pkg_root, rel))
+    else:
+        candidates.append(os.path.join(parent_dir, rel))
+        candidates.append(os.path.join(pkg_root, rel))
+    real_root = os.path.realpath(pkg_root)
+    found = None
+    for c in candidates:
+        real = os.path.realpath(c)
+        if real != real_root and not real.startswith(real_root + os.sep):
+            fail(f"script '{rel}' resolves outside the package — apm confines hook scripts to the package root — {where}")
+            return
+        if os.path.isfile(c):
+            found = c
+            break
+    if found is None:
+        fail(f"script '{rel}' does not exist in the package — apm only warns, then deploys a hook that fails every time it fires — {where}")
+        return
+    if first and not os.access(found, os.X_OK):
+        fail(f"script '{rel}' is run directly but is not executable — chmod +x it, or invoke it through an interpreter — {where}")
+
+
+def audit_hook():
+    check_not_linked(hardlinks=False)
+    stem = fname[:-len('.json')]
+    hooks_dir = os.path.basename(parent_dir)
+    if hooks_dir != 'hooks':
+        fail(f"is not directly in a hooks/ directory — apm discovers hook files only at .apm/hooks/*.json and hooks/*.json, non-recursively — {fname}")
+    if os.path.basename(os.path.dirname(parent_dir)) == '.apm':
+        pkg_root = os.path.dirname(os.path.dirname(parent_dir))
+    else:
+        pkg_root = os.path.dirname(parent_dir)
+    if not os.path.isfile(os.path.join(pkg_root, 'apm.yml')):
+        info(f"no apm.yml at the inferred package root {pkg_root} — script paths are resolved against it anyway — {fname}")
+
+    if ROUTING_STEM_RE.search(stem):
+        suggest(f"filename stem '{stem}' uses deprecated hook filename routing — name it plainly and narrow reach with target:/targets: in the package's apm.yml — {fname}")
+
+    content = read_text(target)
+    if content is None:
+        return
+    try:
+        doc = json.loads(content)
+    except json.JSONDecodeError as exc:
+        fail(f"is not valid JSON (line {exc.lineno}, column {exc.colno}) — apm skips an unparseable hook file silently — {fname}")
+        return
+    if not isinstance(doc, dict):
+        fail(f"top level is not a JSON object — {fname}")
+        return
+
+    if 'hooks' in doc:
+        events = doc['hooks']
+        if not isinstance(events, dict):
+            fail(f"'hooks' is not an object — apm skips the file, and the Copilot install fails outright — {fname}")
+            return
+    else:
+        stray = [k for k, v in doc.items() if not isinstance(v, list)]
+        if stray:
+            fail(f"naked settings-slice shape with non-list top-level key(s) {', '.join(sorted(stray))} — apm does not promote it, Claude gets nothing and Copilot gets a junk file; wrap events in {{\"hooks\": {{...}}}} — {fname}")
+            return
+        events = doc
+
+    if not events:
+        fail(f"contributes no hook entries — apm warns and deploys nothing — {fname}")
+        return
+
+    # A file is Claude-shaped when its entries nest handlers under "hooks" or
+    # its handlers use "command"; the flat bash/powershell form is Copilot's.
+    claude_shaped = False
+    shape_ok = True
+    for event, entries in events.items():
+        if not isinstance(entries, list):
+            fail(f"event '{event}' is not a list — the Copilot install fails on this payload — {fname}")
+            shape_ok = False
+            continue
+        for i, entry in enumerate(entries):
+            if not isinstance(entry, dict):
+                fail(f"event '{event}' entry {i} is not an object — the Copilot install fails on this payload — {fname}")
+                shape_ok = False
+                continue
+            if 'hooks' in entry:
+                claude_shaped = True
+                nested = entry['hooks']
+                if not isinstance(nested, list) or not all(isinstance(h, dict) for h in nested):
+                    fail(f"event '{event}' entry {i}: nested 'hooks' is not a list of objects — the Copilot install fails on this payload — {fname}")
+                    shape_ok = False
+            elif 'command' in entry:
+                claude_shaped = True
+
+    for event in events:
+        if not event.strip():
+            fail(f"empty event name — {fname}")
+        elif not any(c.isupper() for c in event):
+            fail(f"event '{event}' is all-lowercase — no target maps it and apm never warns, so it silently never fires — {fname}")
+        elif claude_shaped and event[0].islower() and event not in CLAUDE_MAPPED_CAMEL:
+            fail(f"event '{event}' is camelCase in a Claude-shaped file and Claude's map does not rename it — it deploys verbatim and never fires; write it in PascalCase — {fname}")
+
+    if not shape_ok:
+        return
+
+    uses_claude_token = False
+    for event, entries in events.items():
+        for i, entry in enumerate(entries):
+            handlers = entry['hooks'] if 'hooks' in entry else [entry]
+            for j, handler in enumerate(handlers):
+                where = f"{fname} {event}[{i}]" + (f".hooks[{j}]" if 'hooks' in entry else '')
+                for key in HOOK_COMMAND_KEYS:
+                    cmd = handler.get(key)
+                    if not isinstance(cmd, str):
+                        continue
+                    if '${CLAUDE_PLUGIN_ROOT}' in cmd:
+                        uses_claude_token = True
+                    refs = extract_script_refs(cmd)
+                    for kind_, rel, first in refs:
+                        check_script(kind_, rel, first, pkg_root, where)
+                    if not any(first for _, _, first in refs):
+                        check_unanchored_script(cmd, pkg_root, where)
+
+    if uses_claude_token:
+        suggest(f"uses ${{CLAUDE_PLUGIN_ROOT}} — apm documents the target-neutral ${{PLUGIN_ROOT}}, which it rewrites identically for every target — {fname}")
+
+
+# ---------------------------------------------------------------------------
+# Instructions
+# ---------------------------------------------------------------------------
+
+INSTRUCTION_KEYS = {'description', 'applyTo', 'author', 'version'}
+
+
+def split_top_level(value):
+    # apm's parse_apply_to: split on commas outside {} (and not escaped \,),
+    # strip each segment, drop empty ones.
+    segs, cur, depth, i = [], '', 0, 0
+    while i < len(value):
+        c = value[i]
+        if c == '\\' and i + 1 < len(value):
+            cur += value[i:i + 2]
+            i += 2
+            continue
+        if c == '{':
+            depth += 1
+        elif c == '}':
+            depth -= 1
+        if c == ',' and depth == 0:
+            segs.append(cur)
+            cur = ''
+        else:
+            cur += c
+        i += 1
+    segs.append(cur)
+    return [s.strip() for s in segs if s.strip()]
+
+
+def check_apply_to(apply_to):
+    if isinstance(apply_to, list):
+        entries = [e for e in apply_to if e is not None and str(e).strip()]
+        globs = [str(e).strip() for e in entries]
+    elif isinstance(apply_to, str):
+        globs = split_top_level(apply_to)
+    else:
+        fail(f"applyTo is neither a string nor a list — apm cannot read a glob from it — {fname}")
+        return False
+    if not globs:
+        fail(f"applyTo is present but empty — remove the key for an intentionally always-on rule, or give it a glob — {fname}")
+        return False
+    ok = True
+    for g in globs:
+        if g.count('{') != g.count('}') or g.count('[') != g.count(']'):
+            fail(f"applyTo glob '{g}' has unbalanced braces or brackets — it matches nothing, so the rule never fires — {fname}")
+            ok = False
+    return ok
+
+
+def audit_instruction():
+    check_not_linked()
+    stem = fname[:-len('.instructions.md')]
+    pkg_root = package_root_for('instructions')
+    if pkg_root is None:
+        fail(f"is not directly in a .apm/instructions/ directory — that is the authoring source; anything else is either deployed output or a legacy root file — {fname}")
+    else:
+        dup = os.path.join(pkg_root, fname)
+        if os.path.isfile(dup):
+            fail(f"stem '{stem}' also exists at the package root ({dup}) — both deploy to the same .claude/rules/{stem}.md, and one overwrites the other — {fname}")
+
+    content = read_text(target)
+    if content is None:
+        return
+    fm, body, ok = split_frontmatter(content)
+    if not ok:
+        return
+    check_description(fm)
+    if not body.strip():
+        fail(f"body is empty — apm deploys an empty rule without complaint — {fname}")
+
+    apply_to = fm.get('applyTo')
+    apply_to_ok = apply_to is not None and check_apply_to(apply_to)
+    if apply_to is None:
+        suggest(f"no applyTo — this loads into every session of every repo that installs the package; confirm always-on is intended, and that a rule for this repo alone is not really an AGENTS.md rule — {fname}")
+    elif apply_to_ok and isinstance(apply_to, list):
+        suggest(f"applyTo is a YAML list — Copilot receives the file verbatim and its handling of a list is unverified; use one comma-separated string — {fname}")
+
+    extra = sorted(k for k in fm if k not in INSTRUCTION_KEYS)
+    if extra:
+        suggest(f"frontmatter key(s) {', '.join(extra)} are read by no target and dropped on Claude — keep to description and applyTo (author, version optional) — {fname}")
+
+
+# ---------------------------------------------------------------------------
+# Prompts
+# ---------------------------------------------------------------------------
+
+PROMPT_KEYS = {'description', 'allowed-tools', 'model', 'argument-hint', 'input'}
+PROMPT_CAMEL_ALIASES = {'allowedTools': 'allowed-tools', 'argumentHint': 'argument-hint'}
+INPUT_NAME_RE = re.compile(r'^[A-Za-z][\w-]{0,63}$')
+# apm's own rewrite pattern for ${input:x}, command_integrator.py.
+INPUT_REF_RE = re.compile(r'\$\{\{?\s*input\s*:\s*([\w-]+)\s*\}?\}')
+TRIGGER_RE = re.compile(r'\buse\s+(?:this\s+)?when\b', re.IGNORECASE)
+PROMPT_DESC_SUGGEST_CHARS = 250
+
+
+def prompt_input_names(spec):
+    """Mirror apm's _extract_input_names, but FAIL on what it rejects or
+    misreads instead of warning. Returns the declared names."""
+    names = []
+
+    def accept(candidate):
+        if not isinstance(candidate, str):
+            fail(f"input entry {candidate!r} is not a string name — apm rejects it — {fname}")
+            return
+        s = candidate.strip()
+        if not s:
+            return
+        if not INPUT_NAME_RE.match(s):
+            fail(f"input name '{s}' does not match ^[A-Za-z][\\w-]{{0,63}}$ — apm rejects it, so the argument never exists — {fname}")
+            return
+        names.append(s)
+
+    if spec is None:
+        return names
+    if isinstance(spec, str):
+        accept(spec)
+    elif isinstance(spec, dict):
+        for k in spec:
+            accept(k)
+    elif isinstance(spec, list):
+        for item in spec:
+            if isinstance(item, dict):
+                if len(item) > 1:
+                    keys = ', '.join(str(k) for k in item)
+                    hint = (" — this is the upstream docs example's `- name: x` / `description:` form, which yields arguments [name, description]"
+                            if 'name' in item else '')
+                    fail(f"input entry {{{keys}}} is one map with several keys — apm reads every key as an argument name{hint}; write `- <name>: \"<desc>\"` — {fname}")
+                for k in item:
+                    accept(k)
+            else:
+                accept(item)
+    else:
+        fail(f"input is neither a name, a list nor a map — apm extracts no arguments from it — {fname}")
+    return names
+
+
+def audit_prompt():
+    check_not_linked()
+    stem = fname[:-len('.prompt.md')]
+    segs = stem.replace('\\', '/').split('/')
+    if not stem.strip() or any(s in ('.', '..', '') for s in segs) or '/' in stem.replace('\\', '/'):
+        fail(f"name '{stem}' is not a safe path segment — apm's validate_path_segments rejects it — {fname}")
+    pkg_root = package_root_for('prompts')
+    if pkg_root is None:
+        fail(f"is not directly in a .apm/prompts/ directory — that is the authoring source; anything else is either deployed output or a legacy root file — {fname}")
+    else:
+        dup = os.path.join(pkg_root, fname)
+        if os.path.isfile(dup):
+            fail(f"name '{stem}' also exists at the package root ({dup}) — both deploy as /{stem}, and they collide — {fname}")
+
+    content = read_text(target)
+    if content is None:
+        return
+    fm, body, ok = split_frontmatter(content)
+    if not ok:
+        return
+
+    desc = check_description(fm)
+    if desc is not None:
+        if len(desc) > PROMPT_DESC_SUGGEST_CHARS:
+            suggest(f"description is {len(desc)} characters (> {PROMPT_DESC_SUGGEST_CHARS}) — it is one user-facing sentence (ADR-0029) — {fname}")
+        if TRIGGER_RE.search(desc):
+            suggest(f"description carries a 'Use when' trigger clause — a prompt is user-triggered (ADR-0029); a trigger clause invites the model to route to it on Claude — {fname}")
+
+    for camel, kebab in PROMPT_CAMEL_ALIASES.items():
+        if camel in fm:
+            suggest(f"'{camel}' — use the kebab-case spelling '{kebab}' apm documents — {fname}")
+    extra = sorted(k for k in fm if k not in PROMPT_KEYS and k not in PROMPT_CAMEL_ALIASES)
+    if extra:
+        suggest(f"frontmatter key(s) {', '.join(extra)} are dropped on Claude (it keeps only {', '.join(sorted(PROMPT_KEYS))}) — keep them only if the Copilot-only behaviour is intended — {fname}")
+
+    declared = prompt_input_names(fm.get('input'))
+    used = []
+    for m in INPUT_REF_RE.finditer(body):
+        if m.group(1) not in used:
+            used.append(m.group(1))
+    if used and not declared:
+        fail(f"body uses {', '.join('${input:' + u + '}' for u in used)} but no input: is declared — apm rewrites references only when input: names them, so Claude receives the literal text — {fname}")
+    else:
+        for u in used:
+            if u not in declared:
+                fail(f"body uses ${{input:{u}}} but input: does not declare '{u}' — {fname}")
+        for d in declared:
+            if d not in used:
+                fail(f"input '{d}' is declared but the body never uses ${{input:{d}}} — the user is asked for an argument that goes nowhere — {fname}")
+
+    if declared and ('argument-hint' in fm or 'argumentHint' in fm):
+        suggest(f"argument-hint is set alongside input: — apm synthesises the hint from input: names; drop it unless that form is inadequate — {fname}")
+
+
+if kind == 'hook':
+    audit_hook()
+elif kind == 'instruction':
+    audit_instruction()
+elif kind == 'prompt':
+    audit_prompt()
+else:
+    print(f"Error: unknown primitive kind '{kind}'", file=sys.stderr)
+    sys.exit(2)
+
+for s in suggestions:
+    print(f"SUGGESTION  {s}")
+sys.exit(1 if failed else 0)
+KYBERFORGE_PRIMITIVE
+KYBERFORGE_PRIMITIVE_PY="${KYBERFORGE_PRIMITIVE_PY%$'\n'}"

plugins/kyberforge/.apm/skills/factory-audit/scripts/lib-checks-skill.sh

@@ -443,39 +443,56 @@ elif desc:
 # derived from this script's own path, and — when an authoring root exists — it
 # never reads a deployed .claude/ tree, so a fresh clone and a machine that has
 # run `apm install` return the same verdict. See the shared resolver's header.
-if desc:
-    routing_targets = boundary_targets(desc)
-    known = known_targets(skill_dir) if routing_targets else set()
-    if routing_targets and not known:
+routing_targets = boundary_targets(desc) if desc else []
+# Body-level targets (issue #124): notation only (`/name`, `-> name`), so
+# every hit is unconditionally blocking — see the shared resolver's
+# body_targets() header for why the description gate's SUGGESTION tier has
+# no counterpart here. Read regardless of `desc`: a body dispatch table can
+# carry a broken route even when the description carries none.
+body_routing_targets = body_targets(body)
+if routing_targets or body_routing_targets:
+    known = known_targets(skill_dir)
+    if not known:
+        unchecked = sorted(set(routing_targets) | set(body_routing_targets))
         info(f"boundary-target resolution DID NOT RUN — no skill universe could be "
              f"determined for this path (no authoring root above it, no apm package "
              f"root, no declared apm dependencies, no deployed .claude/ or .agents/ "
-             f"tree). Unchecked target(s): {', '.join(routing_targets)}")
-    elif routing_targets:
-        # blocking vs reported: a target only earns a FAIL when it is written in
-        # route notation or its own sentence corroborates it by naming another
-        # target that resolves. See the shared resolver's CORROBORATION note.
-        unresolved, soft = unresolved_targets(desc, known)
-        for target in unresolved:
-            fail(f"description routes to '{target}', which resolves to no skill or agent "
-                 f"in this monorepo, in this package, or in a package it declares in "
-                 f"apm.yml dependencies.apm — a boundary clause naming a non-existent "
-                 f"target sends the router nowhere")
-        for target in soft:
-            suggest(f"description routes to '{target}', which resolves to no skill or agent "
-                    f"in this monorepo, in this package, or in a package it declares in "
-                    f"apm.yml dependencies.apm — SUGGESTION rather than FAIL because nothing "
-                    f"else in that sentence resolves, so it is equally likely to be a tool, a "
-                    f"file format or an English compound. If it IS a route, write it as "
-                    f"`/{target}` or `-> {target}` and it will be checked properly")
-        if not unresolved:
-            # Counts the targets that ACTUALLY resolve, not every target found:
-            # a confirm-only target (one used attributively — see the resolver's
-            # ATTRIBUTIVE USE note) is exempt from the failure above, so
-            # reporting it as resolved would be a false claim.
-            resolved = [t for t in routing_targets if normalize_target(t) in known]
-            ok(f"{len(resolved)} of {len(routing_targets)} boundary target(s) resolve: "
-               f"{', '.join(resolved) if resolved else '(none)'}")
+             f"tree). Unchecked target(s): {', '.join(unchecked)}")
+    else:
+        if routing_targets:
+            # blocking vs reported: a target only earns a FAIL when it is written in
+            # route notation or its own sentence corroborates it by naming another
+            # target that resolves. See the shared resolver's CORROBORATION note.
+            unresolved, soft = unresolved_targets(desc, known)
+            for target in unresolved:
+                fail(f"description routes to '{target}', which resolves to no skill or agent "
+                     f"in this monorepo, in this package, or in a package it declares in "
+                     f"apm.yml dependencies.apm — a boundary clause naming a non-existent "
+                     f"target sends the router nowhere")
+            for target in soft:
+                suggest(f"description routes to '{target}', which resolves to no skill or agent "
+                        f"in this monorepo, in this package, or in a package it declares in "
+                        f"apm.yml dependencies.apm — SUGGESTION rather than FAIL because nothing "
+                        f"else in that sentence resolves, so it is equally likely to be a tool, a "
+                        f"file format or an English compound. If it IS a route, write it as "
+                        f"`/{target}` or `-> {target}` and it will be checked properly")
+            if not unresolved:
+                # Counts the targets that ACTUALLY resolve, not every target found:
+                # a confirm-only target (one used attributively — see the resolver's
+                # ATTRIBUTIVE USE note) is exempt from the failure above, so
+                # reporting it as resolved would be a false claim.
+                resolved = [t for t in routing_targets if normalize_target(t) in known]
+                ok(f"{len(resolved)} of {len(routing_targets)} boundary target(s) resolve: "
+                   f"{', '.join(resolved) if resolved else '(none)'}")
+        unresolved_body = unresolved_body_targets(body, known)
+        for target in unresolved_body:
+            fail(f"body routes to '{target}' (`/{target}` or `-> {target}` notation), which "
+                 f"resolves to no skill or agent in this monorepo, in this package, or in a "
+                 f"package it declares in apm.yml dependencies.apm — a dispatch table or "
+                 f"\"run X\" step naming a non-existent target sends the agent nowhere")
+        if body_routing_targets and not unresolved_body:
+            ok(f"{len(body_routing_targets)} of {len(body_routing_targets)} body routing "
+               f"target(s) resolve: {', '.join(body_routing_targets)}")
 
 # Body unfilled placeholders
 fill_matches = PLACEHOLDER_RE.findall(body)

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

@@ -2,13 +2,16 @@
 set -euo pipefail
 
 # The ONE entry point for structural validation. It auto-detects whether the
-# target is a skill directory or an agent definition file and runs the matching
-# check suite; the two suites live in lib-checks-skill.sh and lib-checks-agent.sh
-# and are unchanged from the skill-audit / agent-audit scripts they came from.
+# target is a skill directory, an agent definition file, or one of the three apm
+# primitives with no container of their own (a hook, an instruction or a prompt)
+# and runs the matching check suite. The skill and agent suites live in
+# lib-checks-skill.sh and lib-checks-agent.sh and are unchanged from the
+# skill-audit / agent-audit scripts they came from; the primitive suite lives in
+# lib-checks-primitive.sh.
 # The ADR-0020 boundary resolver both of them need is sourced once, from
 # lib-boundary-resolver.sh, instead of being embedded twice.
 #
-# Detection never guesses. A target that matches neither shape is a hard exit 2
+# Detection never guesses. A target that matches no shape is a hard exit 2
 # naming the mismatch, because the alternative — picking a mode and letting the
 # suite fail on its own terms — reports a skill-shaped finding about an agent
 # file, or the reverse, and sends the reader after the wrong problem.
@@ -115,17 +118,22 @@ _kf_require_lib() {
 
 usage() {
   cat <<EOF
-Usage: validate.sh <skill-dir | agent-file>
+Usage: validate.sh <skill-dir | agent-file | hook-file | instruction-file | prompt-file>
 
-Validate a skill directory against the agentskills.io specification, or an agent
-definition file against the agent definition spec. The mode is detected from the
-target:
+Validate a skill directory against the agentskills.io specification, an agent
+definition file against the agent definition spec, or an apm hook, instruction or
+prompt file against what apm 0.28.0 actually deploys. The mode is detected from
+the target:
 
   skill mode  the target is a directory (a skill directory contains SKILL.md),
               or the target IS a SKILL.md file.
   agent mode  the target is a *.agent.md file, or a *.md file whose parent
               directory is named 'agents' (.apm/agents, .claude/agents,
               .github/agents, .copilot/agents).
+  hook mode         the target is a *.json file directly under a hooks/
+                    directory (.apm/hooks, or a package's root hooks/).
+  instruction mode  the target is a *.instructions.md file.
+  prompt mode       the target is a *.prompt.md file.
 
 Skill mode audits the directory named by <skill-dir>.
 
@@ -137,16 +145,20 @@ At project or user scope, <agent-file> is either half of a Claude Code .md /
 Copilot .agent.md pair.
 
 Arguments:
-  skill-dir   Path to the skill directory containing SKILL.md.
-  agent-file  Path to the agent file (or either half of a project/user-scope pair).
+  skill-dir         Path to the skill directory containing SKILL.md.
+  agent-file        Path to the agent file (or either half of a project/user-scope pair).
+  hook-file         Path to a hook JSON file directly under .apm/hooks/ or hooks/.
+  instruction-file  Path to a *.instructions.md file.
+  prompt-file       Path to a *.prompt.md file.
 
 Exit codes:
   0  All checks passed (may include SUGGESTIONs)
   1  One or more checks failed
-  2  Nothing was audited (no argument, the target matches neither shape, the
+  2  Nothing was audited (no argument, the target matches no shape, the
      target does not exist, an unrecognized file extension, a missing
-     references/agent-field-inventory.md, or a missing or unreadable lib-*.sh
-     beside this script)
+     references/agent-field-inventory.md, a missing or unreadable lib-*.sh
+     beside this script, or, for a hook, instruction or prompt, a missing
+     python3 or PyYAML)
 EOF
 }
 
@@ -156,7 +168,7 @@ if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
 fi
 
 if [[ $# -lt 1 ]]; then
-  echo "Error: a skill directory or an agent file is required." >&2
+  echo "Error: a skill directory, an agent file, or a hook, instruction or prompt file is required." >&2
   echo "" >&2
   usage >&2
   exit 2
@@ -209,12 +221,21 @@ elif [[ "$TARGET_BASE" == "SKILL.md" ]]; then
   TARGET="$(_kf_dirname "$TARGET")"
 elif [[ "$TARGET_BASE" == *.agent.md ]]; then
   MODE=agent
+# The two primitive suffixes are tested before the agents/-parent rule: a
+# *.prompt.md or *.instructions.md file is that primitive wherever it sits, and
+# the parent-name rule would otherwise claim one that happened to sit in agents/.
+elif [[ "$TARGET_BASE" == *.instructions.md ]]; then
+  MODE=instruction
+elif [[ "$TARGET_BASE" == *.prompt.md ]]; then
+  MODE=prompt
+elif [[ "$TARGET_BASE" == *.json && "$TARGET_PARENT" == "hooks" && ! -d "$TARGET" ]]; then
+  MODE=hook
 elif [[ "$TARGET_BASE" == *.md && "$TARGET_PARENT" == "agents" ]]; then
   MODE=agent
 else
-  echo "Error: '$TARGET' matches neither a skill directory nor an agent file." >&2
-  echo "  Why: skill mode needs a directory containing SKILL.md (or the SKILL.md itself); agent mode needs a <name>.agent.md file, or a .md file directly under an agents/ directory (.apm/agents, .claude/agents, .github/agents, .copilot/agents). Picking a mode anyway would audit this path against the wrong spec." >&2
-  echo "  Fix: pass one of those two shapes." >&2
+  echo "Error: '$TARGET' matches no auditable shape." >&2
+  echo "  Why: skill mode needs a directory containing SKILL.md (or the SKILL.md itself); agent mode needs a <name>.agent.md file, or a .md file directly under an agents/ directory (.apm/agents, .claude/agents, .github/agents, .copilot/agents); hook mode needs a .json file directly under a hooks/ directory; instruction and prompt modes need a *.instructions.md or *.prompt.md file. Picking a mode anyway would audit this path against the wrong spec." >&2
+  echo "  Fix: pass one of those shapes." >&2
   exit 2
 fi
 
@@ -250,6 +271,13 @@ $KYBERFORGE_RESOLVER_PY
 $KYBERFORGE_AGENT_BODY_PY"
     python3 -u - "$TARGET" "$SCRIPT_DIR" <<< "$PROG" || RC=$?
     ;;
+  hook | instruction | prompt)
+    _kf_require_lib lib-checks-primitive.sh
+    # shellcheck source=lib-checks-primitive.sh
+    . "$SCRIPT_DIR/lib-checks-primitive.sh"
+    kyberforge_primitive_preflight
+    python3 -u - "$TARGET" "$MODE" <<< "$KYBERFORGE_PRIMITIVE_PY" || RC=$?
+    ;;
 esac
 
 exit "$RC"

plugins/kyberforge/.apm/skills/factory-audit/tests/README.md

@@ -36,13 +36,16 @@ bats plugins/kyberforge/.apm/skills/factory-audit/tests/
 | `validate-agent.bats` | `scripts/validate.sh` against agent files |
 | `validate-provenance-skill.bats` | `scripts/validate-provenance.sh` against skill directories |
 | `validate-provenance-agent.bats` | `scripts/validate-provenance.sh` against agent files |
+| `validate-primitive.bats` | `scripts/validate.sh` against apm hook, instruction and prompt files |
 
-## Two scripts, four suites
+## Two scripts, five suites
 
 `factory-audit` merges what were two skills — `skill-audit` and `agent-audit` —
 each of which shipped its own `validate.sh` and `validate-provenance.sh`. The
 merged skill has **one** of each. Every suite here invokes one of those two
-scripts; the four files are two scripts × two artifact types, not four scripts.
+scripts; the four skill and agent files are two scripts × two artifact types, not four scripts.
+`validate-primitive.bats` is a fifth suite over the same `scripts/validate.sh`, for hooks,
+instructions and prompts, which have no provenance mode and so no provenance suite.
 
 `validate-skill.bats` and `validate-agent.bats` run the same
 `scripts/validate.sh` and differ only in the fixtures they point it at. The two

plugins/kyberforge/.apm/skills/factory-audit/tests/validate-primitive.bats

@@ -0,0 +1,397 @@
+#!/usr/bin/env bats
+
+# scripts/validate.sh against the three apm primitives with no container of
+# their own: hooks, instructions and prompts. Each rule under test traces to
+# the Authoring checklist in
+# plugins/kyberforge/docs/research/docs/microsoft-apm/<kind>-primitive-schema.md.
+
+setup() {
+    REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../../../../../../" && pwd)"
+    load "$REPO_ROOT/tests/test_helper/bats-support/load"
+    load "$REPO_ROOT/tests/test_helper/bats-assert/load"
+
+    SCRIPT="$(cd "$BATS_TEST_DIRNAME/../scripts" && pwd)/validate.sh"
+    TMPDIR="$(mktemp -d)"
+    PKG="$TMPDIR/pkg"
+    mkdir -p "$PKG/.apm/hooks/scripts" "$PKG/.apm/instructions" "$PKG/.apm/prompts"
+    cat > "$PKG/apm.yml" <<EOF
+name: test-package
+version: 0.1.0
+type: hybrid
+EOF
+    printf '#!/usr/bin/env bash\nexit 0\n' > "$PKG/.apm/hooks/scripts/check.sh"
+    chmod +x "$PKG/.apm/hooks/scripts/check.sh"
+
+    # Helper: write <content> as hook file <name> under .apm/hooks/.
+    write_hook() {
+        printf '%s\n' "$2" > "$PKG/.apm/hooks/$1"
+    }
+
+    # Helper: write an instruction <stem> with raw <frontmatter> and <body>.
+    write_instruction() {
+        printf -- '---\n%s\n---\n\n%s\n' "$2" "$3" > "$PKG/.apm/instructions/$1.instructions.md"
+    }
+
+    # Helper: write a prompt <stem> with raw <frontmatter> and <body>.
+    write_prompt() {
+        printf -- '---\n%s\n---\n\n%s\n' "$2" "$3" > "$PKG/.apm/prompts/$1.prompt.md"
+    }
+}
+
+teardown() {
+    rm -rf "$TMPDIR"
+}
+
+# ---------------------------------------------------------------------------
+# Dispatch
+# ---------------------------------------------------------------------------
+
+@test "dispatch: a .json file outside a hooks/ directory matches no shape (exit 2)" {
+    printf '{}\n' > "$PKG/settings.json"
+    run bash "$SCRIPT" "$PKG/settings.json"
+    assert_equal "$status" 2
+    assert_output --partial "matches no auditable shape"
+}
+
+@test "dispatch: an *.instructions.md under an agents/ directory takes the instruction flow, not the agent flow" {
+    mkdir -p "$PKG/.apm/agents"
+    printf -- '---\ndescription: x\n---\n\nbody\n' > "$PKG/.apm/agents/x.instructions.md"
+    run bash "$SCRIPT" "$PKG/.apm/agents/x.instructions.md"
+    assert_failure
+    assert_output --partial "is not directly in a .apm/instructions/ directory"
+    refute_output --partial "counterpart"
+}
+
+# ---------------------------------------------------------------------------
+# Hooks
+# ---------------------------------------------------------------------------
+
+@test "hook: canonical nested shape with \${PLUGIN_ROOT} passes clean" {
+    write_hook hooks.json '{"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":"${PLUGIN_ROOT}/.apm/hooks/scripts/check.sh","timeout":10}]}]}}'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_success
+    refute_output --partial "FAIL"
+    refute_output --partial "SUGGESTION"
+}
+
+@test "hook: invalid JSON is a FAIL" {
+    write_hook hooks.json '{"hooks": {'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_failure
+    assert_output --partial "is not valid JSON"
+}
+
+@test "hook: an event value that is not a list is a FAIL" {
+    write_hook hooks.json '{"hooks":{"PreToolUse":{"hooks":[]}}}'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_failure
+    assert_output --partial "event 'PreToolUse' is not a list"
+}
+
+@test "hook: a naked slice with a stray scalar key is a FAIL" {
+    write_hook hooks.json '{"description":"x","PreToolUse":[{"hooks":[{"type":"command","command":"true"}]}]}'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_failure
+    assert_output --partial "naked settings-slice shape"
+}
+
+@test "hook: an all-lowercase event is a FAIL" {
+    write_hook hooks.json '{"hooks":{"stop":[{"hooks":[{"type":"command","command":"true"}]}]}}'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_failure
+    assert_output --partial "event 'stop' is all-lowercase"
+}
+
+@test "hook: camelCase userPromptSubmit in a Claude-shaped file is a FAIL; mapped sessionStart is not" {
+    write_hook hooks.json '{"hooks":{"userPromptSubmit":[{"hooks":[{"type":"command","command":"true"}]}],"sessionStart":[{"hooks":[{"type":"command","command":"true"}]}]}}'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_failure
+    assert_output --partial "event 'userPromptSubmit' is camelCase"
+    refute_output --partial "event 'sessionStart'"
+}
+
+@test "hook: a flat Copilot-shaped file may use camelCase events" {
+    write_hook hooks.json '{"hooks":{"userPromptSubmit":[{"type":"command","bash":"true","timeoutSec":5}]}}'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_success
+}
+
+@test "hook: a referenced script that does not exist is a FAIL" {
+    write_hook hooks.json '{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"${PLUGIN_ROOT}/.apm/hooks/scripts/missing.sh"}]}]}}'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_failure
+    assert_output --partial "script '.apm/hooks/scripts/missing.sh' does not exist"
+}
+
+@test "hook: a directly-run script without the executable bit is a FAIL; the same script through an interpreter is not" {
+    chmod -x "$PKG/.apm/hooks/scripts/check.sh"
+    write_hook hooks.json '{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"./scripts/check.sh"}]}]}}'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_failure
+    assert_output --partial "is run directly but is not executable"
+
+    write_hook hooks.json '{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"bash ${PLUGIN_ROOT}/.apm/hooks/scripts/check.sh"}]}]}}'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_success
+}
+
+@test "hook: a script path escaping the package is a FAIL" {
+    write_hook hooks.json '{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"${PLUGIN_ROOT}/../outside.sh"}]}]}}'
+    touch "$TMPDIR/outside.sh"
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_failure
+    assert_output --partial "resolves outside the package"
+}
+
+@test "hook: \${CLAUDE_PLUGIN_ROOT} is a SUGGESTION, not a FAIL" {
+    write_hook hooks.json '{"hooks":{"SessionStart":[{"matcher":"startup","hooks":[{"type":"command","command":"${CLAUDE_PLUGIN_ROOT}/.apm/hooks/scripts/check.sh","timeout":5}]}]}}'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_success
+    assert_output --partial "SUGGESTION  uses \${CLAUDE_PLUGIN_ROOT}"
+}
+
+@test "hook: a deprecated filename-routing stem is a SUGGESTION" {
+    write_hook claude-hooks.json '{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"true"}]}]}}'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/claude-hooks.json"
+    assert_success
+    assert_output --partial "deprecated hook filename routing"
+}
+
+@test "hook: a symlinked hook file is a FAIL" {
+    write_hook real.json '{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"true"}]}]}}'
+    ln -s real.json "$PKG/.apm/hooks/link.json"
+    run bash "$SCRIPT" "$PKG/.apm/hooks/link.json"
+    assert_failure
+    assert_output --partial "is a symlink"
+}
+
+@test "hook: a hardlinked hook file is not a FAIL (find_hook_files skips symlinks only)" {
+    write_hook real.json '{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"true"}]}]}}'
+    ln "$PKG/.apm/hooks/real.json" "$PKG/.apm/hooks/linked.json"
+    run bash "$SCRIPT" "$PKG/.apm/hooks/linked.json"
+    assert_success
+    refute_output --partial "hardlink"
+}
+
+@test "hook: an absolute script path is a FAIL; an absolute interpreter path is not" {
+    write_hook hooks.json '{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"/usr/local/bin/check.sh","timeout":5}]}]}}'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_failure
+    assert_output --partial "is an absolute path"
+
+    write_hook hooks.json '{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"/usr/bin/env true","timeout":5}]}]}}'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_success
+    refute_output --partial "absolute path"
+}
+
+@test "hook: a bare relative path to a package script is a FAIL; a bare command is not" {
+    write_hook hooks.json '{"hooks":{"Stop":[{"hooks":[{"type":"command","command":".apm/hooks/scripts/check.sh","timeout":5}]}]}}'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_failure
+    assert_output --partial "is a bare relative path"
+
+    write_hook hooks.json '{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"npx some-tool --check","timeout":5}]}]}}'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_success
+    refute_output --partial "bare relative path"
+}
+
+@test "hook: a file contributing no entries is a FAIL" {
+    write_hook hooks.json '{"hooks":{}}'
+    run bash "$SCRIPT" "$PKG/.apm/hooks/hooks.json"
+    assert_failure
+    assert_output --partial "contributes no hook entries"
+}
+
+# ---------------------------------------------------------------------------
+# Instructions
+# ---------------------------------------------------------------------------
+
+@test "instruction: description, applyTo and a body pass clean" {
+    write_instruction python 'description: Python style rules
+applyTo: "**/*.py"' 'Use type hints on public functions.'
+    run bash "$SCRIPT" "$PKG/.apm/instructions/python.instructions.md"
+    assert_success
+    refute_output --partial "FAIL"
+    refute_output --partial "SUGGESTION"
+}
+
+@test "instruction: missing description is a FAIL" {
+    write_instruction python 'applyTo: "**/*.py"' 'Use type hints.'
+    run bash "$SCRIPT" "$PKG/.apm/instructions/python.instructions.md"
+    assert_failure
+    assert_output --partial "'description' is missing or empty"
+}
+
+@test "instruction: an empty body is a FAIL" {
+    write_instruction python 'description: x
+applyTo: "**/*.py"' ''
+    run bash "$SCRIPT" "$PKG/.apm/instructions/python.instructions.md"
+    assert_failure
+    assert_output --partial "body is empty"
+}
+
+@test "instruction: invalid frontmatter YAML is a FAIL" {
+    write_instruction python 'description: [unclosed' 'body'
+    run bash "$SCRIPT" "$PKG/.apm/instructions/python.instructions.md"
+    assert_failure
+    assert_output --partial "frontmatter is not valid YAML"
+}
+
+@test "instruction: no applyTo is a SUGGESTION (deliberate always-on), not a FAIL" {
+    write_instruction general 'description: General rules' 'Be kind.'
+    run bash "$SCRIPT" "$PKG/.apm/instructions/general.instructions.md"
+    assert_success
+    assert_output --partial "SUGGESTION  no applyTo"
+}
+
+@test "instruction: a YAML-list applyTo and unread keys are SUGGESTIONs" {
+    write_instruction python 'description: x
+applyTo:
+  - "**/*.py"
+name: python' 'body'
+    run bash "$SCRIPT" "$PKG/.apm/instructions/python.instructions.md"
+    assert_success
+    assert_output --partial "applyTo is a YAML list"
+    assert_output --partial "frontmatter key(s) name"
+}
+
+@test "instruction: an applyTo that is present but empty is a FAIL" {
+    write_instruction empty 'description: x
+applyTo: ""' 'body'
+    run bash "$SCRIPT" "$PKG/.apm/instructions/empty.instructions.md"
+    assert_failure
+    assert_output --partial "applyTo is present but empty"
+    refute_output --partial "SUGGESTION  no applyTo"
+}
+
+@test "instruction: an applyTo glob with unbalanced braces is a FAIL" {
+    write_instruction broken 'description: x
+applyTo: "**/*.{py"' 'body'
+    run bash "$SCRIPT" "$PKG/.apm/instructions/broken.instructions.md"
+    assert_failure
+    assert_output --partial "unbalanced braces or brackets"
+}
+
+@test "instruction: a top-level comma list with a brace group passes clean" {
+    write_instruction multi 'description: x
+applyTo: "**/*.py, **/*.{pyi,pyx}"' 'body'
+    run bash "$SCRIPT" "$PKG/.apm/instructions/multi.instructions.md"
+    assert_success
+    refute_output --partial "applyTo"
+}
+
+@test "instruction: the same stem at the package root is a FAIL" {
+    write_instruction python 'description: x
+applyTo: "**/*.py"' 'body'
+    cp "$PKG/.apm/instructions/python.instructions.md" "$PKG/python.instructions.md"
+    run bash "$SCRIPT" "$PKG/.apm/instructions/python.instructions.md"
+    assert_failure
+    assert_output --partial "also exists at the package root"
+}
+
+@test "instruction: a hardlinked instruction file is a FAIL" {
+    write_instruction python 'description: x
+applyTo: "**/*.py"' 'body'
+    ln "$PKG/.apm/instructions/python.instructions.md" "$TMPDIR/python.instructions.md"
+    run bash "$SCRIPT" "$PKG/.apm/instructions/python.instructions.md"
+    assert_failure
+    assert_output --partial "is a hardlink"
+}
+
+# ---------------------------------------------------------------------------
+# Prompts
+# ---------------------------------------------------------------------------
+
+@test "prompt: declared and used inputs with a plain description pass clean" {
+    write_prompt review-pr 'description: Review a pull request with gitea-prs and factory-audit, then summarize.
+input:
+  - pr_number: "The PR to review"' 'Review PR ${input:pr_number} with gitea-prs.'
+    run bash "$SCRIPT" "$PKG/.apm/prompts/review-pr.prompt.md"
+    assert_success
+    refute_output --partial "FAIL"
+    refute_output --partial "SUGGESTION"
+}
+
+@test "prompt: missing description is a FAIL" {
+    write_prompt review-pr 'model: sonnet' 'Review the PR.'
+    run bash "$SCRIPT" "$PKG/.apm/prompts/review-pr.prompt.md"
+    assert_failure
+    assert_output --partial "'description' is missing or empty"
+}
+
+@test "prompt: the upstream docs' - name: x / description: form is a FAIL" {
+    write_prompt review-pr 'description: Review a PR.
+input:
+  - name: pr_number
+    description: The PR' 'Review ${input:pr_number}.'
+    run bash "$SCRIPT" "$PKG/.apm/prompts/review-pr.prompt.md"
+    assert_failure
+    assert_output --partial "yields arguments [name, description]"
+}
+
+@test "prompt: an invalid input name is a FAIL" {
+    write_prompt review-pr 'description: Review a PR.
+input: [1pr]' 'Review.'
+    run bash "$SCRIPT" "$PKG/.apm/prompts/review-pr.prompt.md"
+    assert_failure
+    assert_output --partial "input name '1pr' does not match"
+}
+
+@test "prompt: an undeclared \${input:x} and an unused input are both FAILs" {
+    write_prompt review-pr 'description: Review a PR.
+input: [pr_number]' 'Review ${input:branch}.'
+    run bash "$SCRIPT" "$PKG/.apm/prompts/review-pr.prompt.md"
+    assert_failure
+    assert_output --partial "input: does not declare 'branch'"
+    assert_output --partial "input 'pr_number' is declared but the body never uses"
+}
+
+@test "prompt: \${input:x} with no input: declared is a FAIL" {
+    write_prompt review-pr 'description: Review a PR.' 'Review ${input:pr_number}.'
+    run bash "$SCRIPT" "$PKG/.apm/prompts/review-pr.prompt.md"
+    assert_failure
+    assert_output --partial "but no input: is declared"
+}
+
+@test "prompt: a trigger clause, an over-long description, dropped keys and camelCase aliases are SUGGESTIONs" {
+    local long
+    long="Use when the user wants a PR reviewed. $(printf 'x%.0s' $(seq 1 240))"
+    write_prompt review-pr "description: $long
+mode: agent
+allowedTools: Bash" 'Review the PR.'
+    run bash "$SCRIPT" "$PKG/.apm/prompts/review-pr.prompt.md"
+    assert_success
+    assert_output --partial "'Use when' trigger clause"
+    assert_output --partial "characters (> 250)"
+    assert_output --partial "frontmatter key(s) mode are dropped on Claude"
+    assert_output --partial "'allowedTools' — use the kebab-case spelling"
+}
+
+@test "prompt: argument-hint alongside input: is a SUGGESTION" {
+    write_prompt review-pr 'description: Review a PR.
+argument-hint: <pr>
+input: [pr_number]' 'Review ${input:pr_number}.'
+    run bash "$SCRIPT" "$PKG/.apm/prompts/review-pr.prompt.md"
+    assert_success
+    assert_output --partial "argument-hint is set alongside input:"
+}
+
+@test "prompt: no procedure heuristic — a long, stepped body is not a script finding" {
+    write_prompt review-pr 'description: Review a PR.' "## Step 1
+$(printf 'line\n%.0s' $(seq 1 80))
+## Gotchas
+- x"
+    run bash "$SCRIPT" "$PKG/.apm/prompts/review-pr.prompt.md"
+    assert_success
+    refute_output --partial "SUGGESTION"
+}
+
+@test "prompt: a hardlinked prompt file is a FAIL" {
+    write_prompt review-pr 'description: Review a pull request with gitea-prs.' 'Review the PR with gitea-prs.'
+    ln "$PKG/.apm/prompts/review-pr.prompt.md" "$TMPDIR/review-pr.prompt.md"
+    run bash "$SCRIPT" "$PKG/.apm/prompts/review-pr.prompt.md"
+    assert_failure
+    assert_output --partial "is a hardlink"
+}

plugins/kyberforge/.apm/skills/forge/SKILL.md

@@ -2,13 +2,12 @@
 name: forge
 description: >
   Use when the user wants to build or improve something but has not yet named
-  the artifact type — skill, agent, plugin, or marketplace entry; "not sure if
-  this should be a skill or a plugin", "I have an idea but don't know where it
-  belongs". Routes to the matching author skill. Do not use when the type is
-  already named — invoke `skill-author`, `agent-author` or `apm-workflow`
-  directly.
+  the artifact type; "not sure if this should be a skill or a plugin", "I have
+  an idea but don't know where it belongs". Routes to the matching author
+  skill. Do not use when the type is already named — invoke `skill-author`,
+  `agent-author`, `primitive-author` or `apm-workflow` directly.
 metadata:
-  version: "1.0.1"
+  version: "1.0.2"
   category: factory
   source_keys:
     - claude-code-subagents-docs
@@ -18,7 +17,7 @@ metadata:
 
 ## Gotchas
 
-- forge is an optional guided entry point, not a gate — `skill-author`, `agent-author`, `factory-audit` and `apm-workflow` all stay directly invokable, and forge never intercepts a direct call to one.
+- forge is an optional guided entry point, not a gate — `skill-author`, `agent-author`, `primitive-author`, `factory-audit` and `apm-workflow` all stay directly invokable, and forge never intercepts a direct call to one.
 - Claude Code's skill-level `context: fork` frontmatter field and the `/fork` subagent command are opposites despite the shared word: `context: fork` isolates (fresh context, no parent access), while `/fork` inherits the full conversation. The route reference each classification loads spends that distinction: `references/author-routes.md` chooses between the two, `references/apm-routes.md` rules the fork out.
 
 ## Step 1 — Grill the intent
@@ -37,12 +36,13 @@ Match the grilled intent against exactly one row — or more than one, if the in
 |---|---|---|---|
 | A reusable capability the agent loads inline in the main conversation, triggered by description-matching, free to bundle its own `references/`, `scripts/` or `assets/` | Skill | `skill-author` | `references/author-routes.md` |
 | A recurring task needs its own reusable definition — dedicated system prompt, tools and description, invokable by name across sessions | Agent / subagent | `agent-author` | `references/author-routes.md` |
+| A runtime callback at a harness event, a rule scoped to a file pattern, or a reusable user-typed message steering existing skills or agents | Hook / instruction / prompt | `primitive-author` | `references/author-routes.md` |
 | A new distributable unit — no existing plugin is the right home for the skill, agent, hook or MCP server being built, or the bundle needs its own manifest, versioning and install lifecycle | Plugin | `apm-workflow` (`apm plugin init`) | `references/apm-routes.md` |
 | The plugin already exists and only its marketplace-facing metadata changes — a first listing, or a version/description update, never the plugin's contents | Marketplace entry | `apm-workflow` (`apm marketplace package add`) | `references/apm-routes.md` |
 
 The table classifies what to build, not how to run it: a one-off task that merely needs an isolated or context-inheriting run is not an artifact and has no row here. If the intent stays genuinely ambiguous between rows after grilling, ask the user rather than guessing.
 
-A real artifact that matches no row — a hook, an MCP server, an AGENTS.md, a research doc — has no route here. Say so, hand the user the skill that does own it, and never bend it into a row to make the table fit.
+A real artifact that matches no row — an MCP server, an AGENTS.md, a research doc — has no route here. Say so, hand the user the skill that does own it, and never bend it into a row to make the table fit.
 
 When the intent spans several rows, chain the routes in dependency order — an artifact that must exist on disk before another skill can target it goes first, so `apm-workflow` scaffolds the plugin directory before `skill-author` scaffolds a skill inside it.
 
@@ -51,4 +51,4 @@ When the intent spans several rows, chain the routes in dependency order — an
 ## Step 3 — Closing gates, common to every route
 
 - **Resolve before closing.** A route is finished only when its verification reports nothing unresolved. An actionable finding reopens the route; it is never reported onward as a caveat.
-- **Bump the package version.** A skill route always lands here: `skill-author` moves only a skill's own `metadata.version`, which is not the package `apm.yml`'s number — so read `references/version-bump.md` after one. `agent-author` and the apm routes bump the package themselves at plugin scope; after those, read it only when their output does not say they did.
+- **Bump the package version.** A skill route always lands here: `skill-author` moves only a skill's own `metadata.version`, which is not the package `apm.yml`'s number — so read `references/version-bump.md` after one. `agent-author`, `primitive-author` and the apm routes bump the package themselves at plugin scope; after those, read it only when their output does not say they did.

plugins/kyberforge/.apm/skills/forge/references/apm-routes.md

@@ -21,7 +21,7 @@ checkpoints to the user in real time.
 
 ## No clean-context recheck, and no automatic audit
 
-Skill and agent routes close with a clean-context audit rerun; these two do not, and the omission
+Skill, agent and primitive routes close with a clean-context audit rerun; these two do not, and the omission
 is deliberate rather than an oversight. Neither artifact type has an audit skill counterpart to
 re-run, so detaching the route to earn a recheck it would never get buys nothing.
 

plugins/kyberforge/.apm/skills/forge/references/author-routes.md

@@ -3,12 +3,13 @@ source_keys:
   - claude-code-subagents-docs
 ---
 
-# Routing a skill or agent to its author skill
+# Routing a skill, agent, hook, instruction or prompt to its author skill
 
-Reached from `SKILL.md` Step 2 when the classified artifact is a skill or an agent/subagent
-definition. Route a skill to `skill-author` and an agent to `agent-author`. The two branches
-differ on the author skill only — both verify the result with `factory-audit`, which detects the
-artifact type itself — and everything below applies to both.
+Reached from `SKILL.md` Step 2 when the classified artifact is a skill, an agent/subagent
+definition, or a hook, instruction or prompt. Route a skill to `skill-author`, an agent to
+`agent-author`, and a hook, instruction or prompt to `primitive-author`. The branches differ on
+the author skill only — all verify the result with `factory-audit`, which detects the artifact type
+itself — and everything below applies to all of them.
 
 ## Choose fork or inline
 
@@ -25,8 +26,8 @@ Fall back to an **inline invocation** — same conversation, no subagent — whe
 
 ## Two-tier verification
 
-Both author skills already close out with their own inline audit, in the same context as the
-authoring work: `skill-author` and `agent-author` each invoke `factory-audit` on what they wrote.
+Every author skill already closes out with its own inline audit, in the same context as the
+authoring work: `skill-author`, `agent-author` and `primitive-author` each invoke `factory-audit` on what they wrote.
 That is tier one, and forge does not change it.
 
 Tier two belongs to forge. Once the author skill's run has finished, spin up a separate

plugins/kyberforge/.apm/skills/forge/references/sources.md

@@ -28,7 +28,7 @@
 
 - **URL:** https://agentskills.io/specification.md
 - **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md
-- **Description:** Complete SKILL.md format specification — confirms `assets/`, `references/`, and `scripts/` are warranted only by the bulk/reusability of supporting content (large reference material, executable code, templates), not by a skill's category, and forge's per-route procedures are that kind of supporting content — so the spec permits the `references/` split here but does not require it. The warrant is a house decision: dispatch is mandatory at two or more mutually exclusive flows, which forge's four-row table is. `references/sources.md` likewise exists for this repo's own provenance-chain convention (see `CONTEXT.md`), not because the spec requires it.
+- **Description:** Complete SKILL.md format specification — confirms `assets/`, `references/`, and `scripts/` are warranted only by the bulk/reusability of supporting content (large reference material, executable code, templates), not by a skill's category, and forge's per-route procedures are that kind of supporting content — so the spec permits the `references/` split here but does not require it. The warrant is a house decision: dispatch is mandatory at two or more mutually exclusive flows, which forge's five-row table is. `references/sources.md` likewise exists for this repo's own provenance-chain convention (see `CONTEXT.md`), not because the spec requires it.
 - **Contributing files:** SKILL.md
 - **Status:** `extracted`
 

plugins/kyberforge/.apm/skills/forge/references/version-bump.md

@@ -7,8 +7,9 @@ source_keys:
 
 Reached from `SKILL.md` Step 3 after a route has finished. A skill route always lands here:
 `skill-author` moves only a skill's own `metadata.version`, which is not the package manifest's
-number, so the package version is still behind when it reports done. `agent-author` bumps the
-resolved package's `apm.yml` itself at plugin/APM scope, and `apm-workflow`'s configure flow
+number, so the package version is still behind when it reports done. `agent-author` and
+`primitive-author` bump the resolved package's `apm.yml` themselves at plugin/APM scope, and
+`apm-workflow`'s configure flow
 carries the same policy — read those routes' output before acting here, because a second bump for
 one change is wrong.
 

plugins/kyberforge/.apm/skills/primitive-author/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: primitive-author
+description: >
+  Use when the user wants an apm hook, instruction or prompt file created, or
+  audit findings or feedback applied to an existing one. Not read-only
+  review -> factory-audit. Not skills -> skill-author. Not agents -> agent-author.
+allowed-tools: Bash Read Write Edit
+metadata:
+  version: "0.1.0"
+  category: factory
+  source_keys:
+    - apm-cli-installed-source
+    - apm-docs-llms-full
+---
+
+## Gotchas
+
+- `apm compile --validate` is not a gate: it reports instruction problems only as warnings, exits 0, and never reads prompts. `apm install` fails only on a hook payload Copilot would reject, and merely warns on bad prompt input names and dropped keys — `/factory-audit` is the only check that fails on the rest.
+- Never draft with the real suffix outside `.apm/<type>/`. apm's local discovery globs `**/*.instructions.md` across the whole tree, so a draft or template named that way anywhere in the repo is picked up as a real instruction. The templates carry a trailing `.template` for this reason; drop it only on the final path.
+- Never hand-write `.claude/settings.json`, even to test a hook. apm owns that file (ADR-0019), overwrites it outright when it is malformed, and `apm audit --ci` fails on anything it would not have written.
+
+## Step 1 — Dispatch
+
+| Target or intent | Type | Reference |
+|---|---|---|
+| A hook — `.apm/hooks/<name>.json`, or "run X whenever Y happens" | hook | `references/hook.md` |
+| An instruction — `.apm/instructions/<name>.instructions.md`, or a rule for files matching a pattern | instruction | `references/instruction.md` |
+| A prompt — `.apm/prompts/<name>.prompt.md`, or a reusable message the user types to kick off work | prompt | `references/prompt.md` |
+| A skill or an agent | — | stop: route to `skill-author` or `agent-author` |
+
+Read only the reference matching the resolved type — each is self-contained. If the target sits inside a git worktree, capture `rtk git log --oneline -1` before touching the filesystem; Step 4 needs it.
+
+## Step 2 — Boundary gate
+
+Run the reference's **Gate** section before writing anything. A failed gate stops this skill: name the owner it points to — `skill-author` for procedure, `agentsmd-author` for a repo-only rule, `apm-workflow` for reach or `targets:` — and hand over. Never bend the artifact to pass the gate.
+
+## Step 3 — Create or improve
+
+| Condition | Action |
+|---|---|
+| No file at the target path | Create: copy the reference's template from `assets/templates/`, drop `.template`, fill every `FILL IN` and `FILL_IN_` placeholder, and apply the reference's checklist |
+| File exists, at least one signal | Improve: read the whole file, then apply each signal against the reference's checklist |
+| File exists, no signal | Stop and ask whether the user meant a new file or has feedback to apply |
+
+Signals: grill output, `/factory-audit` findings, inline feedback, session context describing what went wrong. Group findings by root cause and fix the cause once.
+
+## Step 4 — Validate and close
+
+1. Run `/factory-audit` on the file, inline in this context; resolve every FAIL before reporting done, including the `### Prose` FAILs Vale raises on an instruction or prompt body.
+2. Run `rtk apm install --dry-run` from the repo root and read what each target will receive. On a feature branch, discard `apm.lock.yaml` churn afterwards (`rtk git checkout -- apm.lock.yaml`).
+3. Bump the owning package's `apm.yml` `version:` — minor for a new hook, instruction or prompt, patch for a fix — unless this branch already bumped it for unreleased work. None of these has a version of its own.
+4. **Commit verification.** Inside a git worktree, once the audit is clean, run `rtk git add` and `rtk git commit`, then re-run `rtk git log --oneline -1` and confirm the hash changed from Step 1's. Staged-but-uncommitted work is silently lost if the tree is cleaned up. Outside a worktree, report done on a clean audit and name that as the reason.

plugins/kyberforge/.apm/skills/primitive-author/assets/templates/hook.json.template

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "FILL_IN_PascalCaseEvent": [
+      {
+        "matcher": "FILL_IN_matcher",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${PLUGIN_ROOT}/.apm/hooks/FILL_IN_script.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

plugins/kyberforge/.apm/skills/primitive-author/assets/templates/name.instructions.md.template

@@ -0,0 +1,7 @@
+---
+description: "FILL IN: one sentence on what this rule governs"
+applyTo: "FILL IN: glob, e.g. **/*.{ts,tsx}"
+---
+
+FILL IN: the rule, as direct second-person guidance. Put any rationale Claude needs here — the
+description above never reaches Claude.

plugins/kyberforge/.apm/skills/primitive-author/assets/templates/name.prompt.md.template

@@ -0,0 +1,8 @@
+---
+description: "FILL IN: one user-facing action naming the skills or agents it steers"
+input:
+  - FILL_IN_name: "FILL IN: what the user supplies"
+---
+
+FILL IN: the message the user would otherwise type, steering existing skills or agents by name.
+Use ${input:FILL_IN_name} where the value belongs.

plugins/kyberforge/.apm/skills/primitive-author/references/hook.md

@@ -0,0 +1,94 @@
+---
+source_keys:
+  - apm-cli-installed-source
+  - apm-docs-llms-full
+---
+
+# Authoring an apm hook
+
+Reached from `SKILL.md` Step 1 for a hook. Run the Gate, then write against the shape and the
+checklist, then return to `SKILL.md` Step 3.
+
+## Gate
+
+A hook is a runtime callback the harness fires inside its own tool loop — "this must always
+happen at this event", enforced deterministically rather than left to the model. apm's own
+guidance is to reach for a skill, instruction or prompt first, and to treat hooks as opt-in
+surface: they ship to a strict subset of harnesses and are silently skipped everywhere else.
+
+- **Procedure, know-how, or anything the model should decide to do** → a skill. Stop and hand to
+  `skill-author`.
+- **The hook must reach only some harnesses** → reach is set by the package `apm.yml` `targets:`,
+  never by the hook file. Stop and hand to `apm-workflow`. `targets:` is package-wide, so a
+  harness-specific hook in a multi-target package means either a separate package or accepting that
+  the other targets receive it too.
+- **A runtime callback** → continue.
+
+## Shape
+
+One JSON file per concern at `.apm/hooks/<name>.json`, with a plain name. Copy
+`assets/templates/hook.json.template`. Write the canonical shape apm documents and renders per
+target:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {"type": "command", "command": "${PLUGIN_ROOT}/.apm/hooks/check.sh", "timeout": 10}
+        ]
+      }
+    ]
+  }
+}
+```
+
+- **`${PLUGIN_ROOT}`** is the target-neutral token; apm rewrites it per target
+  (`"${CLAUDE_PROJECT_DIR}/.claude/hooks/<pkg>/…"` on Claude, repo-relative elsewhere).
+  `${CLAUDE_PLUGIN_ROOT}` is rewritten identically, so it is valid, but it ties the source to one
+  harness's name (Should 12).
+- **Claude is the verified target.** apm 0.28.0 passes this nested shape to Copilot without
+  reshaping it, and whether Copilot CLI runs nested entries or honours `matcher` is unverified. That
+  gap is apm's to close. Per-file target routing is deprecated, so a Copilot-native flat hook
+  (`bash` / `powershell` / `timeoutSec`) can only live in a separate Copilot-targeted package — hand
+  that to `apm-workflow` rather than adding a second file here.
+
+## Checklist
+
+Must:
+
+1. The file sits directly in `.apm/hooks/`, is not a symlink, and parses as a JSON object. apm
+   skips invalid JSON silently. (apm also discovers a package-root `hooks/`, and `factory-audit`
+   accepts it for third-party packages; author in `.apm/hooks/`.)
+2. Use the wrapped shape `{"hooks": {Event: [...]}}`. If a naked settings slice is used instead,
+   every top-level value must be a list, with no stray scalar keys anywhere.
+3. Every event value is a list of objects, and every nested `hooks` is a list of objects. Anything
+   else fails the Copilot install outright. The file contributes at least one entry: an empty one
+   deploys nothing, with only a warning.
+4. Event names are PascalCase (`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`,
+   `Stop`, …). An all-lowercase name (`stop`) never warns and never fires; a camelCase name outside
+   apm's rename map (`userPromptSubmit`) deploys verbatim to Claude and never fires.
+5. The script is referenced as `${PLUGIN_ROOT}/…` (or `${CLAUDE_PLUGIN_ROOT}/…`, see Shape) for
+   the package root, or `./…` for the hook directory, and exists inside the package. No absolute
+   path and no bare relative path (`scripts/x.sh`): apm bundles and rewrites neither. No `$` or
+   backtick in the path itself. A missing script is only a warning at install time.
+6. A script run directly as the command's first token is executable. This is stricter than the
+   research's Should: without it the hook fails every time it fires. A script passed to an
+   interpreter (`bash ${PLUGIN_ROOT}/x.sh`) needs no executable bit.
+
+Should:
+
+7. Every handler sets `"type": "command"` and an explicit `timeout` in seconds — apm passes `type`
+   through but never supplies it.
+8. Set `matcher` explicitly on tool events and on `SessionStart` (`startup`, `resume`, …). Omitted,
+   Claude receives `"*"`.
+9. Do not author Copilot's flat `bash` / `powershell` / `timeoutSec` keys in a Claude-shaped file;
+   they render onto Claude as stray keys.
+10. Quote a script path that may contain spaces: `"${PLUGIN_ROOT}/scripts/my hook.sh"`.
+11. Keep helper files in the hook directory non-JSON. Copilot's loader rejects any bundled `.json`
+    without a `hooks` key.
+12. Prefer `${PLUGIN_ROOT}` over `${CLAUDE_PLUGIN_ROOT}`.
+13. No `hooks-<target>` or `*-<target>-hooks` filename. That routing is deprecated and reach belongs
+    to `targets:` (see Gate); the research allows it only when deprecated routing is intended.

plugins/kyberforge/.apm/skills/primitive-author/references/instruction.md

@@ -0,0 +1,54 @@
+---
+source_keys:
+  - apm-cli-installed-source
+  - apm-docs-llms-full
+---
+
+# Authoring an apm instruction
+
+Reached from `SKILL.md` Step 1 for an instruction. Run the Gate, then write against the checklist,
+then return to `SKILL.md` Step 3.
+
+## Gate
+
+An instruction is a scoped rule: it applies when the agent touches files matching its `applyTo`
+glob. On Claude it deploys to `.claude/rules/<stem>.md` with `applyTo` renamed to `paths:`.
+
+- **A rule for this repo alone** → it belongs in the repo's AGENTS.md, which is the single
+  always-on source. Stop and hand to `agentsmd-author`.
+- **No file pattern fits** → an instruction without `applyTo` is always-on in every session of
+  every repo that installs this package, and `apm compile` can fold it into the global sections of
+  `AGENTS.md` and `CLAUDE.md` (skipped when `.github/instructions/` or `.claude/rules/` is already
+  populated, unless `--force-instructions`). Say exactly that to the user and continue only on an explicit yes.
+  Legitimate when a package deliberately ships guidance to its consumers; never a default.
+- **Procedure the agent follows step by step** → a skill. Stop and hand to `skill-author`.
+- **A rule scoped to a file pattern** → continue.
+
+## Checklist
+
+Copy `assets/templates/name.instructions.md.template` and drop `.template` only on the final path.
+
+Must:
+
+1. The path is `.apm/instructions/<stem>.instructions.md`, directly in that directory, not a
+   symlink or hardlink.
+2. `description` is a non-empty string. apm only warns when it is missing.
+3. The body is non-empty after trimming whitespace. apm deploys an empty rule silently.
+4. `applyTo` is a non-empty glob or comma-separated list — top-level commas only as separators,
+   alternation inside `{}` (`"**/*.{ts,tsx}"`), braces and brackets balanced — or absent after the
+   Gate's explicit yes. An empty `applyTo: ""` is neither.
+5. The stem is unique across the package and its dependencies: a `.claude/rules/<stem>.md`
+   collision is silently overwritten.
+
+Should:
+
+6. Write `applyTo` as a scalar string, not a YAML list. Copilot receives the source verbatim, and
+   its handling of a list is unverified.
+7. Keep frontmatter to `description` and `applyTo`, plus optional `author` and `version`. No target
+   consumes other keys, and Claude drops them.
+8. Put any rationale Claude needs in the body. `description` never reaches Claude — it survives only
+   for Copilot and as Cursor's index text.
+9. Keep relative markdown links resolvable from the source file.
+10. Check the glob against the tree: one that matches nothing here fires only in consumer repos
+    that have such files, and one broader than the rule's real scope spends context on every file
+    it touches.

plugins/kyberforge/.apm/skills/primitive-author/references/prompt.md

@@ -0,0 +1,66 @@
+---
+source_keys:
+  - apm-cli-installed-source
+  - apm-docs-llms-full
+  - adr-0029-prompt-house-rule
+---
+
+# Authoring an apm prompt
+
+Reached from `SKILL.md` Step 1 for a prompt. Run the Gate, then write against the description
+contract and the checklist, then return to `SKILL.md` Step 3.
+
+## Gate
+
+This repo holds a prompt to ADR-0029, which is stricter than apm: apm calls a prompt "a callable
+program", but on Claude it deploys as a command that is a skill in every respect except that it
+keeps fewer frontmatter keys, apm drops `disable-model-invocation` so it can never be made
+user-only, and Codex receives no prompts at all. A prompt that carries procedure is therefore a
+worse skill on every harness.
+
+- **Reusable know-how, steps, gotchas, bundled files, or anything the model should find on its
+  own** → a skill. Stop and hand to `skill-author`; if a short steering message is still wanted
+  afterwards, come back and write it against the new skill.
+- **A single-intent message the user would otherwise type repeatedly, steering existing skills or
+  agents by name** → continue. Confirm each skill or agent it names exists and is not
+  `disable-model-invocation: true`: the prompt's body reaches the model, and the model cannot
+  invoke a skill that sets it, so the steering would dead-end (the same check `factory-audit`'s
+  prompt flow applies).
+
+## Description contract
+
+One plain, user-facing sentence stating the action and naming the skills or agents it steers — "Review the
+current PR with `gitea-prs` and `factory-audit`, then summarise the findings." No "Use when"
+trigger clause and no `Not X -> Y` boundary: on Claude the description is model-visible, and a
+trigger clause invites the router to pick the wrapper over the skills it wraps.
+
+## Checklist
+
+Copy `assets/templates/name.prompt.md.template` and drop `.template` only on the final path.
+
+Must:
+
+1. The path is `.apm/prompts/<name>.prompt.md`, directly in that directory, not a symlink or
+   hardlink. `<name>` is a safe path segment and unique across `.apm/prompts/` and the package
+   root; it becomes the Copilot filename and the Claude `/command` name.
+2. `description` is present and non-empty.
+3. Every `input:` name matches `^[A-Za-z][\w-]{0,63}$`, written in the object form
+   `- pr_number: "The PR to review"`. Never copy apm's published `- name: pr_number` /
+   `description: …` example: apm reads the map's keys, so it produces the arguments `name` and
+   `description`.
+4. Every `${input:x}` in the body is declared in `input:`, and every declared name is used. Without
+   `input:`, no `${input:…}` may appear — it would reach Claude unrewritten.
+
+Should:
+
+5. Frontmatter keys stay within `description`, `allowed-tools`, `model`, `argument-hint` and
+   `input`. Claude drops everything else with only a warning. The exception: a Copilot-only key
+   (`agent`, `tools`, …) that is intended, with its Claude drop accepted and said so.
+6. The description follows the contract above: one plain sentence, no trigger or boundary clause,
+   naming the skills or agents it steers.
+7. Spell keys in kebab-case — `allowed-tools`, `argument-hint` — not the camelCase aliases.
+8. Omit `argument-hint` when `input:` is set; apm synthesises `<a> <b>` from the input names.
+9. Keep one intent per prompt, and write the body as second-person instructions.
+10. Keep `description` to 250 characters or fewer.
+11. Give `model` a slug the target accepts. Copilot ignores `allowed-tools` and `model`, so neither
+    constrains a Copilot run.

plugins/kyberforge/.apm/skills/primitive-author/references/sources.md

@@ -0,0 +1,26 @@
+# Sources
+
+## apm-cli-installed-source
+
+- **URL:** file:///root/.local/pipx/venvs/apm-cli/lib/python3.11/site-packages/apm_cli/
+- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
+- **Description:** Installed apm-cli 0.28.0 source — ground truth for what apm deploys from a hook, instruction or prompt file and what it silently skips or only warns on; every Must/Should checklist item traces to the research docs' Authoring checklists, and the `**/*.instructions.md` local-discovery glob behind the template-suffix Gotcha is `primitives/discovery.py` `LOCAL_PRIMITIVE_PATTERNS`
+- **Contributing files:** SKILL.md, references/hook.md, references/instruction.md, references/prompt.md
+- **Status:** `extracted`
+
+## apm-docs-llms-full
+
+- **URL:** https://microsoft.github.io/apm/llms-full.txt
+- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
+- **Description:** Published apm docs bundle — the "Hooks and commands" guide's canonical hook shape, `${PLUGIN_ROOT}`, reach via `targets:` rather than deprecated filename routing, and "reach for a skill, instruction, or prompt first"; the "Author a prompt" guide's one-intent rule
+- **Contributing files:** SKILL.md, references/hook.md, references/instruction.md, references/prompt.md
+- **Status:** `extracted`
+
+## adr-0029-prompt-house-rule
+
+- **URL:** docs/adr/0029-prompts-are-thin-user-triggered-steering-messages.md
+- **Research doc:** none
+- **Basis:** docs/adr/0029-prompts-are-thin-user-triggered-steering-messages.md
+- **Description:** The repo's prompt house rule — a prompt is a single-intent, user-triggered steering message with no procedure — and its description contract: one user-facing sentence naming the steered skills, no trigger or boundary clause
+- **Contributing files:** references/prompt.md
+- **Status:** `extracted`

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

@@ -6,7 +6,7 @@ description: >
   Not read-only review -> `factory-audit`. Not agent files -> `agent-author`.
 allowed-tools: Bash Read Write Edit
 metadata:
-  version: "1.0.5"
+  version: "1.0.6"
   category: factory
   source_keys:
     - agentskills-home

plugins/kyberforge/.apm/skills/skill-author/references/deployment-modes.md

@@ -40,7 +40,7 @@ These variables are injected when the plugin is loaded from an install cache. Th
 | `${CLAUDE_PLUGIN_ROOT}` | Absolute path to the plugin's install directory. Changes on update. |
 | `${CLAUDE_PLUGIN_DATA}` | Persistent directory that survives updates. Use for `node_modules`, generated state, caches. |
 
-Use `${CLAUDE_PLUGIN_ROOT}` only in hook commands — not in SKILL.md body text, since standalone deployments won't have it.
+Neither belongs in SKILL.md body text, since standalone deployments won't have them. Hook commands are not authored here: hook authoring, including which script-path token to use (the target-neutral `${PLUGIN_ROOT}`), belongs to `primitive-author`.
 
 ## Standalone mode
 

plugins/kyberforge/README.md

@@ -9,7 +9,7 @@ apm is the only supported install path (ADR-0024). Declare this package in the c
 ```yaml
 dependencies:
   apm:
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
+    - git: git@git.rkdr.net:Defame1297/holocron.git
       path: plugins/kyberforge
 ```
 
@@ -19,7 +19,7 @@ Then:
 apm install
 ```
 
-The entry above is unpinned and tracks the remote's default branch — add `ref: <tag>` to pin a release. Registering the catalogue instead (`apm marketplace add git@git.dev.rkdr.net:Defame1297/holocron.git --name holocron`) gets you the `kyberforge@holocron` short name, but writes to `~/.apm/marketplaces.json` at user scope; the git+path object needs nothing beyond the manifest.
+The entry above is unpinned and tracks the remote's default branch — add `ref: <tag>` to pin a release. Registering the catalogue instead (`apm marketplace add git@git.rkdr.net:Defame1297/holocron.git --name holocron`) gets you the `kyberforge@holocron` short name, but writes to `~/.apm/marketplaces.json` at user scope; the git+path object needs nothing beyond the manifest.
 
 **Native plugin installs do not work.** This package ships no per-plugin manifest and no flat content directories, so a host that installs it natively gets zero skills, agents and hooks — and Claude Code raises no error while doing it (ADR-0024).
 
@@ -31,18 +31,19 @@ Authoring source lives in `.apm/`; it is the only content source and the only th
 |---|---|---|
 | Skills | `.apm/skills/` | Slash commands available after install |
 | Agents | `.apm/agents/*.agent.md` | Role-based agents; one vendor-neutral `.agent.md` per agent (ADR-0016) |
-| Hooks | `.apm/hooks/` | Event-triggered automation — Claude Code only, see below |
+| Hooks | `.apm/hooks/` | Event-triggered automation — authored for Claude Code, see below |
 
-**Hooks are Claude Code-only.** apm merges `.apm/hooks/*.json` into the consuming project's `.claude/settings.json` at install. Copilot CLI has no default hooks path — `agents` and `skills` default to `agents/` and `skills/`, but `hooks` defaults to nothing (`docs/research/docs/github-copilot-plugins/configuration.md:47`), so Copilot reads hooks only via an explicit pointer in a plugin manifest — and since ADR-0024 there is no per-plugin manifest to carry one. Copilot therefore loads no hooks from this plugin. Details, including why a pointer was the wrong fix even when a manifest existed, are in `docs/hooks.md`.
+**Hooks are authored for Claude Code, but apm writes them for every package target.** apm merges `.apm/hooks/*.json` into the consuming project's `.claude/settings.json` at install. Because kyberforge also targets Copilot and Codex, apm writes the same hook to `.github/hooks/kyberforge-hooks.json` (nested shape passed through, not reshaped) and into `.codex/hooks.json` when `.codex/` exists. Whether those harnesses execute it is unverified; the hook's behaviour is Claude-specific and it exits silently without an `apm.lock.yaml`. Details are in `docs/hooks.md` and ADR-0019's 2026-09-28 amendment.
 
 ## Skills
 
 | Skill | Description |
 |---|---|
-| `forge` | Grill an unclassified "I want to add something" request, decide whether it's a skill, agent, plugin, or marketplace entry, then route to the matching author skill |
+| `forge` | Grill an unclassified "I want to add something" request, decide whether it's a skill, agent, hook, instruction, prompt, plugin, or marketplace entry, then route to the matching author skill |
 | `skill-author` | Create or improve a skill from scratch, audit findings, or inline feedback |
 | `agent-author` | Author an agent definition file |
-| `factory-audit` | Audit a skill directory or an agent definition — structure, provider safety, description and body quality, and provenance; produces a findings report. Auto-detects which of the two it was handed (ADR-0025) |
+| `primitive-author` | Create or improve an apm hook, instruction or prompt, gated on whether it should be one at all (ADR-0029 for prompts) |
+| `factory-audit` | Audit a skill directory, an agent definition, or an apm hook, instruction or prompt — structure, provider safety, description and body quality, and provenance; produces a findings report. Auto-detects which it was handed (ADR-0025) |
 | `apm-install` | Install or upgrade the apm CLI and set up the agent runtimes it drives (Copilot CLI, Codex, Gemini, generic llm) |
 | `apm-workflow` | Author apm.yml, scaffold an apm package/marketplace, install dependencies, and compile/pack/publish/audit apm content |
 

plugins/kyberforge/apm.yml

@@ -1,13 +1,13 @@
 name: kyberforge
-version: 2.0.0
+version: 2.1.0
 description: Skills and agents for creating, maintaining, and managing an apm plugin marketplace for Claude Code and GitHub Copilot.
 author:
   name: Defame1297
   email: defame1297@rkdr.net
-  url: https://git.dev.rkdr.net/Defame1297/
+  url: https://git.rkdr.net/Defame1297/
 license: MIT
-homepage: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/kyberforge
-repository: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/kyberforge
+homepage: https://git.rkdr.net/Defame1297/holocron/src/branch/main/plugins/kyberforge
+repository: https://git.rkdr.net/Defame1297/holocron/src/branch/main/plugins/kyberforge
 keywords:
   - marketplace
   - plugin

plugins/kyberforge/docs/hooks.md

@@ -43,15 +43,17 @@ an event not listed here.
 
 ## Referencing a script — use the `.apm/` path
 
-Use `${CLAUDE_PLUGIN_ROOT}` to reference scripts inside this plugin; the plugin runs from a cache or
-`apm_modules/` path after install, not its original repo location. **Address the script at its
-`.apm/` path:**
+Use `${PLUGIN_ROOT}` to reference scripts inside this plugin; the plugin runs from a cache or
+`apm_modules/` path after install, not its original repo location. `${PLUGIN_ROOT}` is apm's
+target-neutral token; apm rewrites it exactly as it rewrites `${CLAUDE_PLUGIN_ROOT}` — verified
+byte-identical in the deployed `.claude/settings.json` with apm 0.28.0 — so prefer it, and
+`factory-audit` suggests it. **Address the script at its `.apm/` path:**
 
 ```json
-"command": "${CLAUDE_PLUGIN_ROOT}/.apm/hooks/check-apm-current.sh"
+"command": "${PLUGIN_ROOT}/.apm/hooks/check-apm-current.sh"
 ```
 
-The obvious-looking `${CLAUDE_PLUGIN_ROOT}/hooks/check-apm-current.sh` does not work, and fails
+The obvious-looking `${PLUGIN_ROOT}/hooks/check-apm-current.sh` does not work, and fails
 quietly enough to be worth spelling out. apm resolves the placeholder against the installed package
 root, and there is no `hooks/` directory there at all — the package's content is `.apm/`. apm prints
 `Hook script not found: .../hooks/check-apm-current.sh` and then deploys the hook anyway, pointing at
@@ -105,32 +107,32 @@ stages a genuinely outdated dependency against the **real** `apm` — a local gi
 `url.<path>.insteadOf` rewrites, so it needs no network — and replays that genuine output through the
 hook.
 
-## GitHub Copilot CLI
+## GitHub Copilot CLI and Codex
 
-**Copilot loads no hooks from this plugin.** Two independent reasons, either one sufficient:
+**apm writes this plugin's hook for Copilot and Codex too; whether they run it is unverified.**
+kyberforge's `apm.yml` declares `targets: [claude, copilot, codex]`, and `targets:` is package-wide,
+so the hook reaches every target the package does
+(`plugins/kyberforge/docs/research/docs/microsoft-apm/hooks-primitive-schema.md`, verified against
+apm 0.28.0):
 
-- **Nothing can point Copilot at a hooks file.** Copilot types `hooks` as a `plugin.json` field of
-  type "string or object" with **no default**
-  (`docs/research/docs/github-copilot-plugins/configuration.md:47`), so there is no convention path
-  for it to scan — it reads hooks only via an explicit pointer. Since ADR-0024 there is no
-  per-plugin Copilot manifest at all, so there is nothing to carry that pointer.
-- **The two ecosystems do not share a hooks format.** 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`. apm merges `.apm/hooks/*.json`
-  into one definition with no per-target shaping, and that definition is Claude-shaped.
+- **Copilot** gets `.github/hooks/kyberforge-hooks.json`, one file per source file. apm renames the
+  event (`SessionStart` → `sessionStart`), rewrites the script path, adds `version: 1`, and otherwise
+  passes the nested Claude shape through — it does **not** reshape it into Copilot's flat
+  `bash`/`powershell`/`timeoutSec` form. Whether Copilot CLI executes a nested entry, or honours
+  `matcher`, has not been verified.
+- **Codex** gets the entry merged into `.codex/hooks.json`, but only when `.codex/` already exists;
+  otherwise nothing is written.
 
-The second reason is why "just add a pointer" was rejected even while a Copilot manifest existed: a
-pointer would tell Copilot that a Claude-shaped file is Copilot-shaped, trading an incomplete
-manifest for a wrong one. ADR-0024 consequence 7 records that the question is now moot — the
-manifest it argued about is gone — but the schema mismatch it turned on is not, and it is what any
-future Copilot hooks support has to solve.
+This is accepted rather than fixed (ADR-0019, amendment 2026-09-28). The hook's behaviour is
+Claude-specific anyway — the `startup` matcher, `CLAUDE_PROJECT_DIR`, and the `reloadSkills`
+output — and the script exits silently without an `apm.lock.yaml`, so a harness that does run it is
+unharmed. The only apm-native way to keep it Claude-only is a separate package whose `apm.yml`
+declares `target: claude`; per-file target routing (`claude-hooks.json`) is deprecated, and
+kyberforge cannot narrow its own `targets:` without dropping its skills from Copilot and Codex.
 
-**What this costs you:** a hook authored under `.apm/hooks/` reaches Claude Code and not Copilot.
-That is a real limitation, and it is the accepted one until apm emits a per-target hooks file or the
-two schemas converge. If you need a Copilot hook today, raise it — it needs an upstream change or a
-second authoring path, not a pointer.
+An earlier version of this section said Copilot loads no hooks from this plugin, because nothing
+could point Copilot at a hooks file and apm did no per-target shaping. Both halves are superseded:
+apm deploys the file into Copilot's hooks directory itself, and does rename events per target.
 
 ## Symlinks under `.apm/` do not survive, and nothing reports it
 

plugins/kyberforge/docs/research/docs/microsoft-apm/hooks-primitive-schema.md

@@ -1,59 +1,139 @@
 ---
 topic: hooks-primitive-schema
 source_keys:
-  - context7-microsoft-apm
+  - apm-cli-installed-source
+  - apm-docs-llms-full
   - apm-github-repo
+  - context7-microsoft-apm
 ---
 
-## File location, naming, and format — confirmed `.json`, not assumed
+Ground truth for this file is the installed apm-cli **0.28.0** source (`apm_cli/integration/hook_integrator.py`, `hook_native_formats.py`, `hook_ir.py`, `hook_file_routing.py`, `_hook_dropped_targets.py`, `targets.py`, `security/executables.py`) plus a live `apm install` of a scratch package targeting `claude` and `copilot` (2026-09-28). Where the published docs (`llms-full.txt`) disagree with 0.28.0, the disagreement is called out; the published docs track upstream `main` and may describe a newer release.
 
-`.apm/hooks/*.json` (legacy fallback: bare `hooks/*.json` at package root, still discovered — `_has_hook_json()` checks both `hooks/` and `.apm/hooks/`). This is genuinely JSON, not YAML or Markdown-with-frontmatter like every other primitive — confirmed directly from source (`apm_cli/integration/hook_integrator.py` module docstring: "Integrates hook JSON files...") and from `apm_cli/models/validation.py`, which states a hook-only package's files define "hook handlers per the Claude Code hooks specification" — i.e. the canonical authoring shape APM expects is Claude Code's own native hook JSON shape, not an APM-invented one. This is consistent with APM's general P1 principle (no invented primitive frontmatter/format) extending even to hooks: author in whichever native harness shape you like, and APM normalizes.
+## File location, naming, discovery
 
-**Accepted input shapes** (APM normalizes both into an internal vendor-neutral IR before rendering per target):
+- `HookIntegrator.find_hook_files()` globs `<pkg>/.apm/hooks/*.json` first, then `<pkg>/hooks/*.json` (Claude-native layout). Non-recursive; symlinks skipped; stems deduplicated case-insensitively, so `.apm/hooks/x.json` shadows `hooks/x.json`. `security/executables.scan_package_executables` uses the same two directories.
+- Genuinely JSON, not Markdown-with-frontmatter. There is no `Hook` dataclass in `primitives/models.py`; hooks never enter `discover_primitives()`, so `apm compile` (and `apm compile --validate`) never see them. Hooks are deployed by `apm install` only.
+- **Filename routing (deprecated, still active).** `hook_file_routing._hook_file_allowed_targets` routes a file whose stem is `hooks-<token>` or ends `-<token>-hooks` (tokens: `copilot`, `vscode`, `cursor`, `claude`, `codex`, `gemini`, `antigravity`, `windsurf`, `kiro`) to that target only, with a deprecation warning. If any file for a target is target-specific, universal files are ignored for that target (`specific if specific else universal`). A stem like `claude-hooks.json` is therefore Claude-only. The replacement is `target:`/`targets:` in the package's own `apm.yml`, or object-form per-dependency `targets:` on the consumer side.
+
+## Accepted source shapes
+
+`_parse_hook_json()` accepts:
 
 ```json
-// "Nested" wrapper (what the docs' canonical example shows)
-{ "hooks": { "PreToolUse": [ { "hooks": [ {"type": "command", "command": "./scripts/validate.sh", "timeout": 10} ] } ] } }
+// Wrapped (canonical)
+{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ {"type": "command", "command": "./scripts/check.sh", "timeout": 10} ] } ] } }
 
-// "Naked" top-level settings-slice (Claude Code settings.json shape, unwrapped)
-{ "PreToolUse": [ { "hooks": [ {"type": "command", "command": "./scripts/validate.sh", "timeout": 10} ] } ] }
+// Naked settings slice: promoted to wrapped only if EVERY top-level value is a list
+{ "PreToolUse": [ { "hooks": [ {"type": "command", "command": "./scripts/check.sh"} ] } ] }
+
+// Flat Copilot-style entry (no inner "hooks" array)
+{ "hooks": { "preToolUse": [ {"type": "command", "bash": "./scripts/check.sh", "powershell": "pwsh ./scripts/check.ps1", "timeoutSec": 5} ] } }
 ```
 
-Both are accepted; APM's discovery/parsing layer detects and unwraps either. There is no separate `Hook`/`HookPrimitive` dataclass in `primitives/models.py` (unlike `Instruction`) — hooks are represented instead by a dedicated vendor-neutral IR (`apm_cli/integration/hook_ir.py`): `HookHandler(command, platform="all", timeout_seconds, provenance, metadata)` grouped into `HookBinding(event, handlers, matcher, provenance, metadata)` grouped into `HookDocument(bindings)`. This IR is populated during install-time integration, not during the generic primitive-discovery pass used for instructions/contexts/agents.
+Nested and flat entries can be mixed in one event array. Parse failure modes (all verified live):
 
-**Event names are case-convention-sensitive by target and get remapped, not just passed through.** Author in either PascalCase (Claude convention: `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `Stop`) or camelCase (Copilot convention: `preToolUse`, `postToolUse`, etc.) — `_HOOK_EVENT_MAP` per-target dictionaries translate between them during merge/deploy. An event name whose casing doesn't match the target's expected convention *and* has no explicit mapping entry triggers a non-fatal warning at install time (`_emit_hook_event_diagnostics`) — not a hard failure, but a real signal that the event likely won't fire.
+| Input | Behaviour |
+|---|---|
+| Invalid JSON | File silently skipped. No warning. |
+| `"hooks"` present but not an object | Skipped; `_log.warning` "Skipping malformed hook file ...: 'hooks' must be a dict". |
+| Naked shape plus one stray scalar key (such as `"description"`) | Not promoted. Merge targets warn "Hook file X contributed no entries to claude settings; skipped." **Copilot still writes** a junk `.github/hooks/<pkg>-X.json` containing the original keys plus `"hooks": {}`. |
+| Event value not a list (such as `{"PreToolUse": {...}}`) | Claude: "contributed no entries" warning. Copilot: `_validate_copilot_payload` error "Invalid Copilot hook payload", and **the install fails**. |
 
-**Script path placeholders** are rewritten per target during deploy: `${CLAUDE_PLUGIN_ROOT}/path`, `${CURSOR_PLUGIN_ROOT}/path`, `${PLUGIN_ROOT}/path`, and bare `./path` all get resolved relative to the package root and rewritten to whatever the target expects; bare system commands (no path separators) pass through unchanged.
+## Vendor-neutral IR (`hook_ir.py`, `hook_native_formats.py`)
 
-## Compile-time mapping per target — both are real reconstruction, differently shaped
+`HookHandler(command, platform="all", timeout_seconds, provenance, metadata)` inside `HookBinding(event, handlers, matcher, provenance, metadata)` inside `HookDocument`. The IR is used **only when rendering merge targets** (Claude, Gemini, Antigravity). Copilot never goes through it (see below).
 
-Neither Claude nor Copilot receives a byte-verbatim copy of the source hook JSON — this is a genuine, structural transform on both sides, driven by `apm_cli/integration/hook_native_formats.py` and `hook_integrator.py`.
+`_handler_to_ir` rules:
+- `command` wins. If it is absent, the **first** present key of `bash` (platform `posix`), `powershell` (`windows`) or `windows` (`windows`) becomes `command`. All other keys, including a second platform key, stay in `metadata`.
+- `timeoutSec` wins over `timeout`. Both are treated as seconds.
+- Every other handler key (`type`, `async`, `statusMessage`, `shell`, `env`, `cwd`, arbitrary keys) passes through in `metadata`. **APM has no handler-field allowlist.**
+- `_entries_to_ir`: `matcher` is popped from the entry and kept. A flat entry (no `hooks` list) becomes a one-handler binding. Non-dict entries pass through raw.
 
-**Claude Code — merged into `.claude/settings.json`, not a standalone file.** `claude` is registered in `_MERGE_HOOK_TARGETS` with `config_filename="settings.json"`, `schema_strict=True`. Behavior (per the integrator's own class docstring: "Claude: Merged into .claude/settings.json hooks key + .claude/hooks/<pkg>/"):
-- Event bindings are merged into the `"hooks"` key of `.claude/settings.json`, using Claude's native nested-matcher-group shape (`{"hooks": {"PreToolUse": [{"hooks": [{"type": "command", "command": "...", "timeout": N}]}]}}`), with PascalCase event names.
-- Any referenced script files are physically copied to `.claude/hooks/<package-name>/`, and the `command` field is rewritten to point at the copied location.
-- An ownership sidecar (`apm-hooks.json`) tracks which entries in the shared `settings.json` were APM-installed, so `apm install`/uninstall can cleanly add/remove only its own entries without clobbering hand-authored hooks a user already had in that file.
+## Events: `_HOOK_EVENT_MAP` (0.28.0, verbatim content)
 
-**Copilot CLI — dedicated per-file deployment, flat/camelCase, field-renamed.** `copilot` is deliberately **not** in `_MERGE_HOOK_TARGETS` (confirmed in `_hook_dropped_targets.py`: "Names not registered in `_MERGE_HOOK_TARGETS` (e.g. `copilot`, which uses per-file, not merged, hook deployment...)"). Instead `PrimitiveMapping("hooks", ".json", "github_hooks")` deploys a dedicated file per source hook file. The native Copilot shape differs structurally from Claude's, per the module docstring:
-```json
-{
-  "version": 1,
-  "hooks": { "preToolUse": [ {"type": "command", "bash": "./scripts/validate.sh", "timeoutSec": 10} ] }
-}
-```
-Differences from the Claude/source shape: flat arrays (no nested matcher-group wrapper), camelCase event keys, a required top-level `"version": 1`, and handler commands split by platform (`bash` / `powershell` keys) instead of a single `command` key, with `timeoutSec` replacing `timeout`.
+| Target | Source name → native name |
+|---|---|
+| `copilot` | `PreToolUse`/`preToolUse`→`preToolUse`; `PostToolUse`/`postToolUse`→`postToolUse`; `UserPromptSubmit`/`userPromptSubmit`→`userPromptSubmit`; `SessionStart`/`sessionStart`→`sessionStart`; `Stop`/`AgentStop`/`agentStop`→`agentStop`; `PreTaskExecution`/`preTaskExecution`→`preTaskExecution`; `PostTaskExecution`/`postTaskExecution`→`postTaskExecution` |
+| `claude` | `preToolUse`→`PreToolUse`; `postToolUse`→`PostToolUse`; `SessionStart`/`sessionStart`→`SessionStart`; `Stop`/`AgentStop`/`agentStop`→`Stop` |
+| `gemini` | `PreToolUse`/`preToolUse`→`BeforeTool`; `PostToolUse`/`postToolUse`→`AfterTool`; `Stop`→`SessionEnd` |
+| `kiro` | PascalCase triggers, including `PreTaskExec`, `PostTaskExec`, `PostFileCreate`, `PostFileSave`, `PostFileDelete`, `promptSubmit`→`UserPromptSubmit` |
 
-## Compile-time file placement
+- **No event is dropped.** Any name absent from the map passes through unchanged (`event_map.get(raw, raw)`). For Claude, that means `PreCompact`, `Notification`, `SubagentStop`, `SessionEnd`, `UserPromptSubmit` and others all work as long as they are authored in PascalCase.
+- `_emit_hook_event_diagnostics` warns (non-fatal) only when the name is unmapped **and** `_detect_event_casing` yields the wrong convention. `_HOOK_EVENT_EXPECTED_CASING`: `copilot` expects camelCase; every other target expects PascalCase. All-lowercase names (`notification`, `stop`) return casing `None`, so they **never warn** and silently never fire. Verified live: `userPromptSubmit` warned on Claude, `PreCompact` warned on Copilot, `notification` warned on neither.
+- The Claude map has no `userPromptSubmit`→`UserPromptSubmit` entry. The camelCase spelling is deployed verbatim into `settings.json` and will not fire, so author `UserPromptSubmit`.
+- **Docs vs 0.28.0:** the published "Session lifecycle event aliases" table says `UserPromptSubmit`/`userPromptSubmitted` → Copilot `userPromptSubmitted`. 0.28.0 maps to `userPromptSubmit` and has no `userPromptSubmitted` alias. Which key Copilot CLI actually fires on has not been verified here.
+- Two source events that rename to the same native key are merged (Copilot: list extend; Claude: appended under one key).
 
-| Target | Output location | Mechanism |
-|---|---|---|
-| Claude Code | `.claude/settings.json` (`"hooks"` key, merged) + scripts copied to `.claude/hooks/<pkg>/` | Merge into existing shared config file, ownership tracked via `apm-hooks.json` sidecar |
-| Copilot CLI | `.github/hooks/<name>.json` | Dedicated per-file deploy, reshaped to Copilot's flat/camelCase/`version:1` schema |
+## Per-target rendering
+
+### Claude Code: merged into `.claude/settings.json`
+
+`_MERGE_HOOK_TARGETS["claude"]` = `_MergeHookConfig("settings.json", "claude", require_dir=False, schema_strict=True)`. `_integrate_merged_hooks` then:
+1. Renames events via the Claude map.
+2. Runs `_to_claude_hook_entries`, which is `_render_nested_document(timeout_milliseconds=False, default_matcher="*")`. Every entry becomes `{matcher, hooks:[...]}`. **The source `matcher` is preserved verbatim.** An entry without a matcher gets `"matcher": "*"`, including events such as `Stop` or `UserPromptSubmit` where Claude ignores matchers.
+3. Rewrites script paths (see below) and copies the hook bundle to `.claude/hooks/<pkg>/…`, keeping the path relative to the package root.
+4. Tags entries with `_apm_source`, then strips the tags into the sidecar `.claude/apm-hooks.json` (schema-strict). `settings.json` holds only native fields.
+5. Upsert is idempotent per source marker (`_should_remove_prior_merged_entry`) and deduplicates by content.
+
+**Flat Copilot entry → Claude** (live): `bash` becomes `command`, `timeoutSec` becomes `timeout`, and the **unused `powershell` key and any other extras are left in the Claude handler** (for example `"powershell": "pwsh $env:CLAUDE_PROJECT_DIR/…"`). Whether Claude Code tolerates unknown handler keys has not been verified here.
+
+**Confirmed for this repo:** `plugins/kyberforge/.apm/hooks/hooks.json` (`SessionStart`, `"matcher": "startup"`, `command: ${CLAUDE_PLUGIN_ROOT}/.apm/hooks/check-apm-current.sh`, `timeout: 380`) compiles in `/root/ai-development/.claude/settings.json` to `{"matcher": "startup", "hooks": [{"type": "command", "command": "\"${CLAUDE_PROJECT_DIR}/.claude/hooks/kyberforge/.apm/hooks/check-apm-current.sh\"", "timeout": 380}]}`. Matcher and timeout are kept, and the path is re-anchored and quoted.
+
+### Copilot: one file per source file, *not* reshaped
+
+`integrate_package_hooks()` writes `<root>/hooks/<pkg>-<stem>.json` (project `.github/hooks/`, user `~/.copilot/hooks/`) and copies scripts to `.github/hooks/scripts/<pkg>/…`. **Correction to the earlier version of this doc:** 0.28.0 does *not* flatten, rename `command`→`bash`, or rename `timeout`→`timeoutSec`. The only transforms are:
+- event renaming via the Copilot map
+- script-path rewrite (repo-relative such as `.github/hooks/scripts/<pkg>/scripts/check.sh`; absolute at user scope)
+- `version: 1` injected with `setdefault`
+- `_validate_copilot_payload`: `version == 1`, `hooks` is an object, each event is a list, each entry is an object, and any nested `hooks` is a list of objects. A failure is a diagnostics **error**, the file is not written, and the install reports failure.
+
+So a Claude-shaped source reaches Copilot as nested `{matcher, hooks:[{type, command, timeout}]}` with the matcher preserved (live: `sessionStart` with `"matcher": "startup"`). A flat `bash`/`powershell`/`timeoutSec` entry reaches Copilot unchanged. The hook-integrator docstring describes the Copilot-native shape as flat `{"type": "command", "bash": …, "timeoutSec": …}`; `HOOK_COMMAND_KEYS` comments name `bash`/`powershell` (Copilot agent/CLI) and `command`/`windows`/`linux`/`osx` (VS Code). **Unverified:** whether Copilot CLI executes a nested entry or a `command` key, and whether it honours `matcher`. APM does not guarantee it.
+
+### Platform-specific commands: how to author
+
+- **Claude-only package:** use `command` (POSIX). For Windows, prefix the command with `pwsh`/`powershell`, or set handler `"shell": "powershell"`. `_project_scoped_command_path` then renders `$env:CLAUDE_PROJECT_DIR/...` instead of `"${CLAUDE_PROJECT_DIR}/..."`. Whether Claude Code itself honours a `shell` handler field is not verified here.
+- **Copilot-correct package:** author flat entries with `bash` + `powershell` + `timeoutSec`, which pass to Copilot verbatim. The Claude render takes `bash` as `command` and carries `powershell` along as a stray key.
+- **Both targets, cleanly:** split into per-target packages or files (`target: claude` / `target: copilot` in each package `apm.yml`), because no single source shape renders natively for both in 0.28.0.
+
+### Other targets (brief)
+
+Merge targets: `cursor` (`.cursor/hooks.json`, `version: 1` default), `codex` (`.codex/hooks.json`), `gemini` (`.gemini/settings.json`, timeouts ×1000 ms, nested), `antigravity` (`.agents/hooks.json` under container key `apm`), `windsurf` (`.windsurf/hooks.json`). Everything except Claude has `require_dir=True`: nothing is written unless the target dir exists. `kiro` writes one file per action. `opencode` has no hooks (`unsupported_user_primitives=("hooks",)`), and other hook-less targets are silently skipped.
+
+## Script path rewriting (`_rewrite_command_for_target`)
+
+- Tokens `${CLAUDE_PLUGIN_ROOT}`, `${CURSOR_PLUGIN_ROOT}`, `${KIRO_PLUGIN_ROOT}` and `${PLUGIN_ROOT}` followed by a path resolve against the **package root**. `./path` resolves against the hook file's directory first, then the package root (`_resolve_relative_hook_script`). Both are confined with `ensure_path_within`.
+- The rewrite runs on every key in `HOOK_COMMAND_KEYS` = `command`, `bash`, `powershell`, `windows`, `linux`, `osx`, at entry level and at nested-handler level.
+- Claude project scope: `"${CLAUDE_PROJECT_DIR}/.claude/hooks/<pkg>/<rel>"`, double-quoted unless the source already quoted it. PowerShell uses `$env:CLAUDE_PROJECT_DIR/...`. A target path containing `$` or a backtick raises `ValueError`. Other targets stay repo-relative. User scope (`-g`) uses absolute paths (`_deploy_root_for_hook_rewrite`).
+- Missing script: `_rich_warning("Hook script not found: …")`. The install continues. At project scope the token is left unexpanded; at user scope it is rewritten to the absolute source path.
+- Bare commands with no `./` and no token (`echo hi`, `npx foo`) pass through untouched and are not bundled.
+- `<pkg>` is the dependency install dir name, or for the project's own `.apm/` the `apm.yml` `name` (fallback `_local`).
+
+## Security / trust gate
+
+Hooks are an executable primitive (`security/executables.EXEC_TYPE_HOOKS`). If the consuming project's `apm.yml` has an `allowExecutables` block, dependency hooks are deny-by-default until approved (`apm approve`). Non-interactive runs hard-error. Local project content (`_local`) is always trusted (`install/exec_gate.check_executable_approval`). With no `allowExecutables` block, everything deploys. The pre-deploy hidden-Unicode scan (`install/helpers/security_scan`, `BLOCK_POLICY`) also covers hook files.
 
 ## Validation constraints and gotchas
 
-- **Copilot's native payload has an enforced shape** (`_validate_copilot_payload`): top-level `"version"` must equal `1`; `"hooks"` must be an object; each event's value must be a list; each entry must be an object; if an entry has a `"hooks"` key, its value must be a list of objects. These errors are collected and surfaced before any file is written (fail before mutation, not after).
-- **Malformed existing config fails closed, not silently.** If `.claude/settings.json` (or another merge target's config) is unreadable/malformed JSON, APM leaves it **byte-identical** and logs an actionable warning rather than overwriting or corrupting it — the same fail-closed posture applies to orphaned `apm-hooks.json` sidecars when their native JSON counterpart is already gone.
-- **Dropping a target from `apm.yml`'s `targets:` list does not auto-clean its merged hook entries** unless `apm install`/reconcile logic explicitly walks the complement set (`reconcile_dropped_targets`) — a real, documented gap the code works around rather than a design guarantee; relying on "just remove the target and hooks disappear" is not safe without a fresh `apm install`.
-- **Event-casing mismatches are warnings, not errors** — a hook authored with the wrong casing for a target and no applicable rename mapping will silently not fire at runtime; APM only logs a warning at install time, it does not block the install or refuse to deploy the file.
-- **No dedicated `Hook`/`HookPrimitive` validation dataclass** exists comparable to `Instruction.validate()` — validation is distributed across `_validate_copilot_payload` (Copilot-shape-specific) and general JSON-parseability checks, not a single primitive-level contract. This mirrors the same "no independent validation model" gap already documented for the agent primitive.
+- **Malformed `.claude/settings.json` is overwritten during install.** This corrects the earlier version of this doc. In `_integrate_merged_hooks`, a `JSONDecodeError` on the existing config sets `json_config = {}`, and the rebuilt file is written. Verified live: a malformed file containing `permissions` was replaced and the `permissions` content lost. The "left byte-identical" fail-closed behaviour applies **only** to `reconcile_dropped_targets` (`_hook_dropped_targets.py`) when it cleans a target dropped from `targets:`.
+- **Dropped targets are cleaned.** `manifest_reconcile.reconcile_dropped_merge_hook_targets` runs `reconcile_dropped_targets` on the complement of active and declared targets on the next install/compile/update (published docs agree). Copilot's per-file hooks are cleaned through `deployed_files` instead.
+- APM's only hook-shape validation is `_validate_copilot_payload` (Copilot only) plus the parse checks above. Nothing validates handler fields, `type`, timeout type or range, matcher syntax, or event-name existence. Casing mismatches only warn.
+- `apm audit --ci` covers deployed-file presence, drift and hidden Unicode for hook outputs. It does not check hook semantics.
+
+## Authoring checklist
+
+Must (an author skill enforces these; an audit skill checks them):
+1. Hook files live at `.apm/hooks/<name>.json` (not a subdir, not a symlink) and parse as a JSON object. *Source: `find_hook_files`; invalid JSON is silently skipped by `_parse_hook_json`.*
+2. Use the wrapped shape `{"hooks": {Event: [...]}}`. In the naked shape, every top-level value must be a list, and no stray scalar keys are allowed anywhere. *Source: `_parse_hook_json`; the Copilot junk-file behaviour above.*
+3. Every event value is a list of objects, and every nested `hooks` is a list of objects. Otherwise the Copilot install fails. *Source: `_validate_copilot_payload`.*
+4. Event names use PascalCase for Claude (`PreToolUse`, `UserPromptSubmit`, `SessionStart`, `Stop`, …). Never use all-lowercase names, and never use camelCase for events outside the Claude map. *Source: `_HOOK_EVENT_MAP["claude"]`, `_detect_event_casing`.*
+5. Script references use `${CLAUDE_PLUGIN_ROOT}/…` / `${PLUGIN_ROOT}/…` (package-root relative) or `./…` (hook-dir relative), and the referenced file exists inside the package. No absolute paths, and no `$` or backtick in the script path. *Source: `_rewrite_command_for_target`, `_project_scoped_command_path`.*
+6. Avoid a stem matching `hooks-<target>` or `*-<target>-hooks` unless you intend deprecated routing. Use `target:` in the package `apm.yml` instead. *Source: `hook_file_routing`.*
+
+Should:
+7. Every handler sets `"type": "command"` and an explicit `timeout` in seconds. APM passes `type` through but never supplies it. *Source: `_handler_to_ir`, `_handler_from_ir`.*
+8. Set `matcher` explicitly on tool events (`PreToolUse`/`PostToolUse`) and on `SessionStart` (`startup` / `resume` / …). If you omit it, Claude receives `"*"`. *Source: `_to_claude_hook_entries` `default_matcher="*"`.*
+9. For a Claude-targeted package, do not author `bash`/`powershell`/`timeoutSec`. They render but leave stray keys. For Copilot-correct output, author the flat Copilot shape in a Copilot-targeted file. *Source: live render; `_handler_to_ir`.*
+10. Quote script paths that may contain spaces. *Source: published hooks guide; quote detection in `_rewrite_command_for_target`.*
+11. Hook scripts must be executable and self-contained within the hook directory bundle. For Copilot, do not ship `.json` helper files in the bundle, because Copilot's loader rejects JSON without a `hooks` key. *Source: published hooks guide; `copy_deployed_hook_bundle(exclude_json_files=True)`.*
+
+Audit-only (apm does not check these): unknown or misspelled event names; missing `type`; non-numeric timeout; matcher on non-tool events; extra handler keys that the target ignores.

plugins/kyberforge/docs/research/docs/microsoft-apm/instructions-primitive-schema.md

@@ -1,66 +1,120 @@
 ---
 topic: instructions-primitive-schema
 source_keys:
-  - context7-microsoft-apm
+  - apm-cli-installed-source
+  - apm-docs-llms-full
   - apm-github-repo
+  - context7-microsoft-apm
 ---
 
-## File location, naming, and frontmatter
+This file is checked against the installed apm-cli **0.28.0** source (`primitives/models.py`, `primitives/parser.py`, `primitives/discovery.py`, `utils/patterns.py`, `integration/instruction_integrator.py`, `integration/base_integrator.py`, `integration/targets.py`, `compilation/agents_compiler.py`, `commands/compile/cli.py`) and against a live `apm install` / `apm compile` of a scratch package (2026-09-28).
 
-`.apm/instructions/*.instructions.md`. Confirmed as the genuine required extension (not assumed) via APM's own discovery glob in `apm_cli/primitives/discovery.py`: `**/.apm/instructions/*.instructions.md` (and the `.github/instructions/` mirror, plus a bare `**/*.instructions.md` fallback).
+## File location, naming, discovery
 
-Unlike prompts and hooks, instructions **do** have a small, concretely modeled dataclass — `apm_cli.primitives.models.Instruction` — because instructions feed APM's own compile pipeline (they get folded into root context files), not just pass-through deployment:
+APM finds instruction files in two different ways, depending on the command.
 
-```python
-@dataclass
-class Instruction:
-    name: str
-    file_path: Path
-    description: str
-    apply_to: str        # from frontmatter key "applyTo"; empty means global/unconditional
-    content: str
-    author: str | None = None
-    version: str | None = None
-    source: str | None = None
+- **`apm install`** uses `InstructionIntegrator.find_instruction_files()`, which calls `find_files_by_glob(pkg, "*.instructions.md", subdirs=[".apm/instructions"])`. It searches the **package root and `.apm/instructions/`**. The search is non-recursive, so files in subdirectories of `.apm/instructions/` are never deployed. Symlinks and hardlinks (link count > 1) are rejected.
+- **`apm compile`** uses `discover_primitives()`, which has broader globs (`primitives/discovery.py`): `**/.apm/instructions/*.instructions.md`, `**/.github/instructions/*.instructions.md`, and a bare `**/*.instructions.md`. Dependencies are searched under `instructions/*.instructions.md` in both `.apm/` and `.github/`. In a live compile, the deployed `.github/instructions/` copies were not double-counted: 4 sources gave "Validated 4 primitives". The exact dedupe mechanism was not traced.
+- The deployed stem is the filename minus `.instructions.md` (`_extract_primitive_name`; rename loop in `integrate_instructions_for_target`).
+
+## Frontmatter and the `Instruction` model
+
+`primitives/parser._parse_instruction` builds `Instruction` with these fields:
+
+| Field | Source | Notes |
+|---|---|---|
+| `description` | `description:` | Defaults to `""` |
+| `apply_to` | `applyTo:` | Normalised by `normalize_apply_to` |
+| `author` | `author:` | Optional |
+| `version` | `version:` | Optional |
+| `content` | the body | |
+
+Any other frontmatter key is ignored by the model. On Copilot, such keys still survive the verbatim copy.
+
+**`applyTo` grammar** (`utils/patterns.py`):
+- **Scalar string.** Either a single glob or a comma-separated list. `parse_apply_to` splits only on **top-level** commas, so brace groups stay intact: `"**/*.py, **/*.{pyi,pyx}"` gives `["**/*.py", "**/*.{pyi,pyx}"]`. Each segment is stripped of whitespace. Empty segments are dropped, so leading, trailing and doubled commas are tolerated.
+- **YAML sequence.** `normalize_apply_to` joins non-null, non-empty entries with `,`. A literal top-level comma inside an entry is escaped as `\,`, so `"a,b/**"` survives as a single glob. You can also write `\,` by hand in a scalar value.
+- Missing, `null`, an empty string or an empty list all produce `""`, which means **unconditional**.
+- A non-string scalar (for example a number) is passed through `str()`. There is no glob syntax validation anywhere.
+
+**`Instruction.validate()` messages (exact text).** All three are appended to one list:
+- `"Missing 'description' in frontmatter"`
+- `"No 'applyTo' pattern specified -- instruction will apply globally"`
+- `"Empty content"` (a whitespace-only body counts as empty)
+
+**Correction to the earlier version of this doc:** none of these is a hard error. `AgentsCompiler.validate_primitives()` turns every message into a **warning** (`self.warnings.append(f"{file_path}: {error}")`) and always returns `[]`. Consequences, all verified live:
+- `apm compile` prints the warnings, still compiles, and exits 0.
+- **`apm compile --validate` can never fail on primitive errors.** `_run_validation_mode` only exits 1 when `validate_primitives` returns errors, which never happens. It printed "All primitives validated successfully!" for a file with no `description` and an empty body. The published docs describe `--validate` as a "frontmatter + structure check", which overstates it.
+- `apm install` never calls `validate()`. An instruction with no description and an empty body deployed silently to both targets.
+- `validate_primitives` also emits broken-markdown-link warnings (`validate_link_targets`) during compile.
+
+## Per-target mapping (`apm install`)
+
+**Copilot: verbatim.** `PrimitiveMapping("instructions", ".instructions.md", "github_instructions")`, where `copy_instruction` does link resolution plus LF normalisation. In a live run, `diff` against the source was empty. Frontmatter is kept byte-for-byte, including a YAML-list `applyTo`. The published docs say Copilot splits comma-lists natively. **Unverified:** whether Copilot honours a YAML-list `applyTo`. Prefer the scalar comma form for Copilot.
+
+**Copilot user scope** (`~/.copilot/`) uses `user_primitive_overrides` → `copilot_user_instructions`, handled by `_integrate_copilot_user_instructions`:
+- Every instruction's body is **frontmatter-stripped**, so `applyTo` scoping is lost.
+- The bodies are concatenated into `~/.copilot/copilot-instructions.md`, inside `<!-- apm:source:<pkg> -->` sections under an APM header.
+- A pre-existing user-authored file without the header is a collision. APM skips it with a warning unless you pass `--force`.
+
+**Claude: `.claude/rules/<stem>.md` via `_convert_to_claude_rules`.** Mapping: `PrimitiveMapping("rules", ".md", "claude_rules", output_compare=True)`.
+- `applyTo` becomes a `paths:` list, with each glob run through `yaml_double_quote`.
+- `description` and all other keys are **dropped**.
+- With no `applyTo`, the output has no frontmatter and the body is left-stripped.
+- An escaped-comma glob comes out unescaped (`a\,b/**` → `"a,b/**"`).
+
+Live output:
+
+```markdown
+---
+paths:
+  - "**/*.py"
+  - "**/*.{pyi,pyx}"
+---
+
+Use type hints.
 ```
 
-Frontmatter fields: `description` (required by convention — its absence is a validation error) and `applyTo` (a glob or comma-separated glob list, or a YAML sequence — APM normalizes all three input shapes into one canonical comma-separated form internally via `normalize_apply_to`/`parse_apply_to`). No `applyTo` means the rule is treated as **unconditional** — folded into root context files as always-on guidance rather than scoped to specific paths.
-
-`Instruction.validate()` produces these built-in errors/warnings:
-- Missing `description` → error: `"Missing 'description' in frontmatter"`.
-- Missing `applyTo` → warning-level: `"No 'applyTo' pattern specified -- instruction will apply globally"` (not fatal — it's accepted, just broad).
-- Empty body → error: `"Empty content"`.
-
-## Compile-time mapping: two entirely different mechanisms per target
-
-This is the biggest divergence from the agent/skill/prompt primitives, and the one most likely to surprise: **Claude Code does not get a verbatim copy of the `.instructions.md` file at all.**
-
-**Copilot CLI — verbatim, native primitive.** `PrimitiveMapping("instructions", ".instructions.md", "github_instructions")` on the `copilot` target has no `output_compare` flag, so `InstructionIntegrator` copies content through unchanged, preserving the original `applyTo:` frontmatter byte-for-byte (per the integrator's own docstring: "Copilot: `.github/instructions/` (verbatim, preserving applyTo:)"). This is deployed by `apm install`, not `apm compile`.
-
-At **Copilot user scope only** (`~/.copilot/`), individual files are not deployed — Copilot CLI at user scope reads a single `copilot-instructions.md`, so APM concatenates all instructions into that one file instead (`user_primitive_overrides: {"instructions": PrimitiveMapping("", ".md", "copilot_user_instructions")}`). Project-scope behavior (per-file, `.github/instructions/`) is unaffected.
-
-**Claude Code — real reconstruction into `.claude/rules/`, with field-dropping.** `PrimitiveMapping("rules", ".md", "claude_rules", output_compare=True)` marks this as one of APM's four "rule formats" (`RULE_FORMATS = {cursor_rules, claude_rules, windsurf_rules, kiro_steering}`) that transform their source rather than copy it. `InstructionIntegrator._convert_to_claude_rules()`:
-
-- Parses the source frontmatter and pulls only `applyTo` — **`description` is dropped entirely**, not carried into the output in any form.
-- Converts `applyTo` into a `paths:` YAML list (one `parse_apply_to()`-split glob per line), e.g. `applyTo: "**/*.py"` → `paths:\n  - "**/*.py"`.
-- If there was no `applyTo` (unconditional instruction), the output has **no frontmatter at all** — just the raw body, matching Claude's convention that files without `paths:` in `.claude/rules/` apply unconditionally.
-- Filename is renamed: `<x>.instructions.md` → `<x>.md` (the primitive's `extension` field, `.md`, replaces the source suffix — this is the general rule for every `output_compare=True` "rule format").
-
-This is architecturally the same category of lossy, real transformation the prior agent-primitive research found for Codex/Kiro agents — except here it's the default behavior for Claude specifically (not an opt-out edge case), and it applies even though Claude and Copilot are both first-class, actively-supported targets.
-
-## Compile-time file placement
+- **Ownership.** Rule-dir files are APM-owned per file. An existing file at the target path is compared against the *transformed* output: it is adopted if identical and rewritten otherwise. `managed_files` is not consulted (apm#1662), so a hand-written `.claude/rules/<same-stem>.md` is overwritten.
+- **Claude user scope.** `~/.claude/rules/`, or `$CLAUDE_CONFIG_DIR/rules/` if that variable is set. All Claude primitives are supported at user scope.
+- **`auto_create=False` for Claude.** `integrate_instructions_for_target` returns early when `<project>/.claude/` is not a directory. In a live run with `targets: [claude, copilot]` declared and no `.claude/`, the directory was created and the rules were deployed anyway. Which step creates it was not traced; the command integrator is a likely candidate.
 
 | Target | Output path | Transform |
 |---|---|---|
-| Copilot CLI (project scope) | `.github/instructions/<name>.instructions.md` | Verbatim byte copy, `applyTo:` preserved as-is |
-| Copilot CLI (user scope, `~/.copilot/`) | `~/.copilot/copilot-instructions.md` | Concatenated — all instructions merged into one file, because Copilot CLI at user scope reads only that single file |
-| Claude Code | `.claude/rules/<name>.md` | Reconstructed: `applyTo` → `paths:` YAML list; `description` dropped; no frontmatter at all if unconditional |
+| Copilot (project) | `.github/instructions/<stem>.instructions.md` | Verbatim |
+| Copilot (user) | `~/.copilot/copilot-instructions.md` | Bodies concatenated; frontmatter stripped |
+| Claude (project/user) | `.claude/rules/<stem>.md` | `applyTo` → `paths:`; everything else dropped; no frontmatter if unconditional |
 
-Additionally, **`apm compile`** (distinct from `apm install`) can also fold instruction content directly into root context files — `AGENTS.md` (single-file or per-directory "distributed" mode) and the Claude-specific parallel format `CLAUDE.md`/per-directory `CLAUDE.md` — grouped by directory using `applyTo` pattern analysis (`context_optimizer.optimize_instruction_placement`). To avoid duplicating content between the native `.claude/rules/`+`.github/instructions/` deployment (from `apm install`) and this root-context fold-in (from `apm compile`), a `skip_instructions` config flag (and `compilation.placement.min_instructions_per_file` in `apm.yml`) actively suppresses the redundant copy in AGENTS.md/CLAUDE.md once native per-target files exist — `apm compile --target claude --force-instructions` overrides this dedup when an author explicitly wants both.
+Other rule formats (`RULE_FORMATS`) work the same way: `cursor_rules` produces `.mdc` with `globs:` and derives `description` from the body when it is missing, `windsurf_rules`, `kiro_steering`, and `antigravity_rules`.
 
-## Validation constraints and gotchas
+## `apm compile`: fold-in to AGENTS.md / CLAUDE.md
 
-- **The `description` field is real for Copilot but silently discarded for Claude.** An author who relies on `description` to explain *why* a rule exists (common practice, since Copilot's `.instructions.md` UI can surface it) gets that context deleted on every Claude compile — there's no config to keep it as a comment or otherwise.
-- **No content-level validation for the `paths:` conversion** — if `applyTo` contains a pattern `parse_apply_to` can't split sensibly, the resulting `paths:` list is whatever falls out; no dedicated schema check catches a malformed glob before deploy.
-- **Directory-distribution logic for AGENTS.md/CLAUDE.md is heuristic, not declarative** — `context_optimizer.optimize_instruction_placement` picks placement directories from `applyTo` patterns algorithmically; `compilation.placement.min_instructions_per_file` in `apm.yml` (default effectively 1) is the only tuning knob, and setting it above 1 causes under-populated directories to have their instructions bubbled up to the parent directory rather than dropped.
-- **Same "no dedicated primitive validation function" gap noted for agents** — `Instruction.validate()` in `primitives/models.py` is the only validation, and it is invoked as part of the generic primitive-discovery/compile pipeline, not as a standalone `apm audit` check comparable to what exists for `apm.yml` itself.
+`compilation/distributed_compiler.py` and `context_optimizer.optimize_instruction_placement` group instruction bodies into `AGENTS.md` and `CLAUDE.md` files, placed per directory according to the `applyTo` patterns.
+
+- **Dedup.** Instructions are omitted from `CLAUDE.md` when `.claude/rules/` is populated, and from `AGENTS.md` when `.github/instructions/` is populated. `--force-instructions` (alias `--no-dedup`) overrides this. In a live `apm compile -t claude,copilot` after install, no `CLAUDE.md` was produced. With `-t claude --force-instructions`, `CLAUDE.md` contained a "Global Instructions" section and one `### Files matching \`<applyTo>\`` section per pattern.
+- **Headings show the normalised `applyTo` string verbatim**, including `\,` escapes (for example ``Files matching `src/**,a\,b/**` ``).
+- `compilation.placement.min_instructions_per_file` in `apm.yml` controls when under-populated directories bubble their instructions up to the parent.
+
+## Gotchas
+
+- **`description` never reaches Claude.** It is kept for Copilot and is used as the index text in Cursor rules and compiled context. Keep the rationale for a rule in the body if Claude readers need it.
+- **Copilot user scope loses `applyTo`.** Every instruction becomes global there.
+- **A glob is never validated.** A typo gives a rule that silently never binds.
+- `apm audit` checks deployed rules for hidden Unicode and drift. It does not validate frontmatter.
+
+## Authoring checklist
+
+**Must** (an author skill enforces these; an audit skill checks them):
+1. The path is `.apm/instructions/<stem>.instructions.md`, directly in that directory with no subdirectories, and is not a symlink. *Source: `find_instruction_files`, `find_files_by_glob`.*
+2. `description` is a non-empty string. *Source: `Instruction.validate()`; apm only warns during `apm compile`.*
+3. The body is non-empty after trimming whitespace. *Source: `Instruction.validate()`; install deploys empty rules silently.*
+4. `applyTo` is either absent (intentionally global) or a non-empty glob / comma-list. Use top-level commas only as separators, and put alternation inside `{}`. *Source: `parse_apply_to`, `has_top_level_comma`.*
+5. The stem is unique across the package and its dependencies, because a `.claude/rules/<stem>.md` collision is overwritten. *Source: `integrate_instructions_for_target` rule-dir ownership.*
+
+**Should:**
+6. Use the scalar string form of `applyTo` rather than a YAML list, because Copilot receives the source verbatim. *Source: `copy_instruction`. Copilot's handling of list values is unverified.*
+7. Omitting `applyTo` should be a deliberate choice. Without it, the file is always-on in Claude rules and is folded into `AGENTS.md`/`CLAUDE.md` global sections. *Source: `_convert_to_claude_rules`; `Instruction.validate()` warning text.*
+8. Keep frontmatter to `description` and `applyTo`, plus the optional `author` and `version`. No target consumes other keys, and Claude drops them. *Source: `_parse_instruction`, `_convert_to_claude_rules`.*
+9. Keep relative markdown links resolvable from the source file. *Source: `validate_link_targets`, `resolve_links`.*
+
+**Audit-only** (apm does not check these): glob syntax validity; globs that match nothing in the repo; duplicate stems; description quality; YAML-list `applyTo` on Copilot-targeted packages. `apm compile --validate` cannot be relied on as a gate.

plugins/kyberforge/docs/research/docs/microsoft-apm/prompt-primitive-schema.md

@@ -1,53 +1,123 @@
 ---
 topic: prompt-primitive-schema
 source_keys:
-  - context7-microsoft-apm
+  - apm-cli-installed-source
+  - apm-docs-llms-full
   - apm-github-repo
+  - context7-microsoft-apm
 ---
 
-## File location, naming, and frontmatter
+Checked against the installed apm-cli **0.28.0** source (`integration/prompt_integrator.py`, `integration/command_integrator.py`, `integration/base_integrator.py`, `integration/targets.py`, `security/gate.py`) and a live `apm install` of a scratch package targeting `claude` and `copilot` (2026-09-28).
 
-`.apm/prompts/*.prompt.md` (also discovered at the package root). Filename minus the `.prompt.md` suffix becomes the prompt's identity — used verbatim as the Copilot filename and, after transformation, as the Claude command name. No required-extension ambiguity: it is genuinely `.prompt.md`, confirmed both in docs and in APM's own `PromptIntegrator.find_prompt_files` (`*.prompt.md`) and `CommandIntegrator.find_prompt_files` (same glob).
+## File location, naming, discovery
 
-There is no single closed frontmatter schema — APM's P1 "no invented primitive frontmatter" principle applies here too, so a prompt author writes whatever keys their primary target needs and APM passes or drops per-target. Keys seen in APM's own docs/examples:
+- `PromptIntegrator.find_prompt_files()` and `CommandIntegrator.find_prompt_files()` both run `find_files_by_glob(pkg, "*.prompt.md", subdirs=[".apm/prompts"])`.
+  - The search covers the package root and `.apm/prompts/`, and is non-recursive.
+  - Symlinks and hardlinks are rejected.
+  - `.apm/prompts/` is canonical. Root files are discovered for backward compatibility (published docs).
+- Identity comes from the filename minus `.prompt.md`. That name is the Copilot filename unchanged, and the Claude `/command` name.
+  - `integrate_commands_for_target` runs `validate_path_segments(base_name, context="command filename")` against traversal names.
+  - A duplicate name in the root and in `.apm/prompts/` collides. The published docs say "later writer wins on copilot and the transform fails on Claude/Cursor". This was not verified here.
+- Prompts are **not** in `discover_primitives()` and have no model class. `apm compile` and `apm compile --validate` never look at them.
+- Prompts are deployed only by `apm install`.
+- There is no `.apm/commands/` primitive. A Claude command is the compiled form of a prompt.
 
-| Field | Purpose |
+## Frontmatter
+
+There is no closed schema. What survives is decided per target.
+
+**`_PRESERVED_COMMAND_KEYS` (exact, 0.28.0):**
+- `description`
+- `allowed-tools`
+- `allowedTools`
+- `model`
+- `argument-hint`
+- `argumentHint`
+- `input`
+
+The user-facing list (`_PRESERVED_COMMAND_KEYS_DISPLAY`) omits the camelCase aliases.
+
+**`input:` shapes accepted by `_extract_input_names`:**
+
+| Shape | Names extracted |
 |---|---|
-| `description` | Shown in Copilot's prompt picker / used for discovery |
-| `input` | List of parameter names (simple list, or list of `{name: description}` objects) referenced in body as `${input:name}` |
-| `allowed-tools` (or `allowedTools`) | Tool allowlist for the prompt's execution |
-| `argument-hint` (or `argumentHint`) | Human-readable hint for expected arguments |
-| `model` | Model override when the prompt runs |
-| `author`, `mcp`, `parameters` | Cursor/other-target-specific metadata — **not preserved** by the shared Claude/Cursor command transformer (see below) |
+| `input: [file, focus]` (list of strings) | each string |
+| `input:` list of one-key maps (`- file: "desc"`) | each map's **keys** |
+| `input: file` (single string) | that string |
+| `input: {file: desc, focus: desc}` (map) | its keys |
 
-**Workflow-prompt-only keys** (Copilot App / Copilot Workflows, not Copilot CLI): `name`, `interval` (`manual`/`hourly`/`daily`/`weekly`), `schedule_hour` (0–23 UTC), `schedule_day` (0–6, weekly only), `mode` (`interactive`/`plan`), `reasoning_effort`. These are flat top-level keys on the same `.prompt.md` file, consumed only by the Copilot App scheduler integration — irrelevant to Claude Code / Copilot CLI compilation and should not be treated as universal prompt schema.
+- Names must match `_INPUT_NAME_RE = ^[A-Za-z][\w-]{0,63}$`.
+- Invalid names and non-string entries are rejected, with the warning `input: rejected N invalid name(s) (must match [A-Za-z][\w-]{0,63}): <first 5>`.
+- Whitespace-only entries are dropped silently.
+- **Upstream docs bug.** The published "Commands" example writes `- name: pr_number` / `description: …` inside a single map. `_extract_input_names` reads the map's *keys*, so the arguments come out as `name` and `description` rather than `pr_number`. This was verified live: `arguments: [name, description]`, `argument-hint: <name> <description>`. Use `- pr_number: "desc"` instead.
 
-## Compile-time mapping: verbatim for Copilot, real reconstruction for Claude
+**Other keys seen in docs:**
+- Copilot-only picker metadata: `name`, `agent`, `mode`, `tools`.
+- Cursor and other targets: `author`, `mcp`, `parameters`.
+- Copilot App workflow keys: `interval`, `schedule_hour`, `schedule_day`, `reasoning_effort`, per the published docs. The source has a `copilot_app_workflow_integrator` module, but it was not traced here.
 
-**Copilot CLI target — verbatim copy.** `PrimitiveMapping("prompts", ".prompt.md", "github_prompt")` on the `copilot` target profile carries no `output_compare` flag, and `PromptIntegrator.copy_prompt()` reads the source file and writes it out unchanged (only markdown link targets get rewritten) via `copy_prompt: "Copy prompt file verbatim with link resolution."`. Every frontmatter key — including `author`, `mcp`, `parameters` — survives. Filename is untouched (`get_target_filename` returns `source_file.name`, "no -apm suffix").
+None of these other keys survive the Claude transform.
 
-**Claude Code target — real reconstruction into a slash command, with field-dropping.** There is no `prompts:` key at all in Claude's `TargetProfile.primitives` dict; instead prompts route through the shared `CommandIntegrator`, which transforms `.prompt.md` → Claude custom slash command markdown. `CommandIntegrator._transform_prompt_to_command()`:
+## Per-target mapping
 
-- Strips the `.prompt.md` suffix from the filename to derive `command_name`.
-- Builds an entirely new frontmatter object containing **only** these preserved keys: `description`, `allowed-tools` (accepts `allowedTools` alias), `model`, `argument-hint` (accepts `argumentHint` alias).
-- Maps APM's `input:` list to Claude's `arguments:` list, and synthesizes `argument-hint` from it if not already set.
-- Rewrites body placeholders `${input:name}` / `${{input:name}}` to Claude's native `$name` syntax via regex substitution.
-- Computes `dropped_keys = source_frontmatter_keys - preserved_keys` and surfaces it as an install-time diagnostic warning — so `author`, `mcp`, `parameters`, and any other non-listed key are silently dropped from the compiled output but *not* silently dropped from the user's awareness (a warning fires).
-- Cursor reuses this exact same transformer (`claude_command` format_id) — same preserved-key set, same drops.
+**Copilot, verbatim.** Mapping: `PrimitiveMapping("prompts", ".prompt.md", "github_prompt")`. `PromptIntegrator.copy_prompt` resolves links and normalises line endings to LF. In the live run a `diff` against the source was empty, and every key survived, including dropped-for-Claude keys. `${input:x}` stays as written. At user scope the prompt goes to `~/.copilot/prompts/`.
 
-## Compile-time file placement
+**Claude, reconstructed.** Mapping: `PrimitiveMapping("commands", ".md", "claude_command")`, which goes through `CommandIntegrator._transform_prompt_to_command`. The transform:
+- Builds new frontmatter from `description`, `allowed-tools` (the `allowedTools` alias is accepted), `model`, and `argument-hint` (the `argumentHint` alias is accepted).
+- Adds `arguments: [names]` from `input`. When there is no explicit `argument-hint`, it synthesises `argument-hint: "<a> <b>"`.
+- Emits keys in alphabetical order, because `frontmatter.dumps` sorts them.
+- Rewrites the body with the regex `\$\{\{?\s*input\s*:\s*([\w-]+)\s*\}?\}` → `$name`. This runs **only when at least one valid input name exists**, and then it rewrites **every** `${input:…}`, including names not declared in `input:`. Live: `${input:undeclared}` became `$undeclared`, while a prompt with no `input:` kept `${input:x}` literally.
+- Reports dropped keys, `sorted(source_keys - _PRESERVED_COMMAND_KEYS)`, as the exact warning `Claude command <name>: frontmatter keys not supported for claude commands and were dropped: <keys>. Supported keys: allowed-tools, argument-hint, description, input, model.`
+- Emits the info message `Mapped input -> command arguments in <file>: [...]`.
+- Scans the compiled text with `SecurityGate.scan_text(BLOCK_POLICY)`. A critical hidden-character finding skips the write.
+- Deploys at user scope to `~/.claude/commands/`, or to `$CLAUDE_CONFIG_DIR/commands/` if that variable is set.
+
+Cursor, OpenCode and Grok Build reuse the same `claude_command` transformer. Gemini writes TOML. Windsurf writes workflows. Codex gets nothing.
+
+Live output of `review.prompt.md`:
+
+```markdown
+---
+allowed-tools:
+- Read
+- Grep
+argument-hint: <file> <focus>
+arguments:
+- file
+- focus
+description: Review a file
+model: sonnet
+---
+
+Review $file focusing on $focus and $undeclared.
+```
 
 | Target | Output path | Transform |
 |---|---|---|
-| Copilot CLI | `.github/prompts/<name>.prompt.md` | Verbatim byte copy (links resolved) |
-| Claude Code | `.claude/commands/<name>.md` | Reconstructed: only `description`/`allowed-tools`/`model`/`argument-hint`/`arguments` survive; `input:` → `arguments:`; `${input:x}` → `$x` |
-
-Invocation surface differs correspondingly: Copilot exposes it via the prompts picker UI (select by name); Claude exposes it as `/<name> <args>` (same pattern Cursor, OpenCode, Gemini CLI, and Windsurf's workflows menu use for their own compiled copies).
+| Copilot | `.github/prompts/<name>.prompt.md` | Verbatim (links resolved) |
+| Claude | `.claude/commands/<name>.md` | Preserved-key subset; `input` becomes `arguments`; `${input:x}` becomes `$x` |
 
 ## Validation constraints and gotchas
 
-- **Input-name validation is real, not just documentation.** `_extract_input_names()` enforces `[A-Za-z][\w-]{0,63}` on every name pulled from `input:`; anything that fails is dropped from `arguments:` and reported as a warning listing up to 5 rejected names (`input: rejected N invalid name(s) ... `). A malformed `input:` entry does not fail the install — it silently loses that one argument.
-- **Filename-derived identity is security-checked.** `integrate_commands_for_target` calls `validate_path_segments(base_name, context="command filename")` specifically to reject a package shipping a `.prompt.md` file with a manipulated relative name (e.g. `../../evil.prompt.md`) that would otherwise escape the target commands directory.
-- **The dropped-key warning is the only signal a Claude-only author gets** that Cursor-specific frontmatter (`author`, `mcp`, `parameters`) never reached the deployed file — there is no error, no hard failure, and no config flag to preserve those keys for Claude; the shared transformer's preserved-key list is fixed in code (`_PRESERVED_COMMAND_KEYS`), not configurable per package.
-- **No dedicated `Prompt`/`PromptPrimitive` validation class exists** in `apm_cli/models/validation.py` or `apm_cli/primitives/models.py` — same gap pattern documented for the agent primitive. `apm.yml`'s `type: prompts` package-content-type ("Commands/prompts only, no instructions or skills") is validated at the package-type-detection level, not the individual-prompt level.
-- Slash commands and prompts share one source directory and one glob (`.apm/prompts/*.prompt.md`) — there is no separate `.apm/commands/` primitive; "command" is purely a per-target compiled *name* for the same source file, not a distinct authoring primitive.
+- APM never validates `description`: the transform only copies it if present. Deploying a prompt with no frontmatter at all was not tested.
+- `$ARGUMENTS` and other native Claude syntax pass through untouched. They appear literally in the Copilot copy.
+- A prompt that relies on Copilot-only keys (`agent`, `tools`, `mode`) loses them on Claude. The only signal is the install-time warning.
+- A pre-install hidden-Unicode scan (`install/helpers/security_scan`, `BLOCK_POLICY`) runs on source files. `apm compile` does not re-scan, so run `apm audit` before publishing (published docs).
+- `apm run <script> --param k=v` compiles a prompt with parameters bound. See `cli-reference.md`.
+
+## Authoring checklist
+
+**Must** (an author skill enforces these; an audit skill checks them):
+1. The path is `.apm/prompts/<name>.prompt.md`, directly in that directory and not a symlink. `<name>` is unique across `.apm/prompts/` and the package root, and is a safe path segment. *Source: `find_prompt_files`, `validate_path_segments`.*
+2. `description` is present and non-empty. It is the picker and command description on both targets, and apm does not check it. *Source: `_transform_prompt_to_command`.*
+3. Every `input:` name matches `^[A-Za-z][\w-]{0,63}$`. The object form is `- <name>: "<desc>"`, never `- name: <name>`. *Source: `_INPUT_NAME_RE`, `_extract_input_names`.*
+4. Every `${input:x}` in the body refers to a name declared in `input:`, and every declared name is used. If `input:` is empty or absent, no `${input:…}` may appear, because it would reach Claude unrewritten. *Source: the rewrite regex and its condition.*
+5. Frontmatter keys are limited to the preserved set (`description`, `allowed-tools`, `model`, `argument-hint`, `input`) unless a Copilot-only key is intended and its Claude drop is accepted. *Source: `_PRESERVED_COMMAND_KEYS`.*
+
+**Should:**
+6. Use the kebab-case spellings `allowed-tools` and `argument-hint`, not the camelCase aliases. *Source: `_PRESERVED_COMMAND_KEYS_DISPLAY`.*
+7. Omit `argument-hint` when `input:` is set, unless the synthesised `<a> <b>` form is inadequate. *Source: `_transform_prompt_to_command`.*
+8. Give `model` a slug the target accepts. Copilot ignores `allowed-tools` and `model` (published docs).
+9. Keep one intent per prompt, and write the body as second-person instructions (published "Author a prompt" guide).
+
+**Audit-only** (apm does not check these): missing `description`; undeclared or unused inputs; `${input:…}` without `input:`; Copilot-only keys in a Claude-targeted package; name collisions between the root and `.apm/prompts/`.

plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md

@@ -14,4 +14,20 @@
 - **Contributing files:** agent-primitive-schema.md, prompt-primitive-schema.md, instructions-primitive-schema.md, hooks-primitive-schema.md, releasing.md
 - **Status:** `extracted`
 
+## apm-cli-installed-source
+
+- **URL:** file:///root/.local/pipx/venvs/apm-cli/lib/python3.11/site-packages/apm_cli/
+- **Description:** Installed apm-cli 0.28.0 package source, which is the version this repo runs. Read as ground truth for the hooks, instructions and prompts docs, including `integration/hook_integrator.py`, `hook_native_formats.py`, `hook_ir.py`, `hook_file_routing.py`, `instruction_integrator.py`, `command_integrator.py`, `prompt_integrator.py`, `targets.py`, `primitives/`, `utils/patterns.py`, `compilation/agents_compiler.py`, `commands/compile/cli.py` and `security/executables.py`. Cross-checked by live `apm install` / `apm compile` runs of a throwaway package (claude and copilot targets) in a scratch dir on 2026-09-28.
+- **Contributing files:** hooks-primitive-schema.md, instructions-primitive-schema.md, prompt-primitive-schema.md
+- **Status:** `extracted`
+
+## apm-docs-llms-full
+
+- **URL:** https://microsoft.github.io/apm/llms-full.txt
+- **Description:** The full published APM docs bundle. It tracks upstream main and may be newer than 0.28.0. Used the "Hooks and commands", "Instructions and agents" and "Author a prompt" guides for public-facing claims and to flag where the docs diverge from 0.28.0.
+- **Contributing files:** hooks-primitive-schema.md, instructions-primitive-schema.md, prompt-primitive-schema.md
+- **Status:** `extracted`
+
+Note (2026-09-28): during the verification pass for the hooks, instructions and prompts docs, the Context7 `/microsoft/apm` endpoint returned an invalid-API-key error. Those three files were re-verified against `apm-cli-installed-source` and `apm-docs-llms-full` only. Their `context7-microsoft-apm` key reflects the earlier pass.
+
 Note: `releasing.md`'s `--check-clean`/`--check-versions` scope, `apm pack` exit-code semantics, and the `.apm/`-vs-root-flat-dir mutual exclusivity referenced there were additionally cross-checked directly against `apm_cli/bundle/plugin_exporter.py`, `apm_cli/commands/pack.py`, and `apm_cli/marketplace/drift_check.py` in the installed `apm-cli` 0.28.0 package (`/root/.local/pipx/venvs/apm-cli/`), not just Context7 doc snippets — confirmed by a live `apm pack --format plugin` run inside `plugins/bin` that reproduced the documented `[!] Skipping root-level skills/ because .apm/ is present` warning.

plugins/lint/apm.yml

@@ -1,13 +1,13 @@
 name: lint
-version: 1.1.8
+version: 1.1.9
 description: Skills and agents for configuring and running linters.
 author:
   name: Defame1297
   email: defame1297@rkdr.net
-  url: https://git.dev.rkdr.net/Defame1297/
+  url: https://git.rkdr.net/Defame1297/
 license: MIT
-homepage: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/lint
-repository: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/lint
+homepage: https://git.rkdr.net/Defame1297/holocron/src/branch/main/plugins/lint
+repository: https://git.rkdr.net/Defame1297/holocron/src/branch/main/plugins/lint
 keywords:
 - lint
 - style

plugins/onedev/apm.yml

@@ -1,13 +1,13 @@
 name: onedev
-version: 0.1.0
+version: 0.1.1
 description: Skills and agents for working with a OneDev forge through the TOD CLI — the forge's own objects, as distinct from the local git clone.
 author:
   name: Defame1297
   email: defame1297@rkdr.net
-  url: https://git.dev.rkdr.net/Defame1297/
+  url: https://git.rkdr.net/Defame1297/
 license: MIT
-homepage: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/onedev
-repository: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/onedev
+homepage: https://git.rkdr.net/Defame1297/holocron/src/branch/main/plugins/onedev
+repository: https://git.rkdr.net/Defame1297/holocron/src/branch/main/plugins/onedev
 keywords:
   - onedev
   - tod

scripts/skill-size-check.sh

@@ -444,30 +444,42 @@ for path in files:
                     "\"Not X -> %s. Not Y -> %s.\"" % (path, first, second, first, second))
 
     targets = boundary_targets(desc)
-    if targets:
+    # Body-level targets (issue #124): notation only (`/name`, `-> name`), so
+    # every hit is unconditionally blocking — see body_targets()'s header for
+    # why the description gate's SUGGESTION tier has no counterpart here.
+    body_route_names = body_targets(body)
+    if targets or body_route_names:
         known = known_targets(skill_dir)
         if known:
-            blocking, reported = unresolved_targets(desc, known)
-            for target in blocking:
-                error("%s: description routes to '%s', which does not resolve to a skill "
-                      "or agent in this monorepo, in this package, or in a package it "
-                      "declares in apm.yml dependencies.apm (ADR-0020). A boundary clause "
-                      "that names a non-existent target sends the router nowhere."
-                      % (path, target))
-            for target in reported:
-                suggest("%s: description routes to '%s', which does not resolve to a skill "
-                        "or agent in this monorepo, in this package, or in a package it "
-                        "declares in apm.yml dependencies.apm (ADR-0020). SUGGESTION rather "
-                        "than a hard failure because nothing else in the sentence resolves, "
-                        "so this is equally likely to be a tool, a file format or an English "
-                        "compound. If it IS a route, write it as `/%s` or `-> %s` and it will "
-                        "be checked properly." % (path, target, target, target))
+            if targets:
+                blocking, reported = unresolved_targets(desc, known)
+                for target in blocking:
+                    error("%s: description routes to '%s', which does not resolve to a skill "
+                          "or agent in this monorepo, in this package, or in a package it "
+                          "declares in apm.yml dependencies.apm (ADR-0020). A boundary clause "
+                          "that names a non-existent target sends the router nowhere."
+                          % (path, target))
+                for target in reported:
+                    suggest("%s: description routes to '%s', which does not resolve to a skill "
+                            "or agent in this monorepo, in this package, or in a package it "
+                            "declares in apm.yml dependencies.apm (ADR-0020). SUGGESTION rather "
+                            "than a hard failure because nothing else in the sentence resolves, "
+                            "so this is equally likely to be a tool, a file format or an English "
+                            "compound. If it IS a route, write it as `/%s` or `-> %s` and it will "
+                            "be checked properly." % (path, target, target, target))
+            for target in unresolved_body_targets(body, known):
+                error("%s: body routes to '%s' (`/%s` or `-> %s` notation), which does not "
+                      "resolve to a skill or agent in this monorepo, in this package, or in a "
+                      "package it declares in apm.yml dependencies.apm (ADR-0020). A dispatch "
+                      "table or \"run X\" step naming a non-existent target sends the agent "
+                      "nowhere." % (path, target, target, target))
         else:
+            unchecked = sorted(set(targets) | set(body_route_names))
             info("%s: boundary-target resolution DID NOT RUN — no skill universe "
                  "could be determined for this path (no authoring root above it, no "
                  "apm package root, no declared apm dependencies, no deployed "
                  ".claude/ or .agents/ tree). Unchecked target(s): %s"
-                 % (path, ", ".join(targets)))
+                 % (path, ", ".join(unchecked)))
 
 sys.exit(1 if failed else 0)
 SSC_CHECKS_PY

tests/run-bats.sh

@@ -46,6 +46,17 @@ fi
 # which is ADR-0024 consequence 2 arriving here. Keeping the exclusion now is
 # what stops that landing as a mystery double-run on the merge that enables it.
 #
+# build/ is excluded for the same reason again, one layer further out: `apm
+# pack` stages a full copy of a package's tree (including its skills' tests/
+# directories) under build/<package>-<version>/ before archiving it. Those
+# staged .bats files carry the same six-levels-up REPO_ROOT walk-up as any
+# other copy, which resolves past this repo's actual root and fails on a
+# missing bats-support helper -- the same failure mode apm_modules/ and
+# .claude/skills/ above already guard against, just from a different apm
+# subcommand. build/ is gitignored and regenerated on demand, so nothing here
+# depends on its contents; the exclusion only stops a stray local `apm pack`
+# output from being discovered and double-run.
+#
 # The walk runs from inside REPO_ROOT so the exclusions match paths RELATIVE to
 # it, the same universe the `git ls-files` grep below sees. Matched against
 # absolute paths, `*/.claude/worktrees/*` excluded every file whenever the
@@ -61,6 +72,7 @@ done < <(
         -not -path "*/.claude/worktrees/*" \
         -not -path "*/apm_modules/*" \
         -not -path "*/.claude/skills/*" \
+        -not -path "*/build/*" \
         | sort
 )
 
@@ -99,7 +111,7 @@ if [[ -n "$GIT_TOPLEVEL" && "$GIT_TOPLEVEL" == "$REPO_ROOT" ]]; then
         [[ -n "$f" ]] && EXPECTED_FILES+=("$REPO_ROOT/$f")
     done < <(
         git -C "$REPO_ROOT" ls-files -- '*.bats' \
-            | grep -Ev '(^|/)tests/bats/|(^|/)test_helper/|(^|/)\.claude/worktrees/|(^|/)apm_modules/|(^|/)\.claude/skills/' \
+            | grep -Ev '(^|/)tests/bats/|(^|/)test_helper/|(^|/)\.claude/worktrees/|(^|/)apm_modules/|(^|/)\.claude/skills/|(^|/)build/' \
             | sort || true
     )
 else

tests/test-adr0020-targets.sh

@@ -961,6 +961,117 @@ else
   fail "an attributive target naming a REAL skill produced output (exit $ATTR_RC): $ATTR_OUT"
 fi
 
+# ---------------------------------------------------------------------------
+# 3. Body-level routing targets (issue #124)
+# ---------------------------------------------------------------------------
+# boundary_targets()/unresolved_targets() are the DESCRIPTION gate, exercised
+# above. body_targets()/unresolved_body_targets() are the separate, narrower
+# extractor added for issue #124: a SKILL.md body is dispatch-table and
+# procedure prose, not a one-to-three-sentence routing clause, so the body
+# extractor takes only /name and -> `name` NOTATION (never the bare-prose
+# forms the description gate also reads), and even within notation, a target
+# must be hyphenated and must not be a `<tag` immediately before the `/`.
+# Every fixture is built inside a real plugin tree (BODY_ROOT), same as
+# section 2 above, so the resolver actually runs instead of declining.
+echo ""
+echo "--- body-level routing targets (issue #124) ---"
+BODY_ROOT="$TMPDIR_T/body"
+write_skill "$BODY_ROOT/plugins/p/.apm/skills/sibling-skill" sibling-skill \
+  "Use when doing the other thing. Do not use for anything else."
+
+# write_skill_body <skill-dir> <name> <body>
+write_skill_body() {
+  mkdir -p "$1"
+  {
+    echo "---"
+    echo "name: $2"
+    echo "description: Use when doing the thing. Do not use for anything else."
+    echo "metadata:"
+    echo "  version: \"1.0.0\""
+    echo "---"
+    echo ""
+    printf '%s\n' "$3"
+  } > "$1/SKILL.md"
+}
+
+# body_case <slug> <expect: silent|errors> <needle> <body>
+body_case() {
+  local slug="$1" mode="$2" needle="$3" body="$4" out status=0
+  write_skill_body "$BODY_ROOT/plugins/p/.apm/skills/$slug" "$slug" "$body"
+  set +e
+  out="$(bash "$HOOK" "$BODY_ROOT/plugins/p/.apm/skills/$slug/SKILL.md" 2>&1)"
+  status=$?
+  set -e
+  if [[ "$out" == *"DID NOT RUN"* ]]; then
+    fail "body \"$body\" — the resolver declined, so this case asserts nothing about extraction: $out"
+    return
+  fi
+  case "$mode" in
+    silent)
+      if [[ $status -eq 0 && -z "$out" ]]; then
+        pass "not a dangling body target: \"$body\""
+      else
+        fail "body \"$body\" (exit $status, output: ${out:-<empty>})"
+      fi
+      ;;
+    errors)
+      if [[ $status -ne 0 && "$out" == *"$needle"* ]]; then
+        pass "dangling body target caught: \"$body\""
+      else
+        fail "body \"$body\" should have ERRORed with $needle (exit $status, output: ${out:-<empty>})"
+      fi
+      ;;
+  esac
+}
+
+# The two live true positives the issue was filed over, at fixture scale:
+# a bare/backticked `/name` and a backticked `-> \`name\``.
+body_case body-slash-dangling errors "body routes to 'no-such-body-skill'" \
+  "Run \`/no-such-body-skill\` if the config is missing."
+body_case body-slash-resolves silent "" \
+  "Run \`/sibling-skill\` if the config is missing."
+body_case body-arrow-dangling errors "body routes to 'no-such-arrow-body'" \
+  "- User wants X -> \`no-such-arrow-body\`"
+body_case body-arrow-resolves silent "" \
+  "- User wants X -> \`sibling-skill\`"
+
+# No conjunction continuation: only the FIRST target after an arrow is ever
+# read, so a dangling SECOND name is silently uncounted rather than reported
+# — the same one-arrow-one-target convention issue #107 enforces on
+# descriptions (there, at SUGGESTION tier; here, by construction, since the
+# body gate has no SUGGESTION tier at all).
+body_case body-arrow-no-continuation silent "" \
+  "- User wants X -> \`sibling-skill\` or \`no-such-uncounted-target\`"
+
+# The single-word guard: a real corpus false positive removed by requiring a
+# hyphen. `` `/fork` `` (forge/SKILL.md) and `` `/name` `` (skill-author/SKILL.md)
+# are both single-word citations of a tool or a placeholder, not routes, and
+# both would otherwise have hard-FAILed with no escape hatch.
+body_case body-slash-single-word-guard silent "" \
+  "See \`/fork\` for how the two differ."
+
+# The closing-tag guard: an XML/HTML-style section delimiter used as a prompt
+# marker (grill-with-docs/SKILL.md's <what-to-do>...</what-to-do>) is
+# indistinguishable from /route notation by every other rule in the pattern —
+# a `<` immediately before the `/` is the one signal that tells them apart.
+body_case body-closing-tag-guard silent "" \
+  $'<what-to-do>\nDo the thing.\n</what-to-do>'
+
+# The bare-arrow guard: NOTATION_ARROW (bare hyphenated word after any arrow)
+# is deliberately NOT used here, only ARROW_MARKED (backticked or
+# slash-prefixed). caveman/SKILL.md's own process chain, "Inline obj prop ->
+# new ref -> re-render.", is real corpus prose this guard exists for — an
+# unbacked, unresolvable name after an arrow must stay silent, not become a
+# hard-blocking dangling-target FAIL with no suppression mechanism.
+body_case body-arrow-bare-not-notation silent "" \
+  "Reproduce -> minimise -> no-such-bare-chain-target."
+
+# Fenced code blocks are masked, same as gotcha_stats() and
+# missing_reference_pointers() mask them: an illustrative example is not a
+# live dispatch entry.
+body_case body-fenced-example silent "" \
+  $'```\nRun /no-such-fenced-skill instead.\n```'
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]

tests/test-apm-current-hook.sh

@@ -297,12 +297,14 @@ echo "--- hooks.json wiring ---"
 # ---------------------------------------------------------------------------
 
 # apm resolves script paths relative to the package root, and `apm pack` keeps
-# only *.json from .apm/hooks/ — so a ${CLAUDE_PLUGIN_ROOT}/hooks/... reference
-# points at a directory the script never reaches. It must be .apm/-relative.
+# only *.json from .apm/hooks/ — so a ${PLUGIN_ROOT}/hooks/... reference
+# points at a directory the script never reaches. It must be .apm/-relative, and
+# it uses apm's target-neutral token, which apm rewrites identically to
+# ${CLAUDE_PLUGIN_ROOT} for every target (ADR-0019, amendment 2026-09-28).
 referenced="$(python3 -c 'import json,sys; d=json.load(open(sys.argv[1])); print(d["hooks"]["SessionStart"][0]["hooks"][0]["command"])' "$HOOKS_JSON")"
-[[ "$referenced" == '${CLAUDE_PLUGIN_ROOT}/.apm/hooks/check-apm-current.sh' ]] \
+[[ "$referenced" == '${PLUGIN_ROOT}/.apm/hooks/check-apm-current.sh' ]] \
   && pass "hooks.json references the script at its .apm/ path" \
-  || fail "hooks.json references '$referenced' — must be \${CLAUDE_PLUGIN_ROOT}/.apm/hooks/check-apm-current.sh"
+  || fail "hooks.json references '$referenced' — must be \${PLUGIN_ROOT}/.apm/hooks/check-apm-current.sh"
 
 [[ -x "$HOOK" ]] && pass "hook script is executable" || fail "hook script must be executable"
 

tests/test-run-bats.sh

@@ -476,6 +476,40 @@ else
   fail "the plan-shortfall run failed with the wrong count: $FAKE_OUT"
 fi
 
+# --- 12. A build/ directory (apm pack's staging output) is excluded, the same
+# way apm_modules/ and .claude/skills/ above are. A stray local `apm pack` run
+# leaves build/<pkg>-<version>/ on disk holding a full copy of every packaged
+# skill's tests/ directory, gitignored and regenerable, but discoverable by a
+# bare `find` all the same. Those staged .bats files carry the same
+# several-levels-up REPO_ROOT walk-up as any other copy, which overshoots this
+# fixture's root, so an unexcluded build/ turns into the same
+# bats-support-not-found failure apm_modules/ and .claude/skills/ already guard
+# against -- this was caught live with 423 duplicate failures against a real
+# checkout holding a stray build/holocron-*/ from an earlier `apm pack`.
+echo ""
+echo "--- a build/ directory holding staged .bats copies is excluded ---"
+DIR12="$(make_fake_repo)"
+FIXTURES+=("$DIR12")
+seed_bats_files "$DIR12"
+mkdir -p "$DIR12/build/some-pkg-1.0.0/tests"
+printf '@test "staged" { false; }\n' > "$DIR12/build/some-pkg-1.0.0/tests/staged.bats"
+install_stub_bats "$DIR12" <<'EOF'
+#!/usr/bin/env bash
+echo "1..1"
+echo "ok 1 first"
+exit 0
+EOF
+run_fake "$DIR12"
+if [[ $FAKE_RC -ne 0 ]]; then
+  fail "a tree holding a build/ directory failed the run: $FAKE_OUT"
+elif grep -q "build/some-pkg-1.0.0" <<< "$FAKE_OUT"; then
+  fail "a .bats file staged under build/ was discovered and run: $FAKE_OUT"
+elif grep -q "^2 tests, 0 failures$" <<< "$FAKE_OUT"; then
+  pass "a build/ directory's staged .bats copies are excluded from discovery"
+else
+  fail "the build/-exclusion run passed with an unexpected count: $FAKE_OUT"
+fi
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]

tests/test-vale-wrap.sh

@@ -1382,6 +1382,8 @@ plugins/demo/.apm/agents/demo.md|[**/agents/*.md]|isolating
 .claude/agents/demo.md|[**/agents/*.md]|isolating
 plugins/demo/.apm/agents/demo.agent.md|[**/*.agent.md]|overlapping
 copilot/demo.agent.md|[**/*.agent.md]|isolating
+plugins/demo/.apm/instructions/demo.instructions.md|[**/*.instructions.md]|isolating
+plugins/demo/.apm/prompts/demo.prompt.md|[**/*.prompt.md]|isolating
 EOF_PROBE28
 )"