Files

Defame1297 9285b29e3c fix(factory-audit): flag unbraced plugin-root tokens and close hook check gaps

Why: PR #144 review round 4 reproduced hooks referencing $PLUGIN_ROOT or
${PLUGIN_ROOT} without a path separator passing the audit, although apm
only rewrites ${TOKEN}/ and the deployed hook points nowhere.

- FAIL unbraced or unseparated plugin-root tokens
- check the exec bit for scripts run via an interpreter -c string
- skip env NAME=value prefixes when locating bare relative paths
- correct input: and empty-frontmatter messages, depth-walk applyTo braces
- INFO on unrecognised targets; failing-case tests for untested checks
- document tiers, blind spots and crash exit 2; drop rtk from portable flow
- restore the after-a-hand-edit trigger; pin upstream apm source URL

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

2026-09-29 08:00:17 +00:00

4.6 KiB

Raw Blame History

source_keys

apm-cli-installed-source

apm-docs-llms-full

adr-0029-prompt-house-rule

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's docs call a prompt "a program for an LLM" (apm-docs-llms-full, "What is APM?" › "Secure by default"); 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 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, a file that is not valid UTF-8, unfilled FILL IN or FILL_IN_ template placeholders, frontmatter, description presence, length, and trigger or Not X -> Y boundary clause, keys Claude drops, the camelCase spelling of allowed-tools or argument-hint and an argument-hint alongside input: (both SUGGESTION), input: names and the object form - <name>: "<desc>" (primitive-author prompt Must 3 — a bare name, a string list or a plain map is a FAIL even though apm reads them), and ${input:x} references against input:. Keys Claude drops are a SUGGESTION, per primitive-author prompt Should 5: 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, including a crash inside the checks — 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. That includes the rules scoped to the description (Kyberforge.DescriptionOpener, VagueWording, CompositionNote), a deliberate deviation from primitive-author, which holds description wording to at most a Should: the house prose rules apply to every model- or user-visible description, and a deterministic rule does not change tier by file kind. Do not re-tier them. 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, carries a Not X -> Y boundary clause (primitive-author prompt Should 6), 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:

Checked: structure · prose · role · description

4.6 KiB Raw Blame History Unescape Escape