fix(kyberforge): resolve clean-context audit findings on primitive support

primitive-author:
- description excludes read-only review (-> factory-audit)
- validation Gotcha now matches the research: compile never reads
  prompts, install fails only on a bad Copilot hook payload and warns on
  prompt input names and dropped keys
- instruction fold-in into AGENTS.md/CLAUDE.md stated as conditional on
  dedup and --force-instructions
- hook checklist gains the wrapped-shape Must, drops hardlinks, notes
  why executable is stricter than the research, and states the
  separate Copilot-targeted package route instead of a blanket "don't"
- prompt Must 5 keeps the research's Copilot-only-key exception; adds
  model-slug and 250-char Shoulds; descriptions name skills or agents
- placeholder instruction covers both FILL IN and FILL_IN_ tokens

factory-audit: hardlink FAIL scoped to instructions and prompts
(find_hook_files skips symlinks only), with bats cases; prompt-flow
description rubric names skills or agents.

forge: version-bump, apm-routes and sources references updated for the
primitive route.

Refs #94

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KkT7RSDwDbmrM9T34b6sTi
This commit is contained in:
2026-09-28 17:40:12 +00:00
parent 0d96dc8282
commit 9ac5340e15
11 changed files with 76 additions and 36 deletions

View File

@@ -50,33 +50,38 @@ target:
`${CLAUDE_PLUGIN_ROOT}` also works but ties the source to one harness's name.
- **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 — do not work around it with a second, Copilot-flat file.
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 or hardlink, and parses as a JSON
object. apm skips invalid JSON silently.
2. Every event value is a list of objects, and every nested `hooks` is a list of objects. Anything
1. The file sits directly in `.apm/hooks/`, is not a symlink, and parses as a JSON object. apm
skips invalid JSON silently.
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.
3. Event names are PascalCase (`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`,
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.
4. The script is referenced as `${PLUGIN_ROOT}/…` (package root) or `./…` (hook directory),
5. The script is referenced as `${PLUGIN_ROOT}/…` (package root) or `./…` (hook directory),
exists inside the package, and is executable. No absolute path, and no `$` or backtick in the
path itself. A missing script is only a warning at install time.
5. No `hooks-<target>` or `*-<target>-hooks` filename. That routing is deprecated; reach belongs to
path itself. A missing script is only a warning at install time. Executable is stricter than the
research's Should: a script invoked as the command's first token fails at runtime without it.
6. No `hooks-<target>` or `*-<target>-hooks` filename. That routing is deprecated; reach belongs to
`targets:` (see Gate).
Should:
6. Every handler sets `"type": "command"` and an explicit `timeout` in seconds — apm passes `type`
7. Every handler sets `"type": "command"` and an explicit `timeout` in seconds — apm passes `type`
through but never supplies it.
7. Set `matcher` explicitly on tool events and on `SessionStart` (`startup`, `resume`, …). Omitted,
8. Set `matcher` explicitly on tool events and on `SessionStart` (`startup`, `resume`, …). Omitted,
Claude receives `"*"`.
8. Do not author Copilot's flat `bash` / `powershell` / `timeoutSec` keys in a Claude-shaped file;
9. Do not author Copilot's flat `bash` / `powershell` / `timeoutSec` keys in a Claude-shaped file;
they render onto Claude as stray keys.
9. Quote a script path that may contain spaces: `"${PLUGIN_ROOT}/scripts/my hook.sh"`.
10. Keep helper files in the hook directory non-JSON. Copilot's loader rejects any bundled `.json`
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.