docs: remove agent-encoded decisions and correct decision records

docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md

@@ -16,8 +16,8 @@
 
 All three reasoned soundly from the oracle. Two did not survive contact with the repository.
 
 The **version guard** was dropped before implementation. Its only in-repo surface — a
 `## [<version>]` heading versus the manifest — is already covered deterministically by
 `scripts/check-changelog-parity.sh --check-bump`, a required CI gate. An enumeration of the
 residual prose surface (all `*.md` under `plugins/` and `docs/`, every string in every
 `plugin.json` and `marketplace.json` outside the `version` field, `plugins/*/hooks/*.sh`,
@@ -36,14 +36,14 @@
 | Findings | **389** |
 | True positives | **0** |
 
 The oracle never misfired — no candidate resolved at the repo root. Every finding was a
 scoping failure. 72% were consumer-project config paths (`.claude/**` and similar) that a
 doc describes for a *consuming* repo and that a marketplace correctly lacks; its
 first-segment gate passed only because this repo happens to carry same-named top-level
 directories. Fixing the three dominant causes still left ~4% firing at zero true positives.
 
 The **reference guard** shipped. Same corpus: 4 true positives, verified individually. Its
 noise was 89% CHANGELOG rename entries — content the hook's own advisory calls correct as
 written, because a CHANGELOG is append-only by contract and a rename entry must keep naming
 the old command. Excluding CHANGELOGs moved it from 3.4% firing at 6% precision to **0.51%
 firing at 57% precision**.
@@ -54,9 +54,9 @@
 been measured against a real corpus.** A sound oracle is a necessary condition, never a
 sufficient one. Specifically:
 
 1. **Measure before shipping, on the real corpus, at real scale — where "real corpus" means the
    guard's deployment surface, not necessarily the authoring repository.** Not a sample, not the
    contract suite. A passing contract suite is evidence for the cases it contains — nothing
    more; an input shape absent from the suite can still be misclassified. A corpus sweep is
    what exposes the scoping. The path guard had 61 green cases and a 23.7% real-world firing
    rate.
@@ -65,11 +65,11 @@
 
    - A guard whose matcher explicitly confines it to this marketplace may measure here.
    - A guard that ships default-on into consumer projects measures against corpora
      representative of that deployment scope — and states which corpora, since a single-repo
      sweep is not evidence about other distributions.
 
    The path guard's dominant failure class — consumer-project config paths (`.claude/**`) that a
    doc describes for a *consuming* repo and that a marketplace correctly lacks — is the
    motivating case: the oracle was exact at the repo root, but the corpus was the wrong
    deployment surface.
 2. **Report the number in the PR.** "It looks quieter now" is not a measurement. The
@@ -77,7 +77,7 @@
 3. **A guard that fires and is never right disqualifies itself**, however sound its oracle.
    The disqualifying condition is **observed false positives with no true positive**, not the
    absence of true positives on its own. A guard that fires on a quarter of writes and is
    never right trains readers to ignore every advisory, including the ones that are right —
    negative value, not low value.
 
    **A guard that does not fire at all is not thereby disqualified.** A corpus may simply
@@ -139,30 +139,10 @@
 - `docs/conventions/hook-precision/README.md` owns the over-fire discipline for a guard
   already in the tree. This ADR is the pre-ship counterpart and defers to it thereafter.
 
-## Session-log grading (#3756)
-
-The per-session hook event log from #3750 is the instrument for a fleet-wide pass:
-blocked-versus-fired per guard, with each block's `subject` available for a
-true/false-positive verdict. `block-hook-bypass` stays in #3721.
-
-**Claim:** no default-on guard is withdrawn, rescoped, or deleted on manufactured
-verdicts. Grading waits on two to four weeks of the operator's own sessions with
-`session_event_log_enabled` on (the switch stays off for consumers). Once that
-window exists, a read-only reduction may emit the findings table (guard, sessions,
-fires, blocks, quoted `subject`) with the true-positive and disposition columns
-blank for the operator. Each non-keep disposition is its own PR with the numbers
-in the body, per clauses 1-4 above. **Basis:** this ADR's "measure before shipping
-on the real corpus" clause; #3756 triage (2026-09-06) that synthetic sessions
-defeat the measurement and that labeling fires is operator judgment. **As of:**
-2026-09-28. **Recheck:** the operator notes a collection-window start date, or a
-session-log corpus large enough to fill the findings table lands in the
-observability store.
-
 ## Sources
 
 - #1270 (scoping, amended twice), #1284 (the two-guard PR, closed), #1319 (the shipped
-  guard), #1314 (the withdrawn guard's measurement and rescope), #3756 (session-log
-  grading parked until an operator collection window)
+  guard), #1314 (the withdrawn guard's measurement and rescope)
 - `docs/conventions/hook-precision/README.md` — over-fire discipline
 - `docs/plugin-philosophy.md` — one mechanism per concern (validation section)
 - `melodic-software/standards`, `conventions/engineering/enforceability-tiers.md` —

docs/adr/0007-host-per-model-doctrine-outside-skill-private-surfaces.md

@@ -69,6 +69,16 @@ skill and agent content as substituting the placeholder anywhere it appears, so
 substitution is a documented contract and the recheck trigger's "not documented" premise no longer
 holds; the probes above stand as corroboration.
 
+*Update (2026-09-29, Claude Code 2.1.284):* a fresh headless `claude -p` probe of a disposable
+`--plugin-dir` plugin, run twice with identical results, measured three surfaces. Skill body:
+`${CLAUDE_PLUGIN_ROOT}` expanded to the plugin root, and a relative path on the next line stayed
+literal. Hook command (`SessionStart`, token single-quoted so the shell could not expand it):
+literal; the variable was set in the hook process environment. Bash-tool environment: unset
+(`printenv CLAUDE_PLUGIN_ROOT` exited 1 with no output). The shell-form hook command does not show
+the inline substitution the plugins reference documents for hook commands ("anywhere in `command`
+and `args`"), while an exec-form `args` element carrying the token expanded to the plugin root in a
+separate probe on the same version.
+
 ## Decision
 
 Per-version model-adaptation chapters live at

docs/adr/0036-make-agents-md-the-instruction-source-behind-a-claude-md-shim.md

@@ -25,29 +25,22 @@ The shims stay until all four cutover conditions hold. They are graded, each wit
 canary, and path detection. `/instruction-placement:migrate remove-shims` takes root and nested
 shims out together once they all hold. The check reruns monthly, and on any Claude Code release
 touching instruction files. The open tracker is
-<https://github.com/melodic-software/claude-code-plugins/issues/5163>
-(#4281 was false-closed when #5160 merged).
+<https://github.com/melodic-software/claude-code-plugins/issues/5163>.
 
 ## Why
 
 Direct reading is conditional in ways a repository cannot fix from inside: it is gated on a remote
-feature flag, is suppressed by any `CLAUDE.md` at or above the working
-directory, needs CLI 2.1.277 or later, and is absent from some sessions entirely. Each of those is
-a four-part dated record in
+feature flag whose code default was false when this was decided, is suppressed by any `CLAUDE.md`
+at or above the working directory, needs CLI 2.1.277 or later, and is absent from some sessions
+entirely. Each of those is a four-part dated record in
 `plugins/instruction-placement/skills/migrate/reference/sources.md` ("The remote flag, and how its
 code default is read", "The documented feature-flag dependency", "The minimum CLI version"), and
 the loading rule itself is the record under "Why the shim stays" in that skill's `SKILL.md`.
 
-On 2026-09-28 those records were re-derived against Claude Code 2.1.282. The bundle code default
-for `tengu_agents_md_mod` reads true, the env-vars feature-flag list no longer names `AGENTS.md`,
-and from v2.1.280 `/memory` lists a directly read `AGENTS.md`. The decision stands: shims stay
-until every graded condition is `[MET]` across the fleet. The same day's fleet run named the nine
-repositories `gh repo list` could read, recorded in `sources.md` under "Accessible fleet graded
-2026-09-28". A standing refresh at 12:31 UTC graded this marketplace at origin/main
-`5e6eade117ec3e6737840434602dbfb930f5ab3e` and the other eight at the commits in that table,
-recorded under "Standing refresh (#5163)": conditions 1, 2, and 4 `[MET]`, condition 3
-`[UNREACH]` because the CLI was logged out. Five repositories from the historical ten on #4281
-were not readable from this host. The verdict stays NOT MET, and `last_checked` stays 2026-09-20.
+Update, 2026-09-29: the remote flag is no longer the blocker. On Claude Code 2.1.282 the bundle
+code default for `tengu_agents_md_mod` reads true, the env-vars feature-flag list no longer names
+`AGENTS.md`, and from v2.1.280 `/memory` lists a directly read `AGENTS.md`. `sources.md` holds each
+condition's current grade under "Current fleet grade": all four read `[MET]`.
 
 The shim costs about 55 tokens per session, never makes Claude read the file twice, and loads in
 the conditions that record lists as unavailable for direct reading (stated under "Why the shim
@@ -60,7 +53,7 @@ Three alternatives were rejected, each with the fact that would flip it:
 
 | Rejected | Why | What would flip it |
 |---|---|---|
-| Native only: delete `CLAUDE.md` now | Accepted while direct reading was still conditional ("The remote flag, and how its code default is read", "Why the shim stays"). Any `CLAUDE.md` above the working directory still suppresses the read | All four graded conditions report `[MET]` |
+| Native only: delete `CLAUDE.md` now | Rejected: it held only while direct reading was conditional (see "The remote flag, and how its code default is read" in `sources.md` and "Why the shim stays" in the migrate skill's `SKILL.md`). Any `CLAUDE.md` above the working directory still suppresses the read | All four graded conditions report `[MET]` |
 | The `claude-md-and-agents-md` both-files setting | A user, `--settings` or managed setting, ignored in project and local settings, so no repository can ship it ("Why the shim stays"); never adopted or run as a convention | The setting becomes readable from project or local settings |
 | A common-ancestor `AGENTS.md` in the directory that holds every clone | No repository versions it, and it misses every worktree checked out outside that tree | Claude Code reads a versioned org-level tier above the repository |
 

docs/out-of-scope/README.md

@@ -1,11 +1,9 @@
-# Rejected-concept ledger (consumer convention)
+# Rejected-concept ledger
 
-Optional per consuming repository. This marketplace keeps one copy at the repo root so
-`work-items:triage` and `work-items:track add` can match incoming requests against settled
-rejections without re-litigating them.
+One file per rejection, matched and appended to as the `/work-items:triage` "Rejected-concept
+ledger" step defines. The ledger records rejections only, never built features or deferred work: a
+deferral, a park, or an open question is an open tracker item.
 
-One file per concept under this directory. Each file records the decision, rationale, revisit
-trigger, and a "Prior requests" log (append-only).
-
-This repository is single-operator today; entries here are publisher-side decisions that also
-apply to marketplace consumers who adopt the ledger shape.
+Two entries are agent proposals the owner has not ruled on, not settled rejections:
+`machine-profile.md` (#4666) and `shared-surface-instruction-governance.md` (#3568). Each says so in
+its own text, and the owner's ruling on that issue confirms, reverses, or removes the entry.

docs/out-of-scope/machine-profile.md

@@ -4,6 +4,11 @@ Record for
 [#4666](https://github.com/melodic-software/claude-code-plugins/issues/4666),
 a proposed host-fact store that would drive every plugin `setup` skill.
 
+Status: unratified agent proposal. The placement is accepted under
+[ADR 0041](../adr/0041-place-the-machine-profile-as-a-claude-ops-skill.md); the owner has not ruled
+on whether to build it or on any setup-contract change, and #4666 is open for that decision. Until
+then it is not a settled rejection.
+
 ## Decision
 
 **Superseded in part.** The design is now
@@ -17,43 +22,56 @@ exists, no new plugin is added, and the rest of this record stands.
   `/<plugin>:setup check` lines for the operator to type. That respects class
   (ii) and is unpaid operator cost, not a skill to ship.
 - **Option 2 (declined):** split `check` from `apply` so `check` is
-  model-invocable. Same ask as #4240. It needs a new invocation-mode class or
-  an amendment to class (ii). The class list is the unit of extension.
+  model-invocable. The per-plugin form shipped in `actionlint`, `biome-format`,
+  `context7`, `go-format` and `markdown-format` (a separate model-invocable `check`
+  skill beside the manual `setup`) with no invocation-mode amendment; the class list in
+  `docs/conventions/invocation-mode/README.md` is still three. Whether to keep that
+  per-plugin split is an open owner question,
+  [#4240](https://github.com/melodic-software/claude-code-plugins/issues/4240) question 2.
 - **Option 3 (declined):** relax `disable-model-invocation` on `check` only.
   Same effect as option 2 with less structure.
 
 **Claim (original park, before the design document):** a re-runnable machine profile that discovers host facts once and
-drives the fleet's setup skills is not implementable without amending
-invocation-mode class (ii) and touching every setup skill; do not build it
-until #4240 records that unblock. Host discovery stays inside each plugin's
-`setup`. If the idea returns after that unblock, it is a `claude-ops` skill
-that feeds `machine-health`'s declared-configuration drift check, never a
-second host-fact store.
-**Basis:** origin/main at this record: 58 plugin-level `plugins/*/skills/setup/SKILL.md`
-files, all `disable-model-invocation: true`.
-`docs/conventions/invocation-mode/README.md` class (ii) and the
-invocation-reach invariant (a `true` skill cannot be invoked by any other
-skill). No `machine-profile` token in `plugins/` or `docs/`.
-`machine-health` already owns a `config` category for declared-configuration
-drift. #4240 is open on the same gate.
-**As of:** 2026-09-28.
-**Recheck:** #4240 records an invocation-mode class (ii) amendment, or a
-maintainer funds a `claude-ops` skill whose only job is a read-only host-fact
-document that `machine-health` consumes.
+drives the fleet's setup skills has no model-invocable path to them: all 58
+plugin `setup` skills are `disable-model-invocation: true`, which
+`scripts/validate-plugin-contracts.mjs` requires. The model-invocable host
+checks are `actionlint:check`, `biome-format:check`, `context7:check`,
+`go-format:check` and `markdown-format:check` (one per plugin) and
+`claude-ops:prerequisites`, a read-only report over the `prerequisites.json`
+that 7 plugins declare. Host discovery stays inside each plugin's `setup`. If the idea returns, it is a `claude-ops` skill that feeds
+`machine-health`'s declared-configuration drift check, never a second
+host-fact store.
+**Basis:** origin/main: 58 plugin-level `plugins/*/skills/setup/SKILL.md`
+files, all `disable-model-invocation: true`, required at
+`scripts/validate-plugin-contracts.mjs:189-190`. The `check` skill of each of
+those five plugins and `plugins/claude-ops/skills/prerequisites/SKILL.md`
+set `disable-model-invocation: false`. `docs/conventions/invocation-mode/README.md`
+still lists three classes, class (ii) among them, and the invocation-reach
+invariant (a `true` skill cannot be invoked by any other skill). No
+`machine-profile` skill or plugin under `plugins/`. `machine-health` already
+owns a `config` category for declared-configuration drift.
+**As of:** 2026-09-29.
+**Recheck:** a setup skill drops `disable-model-invocation: true`
+(`git grep -L 'disable-model-invocation: true' -- 'plugins/*/skills/setup/SKILL.md'`
+lists a file; it lists none today), or a maintainer funds a `claude-ops` skill
+whose only job is a read-only host-fact document that `machine-health`
+consumes.
 
 ## Rationale
 
 - Naive orchestration is impossible today: every setup skill is model-hidden.
-- Options 2 and 3 are a fleet contract change (58 skills plus
-  `validate-plugin-contracts.mjs`), not a claude-ops slice.
+- Option 3 changes the contract `validate-plugin-contracts.mjs` enforces on all
+  58 setup skills. Option 2 adds a `check` skill to each setup plugin that
+  lacks one. Neither is a claude-ops slice.
 - A parallel host-fact document would compete with `machine-health` instead of
   feeding it.
 - Per-plugin setup already owns prerequisite logic and versions with the
   plugin. Absorbing that into one driver is the gotcha the issue named.
 
 ## Revisit when
 
-- #4240 lands a recorded unblock (new class or a class (ii) amendment), or
+- a `setup` skill becomes model-invocable (the Recheck condition above), or
+- the owner rules on the check/setup split in #4240 (question 2), or
 - an operator go names a read-only host-fact document with no setup-skill
   orchestration.