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`