docs: close the self-contradictions left by the branch's own cuts

CONTEXT.md used two terms it no longer defines. This branch deleted the
Preload tax and Skill context contract entries as audit finding 31, but
the Hand-invoked skill definition and the example dialogue still used
both, bolded, which is this file's convention for a defined term. The
definitional file contradicted itself while AGENTS.md tells every
session to read it as authoritative. Rephrased in place, the way
e2e957e handled the one the audit's own note records.

ADR-0024 said 10 .bats files deploy across 6 skills; ADR-0025 merged
two of those directories the next day, on this branch, leaving 5. It
was also the only ADR ADR-0025 invalidated without an amendment banner,
as was ADR-0016, which still named agent-audit in the present tense as
the live enforcer. Both get the banner the other nine carry, and the
figure and names are corrected in place as well, since these sit in
text asserting present fact rather than a superseded decision.

ADR-0019's correction block from 1614bce was inserted mid-paragraph and
swallowed the original's trailing sentence, leaving the quote malformed
and the next line starting lowercase mid-sentence. gates.md took the
same correction and is not affected.

In the audit note: two of §12's five open follow-ups were already
closed (e4ed343 repointed the a8cd5e8 citations at 598a7c3; #101 closed
2026-09-16, so Closes #101 is a no-op), the same stale hash sat at :330
with a wrong line number, the vale-wrap counts had drifted from 63/19
to 65/14 and are now pinned to a commit per §1's own convention, and
the deleted-suite tally said eight where the diff shows nine.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NwD8Egs5r4ndqeFLmhusX2
This commit is contained in:
2026-09-20 12:34:28 +00:00
parent 384756b343
commit c84f1f4145
5 changed files with 43 additions and 22 deletions

View File

@@ -1,5 +1,13 @@
# Plugin-scope agent-author omits `tools:` and all Claude-only fields from `.apm/agents/*.agent.md`
**Amended by ADR-0025 (2026-09-15).** `agent-audit` was removed and its flow merged with
`skill-audit`'s into `factory-audit`, which dispatches to a skill flow and an agent flow at Step 0.
Read `agent-audit` below as `factory-audit`'s agent flow, and `validate.sh` as that flow's
validator. The decision is unchanged — plugin-scope `.apm/agents/*.agent.md` still carries only the
allowlisted fields, and the allowlist is still read as data from a reference file, now
`factory-audit/references/agent-field-inventory.md`. The present-tense skill names below are
updated accordingly.
This ADR is a narrower, downstream consequence discovered while designing issue #89's
implementation under ADR-0015's broader direction (Microsoft APM replaces hand-authored
plugin/marketplace authoring). It does not restate ADR-0015's rationale — see that ADR for
@@ -47,8 +55,8 @@ Absent `tools:` means inherit-all-tools on both harnesses — the one value that
on either target, unlike a present, harness-specific value that is guaranteed wrong on at least
one of them.
`agent-audit`, at plugin scope, is intended to flag — as a **SUGGESTION**, not a FAIL, since
this is an upstream schema limitation rather than an authoring mistake — any agent whose
`factory-audit`'s agent flow, at plugin scope, is intended to flag — as a **SUGGESTION**, not a
FAIL, since this is an upstream schema limitation rather than an authoring mistake — any agent whose
description or body implies a need for tool restriction or a Claude-only behavior the
frontmatter can no longer express. This would give visibility into the gap without pretending
the schema can do something it can't. **Not yet implemented**: `check_apm_agent_file()` in
@@ -71,7 +79,7 @@ write Claude's space-separated `tools:` string. Rejected because it ships a valu
silently wrong (or possibly a hard error) on Copilot, and which harness "wins" would be an
arbitrary, undocumented asymmetry.
**Same as above, but `agent-audit` flags the cross-harness breakage as a tracked finding
**Same as above, but `factory-audit` flags the cross-harness breakage as a tracked finding
(rejected).** Rejected for the same core reason — it still ships a wrong value to a real
harness. Tracking the breakage doesn't prevent it, and the chosen decision already gets
equivalent visibility (a SUGGESTION finding) without ever shipping the wrong value in the first
@@ -141,7 +149,7 @@ admitted as the portable-by-construction half of what was lost. It restores a re
confirmed write fence against the tool-call path, not a complete write sandbox. The consequence
below is narrowed accordingly.
Enforcement follows the decision: `agent-audit`'s plugin-scope validator reads its allowlist as
Enforcement follows the decision: `factory-audit`'s plugin-scope validator reads its allowlist as
data from the `apm-agent-allowlist` section of
`plugins/kyberforge/.apm/skills/agent-audit/references/field-inventory.md` (now
`factory-audit/references/agent-field-inventory.md`, see ADR-0025), and that line now reads
@@ -161,9 +169,9 @@ whether a field is safe under verbatim copy in a single vendor-neutral file.
Plugin scope is now "directory containing `apm.yml` → single vendor-neutral file lands in
`<root>/.apm/agents/`." Project and user scope, and the rest of ADR-0005, are unaffected.
- **ADR-0008 is partially superseded** — its counterpart-derivation/pair-validation mechanism
no longer applies at plugin scope; `agent-audit` takes the single file directly there. Project
no longer applies at plugin scope; `factory-audit` takes the single file directly there. Project
and user scope, where a real pair still exists, are unaffected.
- **ADR-0009 is not superseded.** The mechanism it established — `agent-audit` reading field
- **ADR-0009 is not superseded.** The mechanism it established — `factory-audit` reading field
lists from `references/field-inventory.md` (now
`factory-audit/references/agent-field-inventory.md`, see ADR-0025) rather than hardcoding them,
with a `source_keys`

View File

@@ -85,12 +85,13 @@ question is only what catches a missed edit.
> does not silently stop the hook deploying. Whether apm behaved this way when this ADR was written
> was not established. **The decision stands** — `scripts/check-executables-allow-sync.sh` is now
> justified by this repo's own requirement that the key track `plugins/kyberforge/apm.yml`'s
> `version:`, not by an apm-level failure mode. `docs/spec/gates.md` carries the same correction. A comment in the `executables:` block is not enough:
this repo gates generated-content drift, marketplace mirror drift and vale style drift
deterministically, and a silent-staleness failure is strictly worse than any of them. So
`scripts/check-executables-allow-sync.sh` runs at pre-push, parsing `version:` out of
`plugins/kyberforge/apm.yml` and asserting root `apm.yml` carries the matching
`kyberforge#<version>` key. The comment stays as the human-facing pointer; the hook is what
> `version:`, not by an apm-level failure mode. `docs/spec/gates.md` carries the same correction.
A comment in the `executables:` block is not enough: this repo gates generated-content drift,
marketplace mirror drift and vale style drift deterministically, and a silent-staleness failure is
strictly worse than any of them. So `scripts/check-executables-allow-sync.sh` runs at pre-push,
parsing `version:` out of `plugins/kyberforge/apm.yml` and asserting root `apm.yml` carries the
matching `kyberforge#<version>` key. The comment stays as the human-facing pointer; the hook is what
actually holds. It parses with PyYAML where importable and falls back to a two-shape scan
otherwise, so a missing pip package cannot become the thing that blocks every push.

View File

@@ -13,6 +13,14 @@ ADR-0015. The root `marketplace:` block in `apm.yml` and the compiled
`.claude-plugin/marketplace.json` it produces are **kept** — see "Also delete the marketplace
catalogue" under considered options.
**Amended by ADR-0025 (2026-09-15).** The decision stands unchanged — apm is the only supported
install path, and `.apm/` still ships the per-skill `tests/` directories this ADR accepted as
dev-fixture leakage. What moved is **consequence 2's skill count**. `skill-audit` and `agent-audit`
merged into `factory-audit`, collapsing two `.bats`-carrying skill directories into one, so the same
10 `.bats` files now deploy across **5** skills, not the six counted here on 2026-09-14. The figure
below is corrected in place; "all six `apm.yml` files" in the same paragraph counts plugins, not
skills, and is unaffected.
## Context
ADR-0018 moved this repo's own consumption of its own plugins onto `apm install`. From that point
@@ -167,7 +175,7 @@ README note is the only available mitigation, and a note is not a gate.
**2. Consumers now receive dev-fixture files.** apm installs from `.apm/`, and `.apm/` contains the
per-skill `tests/` directories the mirror explicitly stripped (ADR-0017's depth-scoped
`<category>/<name>/tests` exclusion). 10 `.bats` files across 6 skills therefore now deploy into
`<category>/<name>/tests` exclusion). 10 `.bats` files across 5 skills therefore now deploy into
every consumer's skill directories. Suppressing them would mean switching all six `apm.yml` files
from `includes: auto` to explicit include lists — and an explicit list that is wrong silently drops
content, which is the same failure class ADR-0017 was written to fix. Trading a cosmetic problem for