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`
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user