Files

Defame1297 965208bddd fix(kyberforge): resolve PR #144 review and audit round 2

- factory-audit: ./ and bare/absolute script checks scoped to command
  position (no false FAILs on ./src or printf); hook sources limited to
  .apm/hooks or package-root hooks/; Kiro-aware lowercase events;
  unfilled template placeholders FAIL; repo-only instructions FAIL at
  any scope; Vale description FAIL documented; bats 367 -> 378
- primitive-author: split-quote/spaced paths and handler-less entries
  promoted to Must; Step 4.2 renders into a scratch consumer instead of
  a no-op dry run; dispatch and gate hand-off trimmed
- apm-workflow 1.0.2: mutual boundary with primitive-author
- forge: no double package bump; gotcha wording
- skill-author: create keeps seeded 0.1.0 (ADR-0022); portable,
  retry-safe new-skill.sh; template and flow consistency fixes
- hook docs: cite the ADR-0019 correction; guard caveat

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

2026-09-28 20:50:22 +00:00

4.4 KiB

Raw Blame History

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 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, unfilled FILL IN or FILL_IN_ template placeholders, 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.

A missing applyTo is a SUGGESTION, not the FAIL primitive-author's instruction Must 4 implies: absence is legal after the author Gate's explicit yes, which the audit cannot see. The scope dimension's always-on FAILs below cover the misuse. Do not re-tier it by judgment.

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: 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: the content is a rule for this repo alone, scoped or always-on — it belongs in AGENTS.md (a nested AGENTS.md for a subtree), which is the repo's own instruction source, not in a package that ships it to every consumer. This matches primitive-author's Gate, which routes every repo-only rule there.
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:

Checked: structure · prose · scope · description

4.4 KiB Raw Blame History