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 waye2e957ehandled 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 from1614bcewas 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 (e4ed343repointed thea8cd5e8citations 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:
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user