@event4u/agent-config 9.7.0 → 9.8.0

package/docs/decisions/ADR-126-internet-reach-operator-tooling.md

@@ -0,0 +1,254 @@
+---
+adr: 126
+status: accepted
+date: 2026-07-24
+decision: internet-reach-operator-tooling
+supersedes: —
+superseded_by: —
+phase: road-to-internet-reach
+type: structural
+---
+
+# ADR-126 — Internet reach: operator tooling shipped, router skill cancelled by its own gate
+
+- **Status:** Accepted (2026-07-24)
+- **Closes:** `agents/roadmaps/archive/road-to-internet-reach.md`
+- **Related:** `docs/contracts/no-runtime-boundary.md` (Class A boundary); ADR-112 (read-only command discipline); ADR-123 (hardened spawn env); ADR-124 (embedded-engine doctrine / Class A–C); `src/rules/lethal-trifecta-guard.md`; `src/rules/source-confidentiality.md`; `src/skills/supply-chain-intake/SKILL.md`; `docs/benchmark.md` § internet-reach.
+
+## Context
+
+The package had no coverage for internet reach: no web-research router, no
+upstream-tool health check, no platform-access prescriptions. `CAPABILITIES.yaml`
+listed 279 skills across 28 areas with `gaps: 0` — true for the areas the index
+tracks, and internet reach was not one of them.
+
+An external capability-layer reference (anonymized per `source-confidentiality`;
+provenance retained as an `ENC1:` token in the roadmap) solves this with four
+jobs — backend selection, installation, health checking, routing — while
+explicitly not wrapping the upstream tools. Three of its mechanism shapes were
+worth absorbing: ordered-backend channels (switching a backend is reordering a
+list, not editing code), a five-state probe taxonomy with stale-shim detection,
+and a tiered access model. Four of its practices were rejected outright:
+auto-installation from an unpinned archive, browser-credential harvesting,
+an agent-obligating update-check standing rule, and a "MUST USE" trigger with no
+published evidence.
+
+The open question was **not** whether those mechanisms are implementable — they
+plainly are — but whether a reach layer earns its place next to the host's own
+web-search and web-fetch tools. That question was made falsifiable before any
+tracked code existed.
+
+## Decision
+
+**1. The reach layer is Class A.** Deterministic, command-invoked probe /
+doctor / validation scripts. No LLM call and no network access in the build
+path, no resident process, no daemon, no wrapper CLI, no MCP reach server.
+Reading and searching itself stays "the agent calls the upstream tool directly".
+Every subprocess spawn routes through `hardenedSpawnEnv()` (ADR-123).
+
+**2. Scope was decided by a pre-registered benchmark, before authoring.** 12
+credential-free dev-research tasks × 2 arms (host-native tools vs. prototype
+reach prescriptions), thresholds and three verdict bands committed before the
+run, prescriptions prototyped in gitignored scratch first so both arms were real
+at scoring time.
+
+**3. The benchmark returned a null, and the null was honoured.** The native arm
+passed 12/12; the reach arm scored **0 outright wins of 12** under the
+pre-registered rule (reach wins only where native fails; ties are native wins) →
+band `stop`. Therefore **no router skill ships.** The `internet-reach` skill,
+its gated-platform prescription set, and the shipped-skill verdict run were
+cancelled *pre-authoring* by the gate that was built to cancel them.
+
+**4. The verdict-independent operator tooling ships anyway,** because it answers
+a question that does not need a router: *is the upstream tool I already chose to
+install healthy, and is its install command pinned?* Concretely: a
+schema-validated channel registry, a five-state probe engine with stale-shim
+detection, a read-only `reach:doctor`, and a CI gate that fails on any unpinned
+install prescription.
+
+**5. Supply chain is prescription-first, mechanized.** No automatic installation
+of system packages, no piping a remote script into a shell. The doctor emits an
+exact pinned command; a human runs it. "Every prescription passes the intake
+gate" is enforced by `check_reach_channels` + `validate_reach_prescriptions` in
+CI, not by an honour system — the failure mode the reference itself exhibits.
+
+**6. Two capabilities are refused, not deferred-with-a-wink.** Browser-credential
+extraction (a lethal-trifecta leg; the reference documents the account-ban risk
+it creates) and CN-market channels (perpetual anti-bot maintenance, no demand
+signal in this audience). Re-opening either requires a named demand signal and
+its own roadmap.
+
+**7. An adversarial security review ran pre-merge and found a real HIGH — it was
+fixed, not documented-around.** The review (`agent-security-review` +
+`threat-modeling` over the five reach scripts, the two schemas and the
+registration) confirmed the design's strongest property: neither spawn site uses
+a shell, no reach script contains a write primitive, no fetched byte reaches any
+payload (both spawns discard stdout/stderr, so the only network-derived datum is
+an exit code), the credential check stats and never reads, and all three gates are
+fail-closed (13/13 negative fixtures non-zero, controls zero). It also found that
+`reach:doctor` never validated the registry at runtime while the schema's
+`probe_args` denylist leaked — a registry entry of `probe_cmd: sh` +
+`probe_args: ["-c", "<payload>"]` passed all three gates with ✅ and was then
+executed and reported as healthy under the innocuous backend label. The false
+assurance was the defect: the schema asserted a probe "can never install, write,
+or authenticate as a side effect", and that was not true. Fixed in the same
+change: `collect()` now enforces the schema and refuses on any error-severity
+finding (exit 2), `probe_args` became a flag-shaped **allowlist**, `probe_cmd` is
+bound to equal its backend `id` (so a row can never label a different binary), the
+prototype-chain lookup on the deep-probe table is guarded, the CI refusal moved
+from the CLI layer into `collect()`, parse errors no longer echo file content, and
+the read-only witness assertion was narrowed to what it actually measures. Two
+permanent regression fixtures cover the hostile-registry shape. The schema comment
+now states a bounded claim and explicitly declines to promise that every upstream
+binary is side-effect-free under every flag — that judgement stays with the human
+adding a backend.
+
+**A second review round — an external bot gate plus a paid multi-model council —
+found one more real primitive, and two of its HIGHs did not reproduce.** Recorded
+because a review trail that only lists confirmed hits teaches the wrong lesson
+about review. The bot gate's two HIGH findings were probed before being believed
+and **neither reproduced as worded**: the deep-probe table was already
+`Object.hasOwn`-guarded behind a `collect()` gate that validates before any load
+or spawn, and a nine-way probe matrix over every entry point showed the parse
+paths leaked nothing. Its `removal_after`-compared-lexicographically finding was a
+false positive twice over (the code parses to epoch numbers, and the schema pins
+both date fields to a fixed-width ISO pattern). Each is now documented at the site
+so it cannot be re-raised without reading the refutation. What the round DID find:
+(a) the grep gate echoed matched file lines verbatim, so `--registry <any file>`
+printed that file's content back — closed at all **four** echo sites, the fourth
+found only by re-running the probe against every entry point instead of assuming
+three fixes had closed the class; and (b) via the council, `credential_path` was
+an arbitrary-path oracle — a registry declaring
+`credential_path: ../../../../etc/passwd` made the doctor report that path's
+existence and permissions at exit 0 inside a normal-looking health row. Now
+confined to the operator's home, this repo, or the temp dir, checked against both
+the literal and realpath'd form of each (so a symlink cannot escape), refused
+before any syscall, and reported as a refusal rather than a silent skip. Both fixes
+are mutation-tested: forcing the confinement open turns six tests red, and deleting
+the file-type check turns the directory case red.
+
+## Consequences
+
+**Good.**
+
+- The most expensive possible mistake — authoring, projecting, indexing and
+  publicly claiming a router skill that loses to tools the user already has —
+  was avoided by measurement rather than by taste.
+- What shipped is small, deterministic and independently useful; it carries no
+  availability promise and no SLA.
+- A published null strengthens the package's evidence posture: the benchmark
+  surface now contains a case where the package's own proposed feature lost.
+- Pinning and lifecycle discipline are machine-checked, so the supply-chain
+  claim is falsifiable rather than aspirational.
+
+**Bad / accepted costs.**
+
+- The capability gap for **gated platforms stays open.** The credential-free
+  task set (needed for reproducibility) structurally excluded the two cases
+  where a reach advantage was hypothesized: video subtitles (backend absent →
+  `untested`) and authenticated / rate-limited access. The null is therefore
+  narrow: *on public, credential-free dev-research tasks*, a reach layer buys no
+  capability the host lacks. Anyone wanting the gated case measured must
+  pre-register a credentialed task set with its own thresholds.
+- A **measured cost asymmetry is left on the table on purpose.** On all 8 tasks
+  both arms solved, the reach arm cost 0.46× the native arm's tokens (0.26× on
+  repository metadata, 0.31× on discussion search) — the native arm repeatedly
+  paid *discovery overhead* to find the machine-readable endpoint the
+  prescription already knows. This is recorded outside the decision: the token
+  threshold was authored as a ≤1.5× guardrail, never a win condition, and
+  promoting it to one after seeing the data would be precisely the post-hoc
+  rigging the bands exist to prevent. Acting on it requires a separate,
+  cost-primary pre-registration.
+- **Both accepted costs now have a named re-entry point,** so neither stays a
+  footnote: the credential-gated case the keyless task set could not ask, and the
+  cost thesis (whose pre-registration must make token cost the primary metric and
+  must price the maintenance cost of the thing winning). Both are parked as
+  named plans in the roadmap layer with explicit resume triggers — a named demand
+  signal, a measured host-capability regression, or a maintainer decision. Paths
+  are deliberately not cited here: the roadmap layer is transient and a stable
+  artefact must not link into it (`no-roadmap-references`). The gated-platform one
+  has since fired and been executed — see § Amendment 2026-07-25. Neither may reuse this
+  roadmap's task set or thresholds: a capability-shaped corpus must not be
+  allowed to decide a cost question, and vice versa.
+- The registry carries maintenance weight (upstream tools break at platform
+  cadence). Contained by `last_verified` + an offline staleness lint + an
+  append-only upstream-change log — not by a scheduled network job, which would
+  buy flaky CI and an implicit availability promise.
+
+## Alternatives considered
+
+- **Ship the router anyway and measure later.** Rejected: re-benchmarking an
+  already merged, indexed and comparison-table-listed skill documents a decision
+  instead of gating it. The gate has to be able to say no.
+- **Lower the win threshold until the reach arm passes.** Rejected as rigging.
+  Worth recording that the band is *defect-insensitive* here: two reach failures
+  were prescription bugs, but repairing them yields ties, and ties are native
+  wins — zero native failures means zero possible reach wins regardless of
+  prescription quality. There was nothing to salvage by re-running.
+- **Promote the token-cost finding into the verdict.** Rejected for this
+  roadmap; see the accepted cost above. It is a genuine signal and it deserves
+  its own honest experiment, not a retrofitted one.
+- **A weekly scheduled job probing every upstream backend.** Rejected: flaky CI
+  against third-party endpoints plus an availability promise the package does
+  not make. Replaced by staleness metadata + an operator-invoked deep check.
+- **A credits/attribution entry naming the reference.** Rejected:
+  `source-confidentiality` forbids derivation-attribution in tracked artefacts,
+  and the license carve-out covers vendored code only — nothing is vendored.
+  Provenance lives anonymized in the roadmap with the link as an `ENC1:` token,
+  and the reference's identifying tokens were added to the CI denylist so a
+  future accidental attribution fails the build.
+
+## Amendment 2026-07-25 — the gated-platform gap, measured and partly closed
+
+This ADR's null was scoped explicitly: *"It says nothing about gated-platform
+access. Testing that needs a credentialed task set with its own
+pre-registration."* That test has now run, and the first thing it found is that
+the sentence's premise was wrong — **no credentials were needed**.
+
+**Closed for three channels, credential-free.** Reddit thread text (Atom feeds),
+Reddit comment **ranking and reply nesting** (server-rendered HTML), and a single
+named tweet (the platform's own oEmbed endpoint) all reached 6/6 against a
+pre-registered task set with a native control and thresholds frozen before the
+run. The native arm scored 0/6 on both Reddit tiers, because the host's own tool
+refuses the `reddit.com` domain outright. Evidence: `docs/benchmark.md`
+§ gated-reach; `internal/bench/gated-reach/{README,results,VERDICT}.md`.
+
+**Still open, each with its re-entry trigger.**
+
+| Surface | State | Re-entry trigger |
+|---|---|---|
+| YouTube transcripts | **parked, unexercised** | the backend is installed by a human and one real extraction is run |
+| Reddit logged-in HTML (session cookie) | parked | an observed login wall on `old.reddit` **and** the maintainer choosing that successor |
+| Reddit approved Data API | parked | the maintainer choosing the durable path — approval-only, weeks of latency, so it starts before it is needed or not at all |
+| Twitter timelines / search | parked | a task that genuinely needs them; no credential-free path exists |
+| Headless browser | parked | a measured need on a fourth platform |
+| Audio transcription fallback | parked | a video task failing specifically because no caption track exists |
+
+**The credential-free scope was a deliberate cut, not an oversight.** Adding a
+credential to any of these channels would put a secret on the same autonomous
+path as untrusted third-party content (Reddit comment bodies, tweet HTML) and an
+outbound fetch — all three legs of the lethal trifecta at once, which
+`lethal-trifecta-guard` exists to prevent. Keeping every prescription
+credential-free keeps that leg broken **by construction** rather than by
+discipline. It also removed the whole consent-gate / credential-file /
+account-ban surface that the design council named as the sharpest risk in this
+area. The cut cost real capability (no timelines, no search, no metrics) and
+that cost is recorded rather than hidden.
+
+**One bound this amendment does not soften.** Reddit tier 2 is on an announced
+closing path (login requirement announced 2026-06-30, still not enforced on the
+bench machine on 2026-07-25). It ships with a kill-switch keyed on an
+**observed** login wall — never on the announcement — plus a reverse trigger that
+keeps the tier alive while logged-out access still works. A press release is not
+an outage.
+
+## References
+
+- `internal/bench/reach-vs-native/README.md` — pre-registered tasks, thresholds, bands, run protocol.
+- `internal/bench/reach-vs-native/VERDICT.md` — tally, per-channel S0a/S0b, `band: stop`, honest limitations.
+- `docs/benchmark.md` § internet-reach — the published null.
+- `internal/upstream-changes.md` — maintenance log for channel breakage.
+- Council: anthropic/claude-sonnet-4-5 + openai/gpt-4o, 2026-07-24, 3 rounds — converged on the five structural defects of the first draft (impossible sequencing, rigged threshold, post-facto verdict, unfalsifiable acceptance criteria, unmechanized discipline claims); all five fixed before execution.
+- `internal/bench/gated-reach/VERDICT.md` — per-channel verdicts + kill-switch criteria (Amendment 2026-07-25).
+- `docs/guides/gated-platform-reads.md` — the shipped operator prescriptions.
+- `src/skills/gated-reach/SKILL.md` — the ship-tier skill, triggers proven both directions.

package/docs/decisions/ADR-127-enforcement-claims-must-resolve.md

@@ -0,0 +1,150 @@
+---
+adr: 127
+status: accepted
+date: 2026-07-25
+decision: enforcement-claims-must-resolve
+supersedes: —
+superseded_by: —
+phase: road-to-enforcement-proof · P1–P5
+type: structural
+review_trigger: >-
+  When resolved enforcement coverage stops rising across two consecutive
+  releases while rules keep being added — that would mean the field is being
+  filled in to satisfy the gate rather than to record a real backstop, and the
+  ratchet has become ceremony. Also reopen if a `validator:` declaration is
+  found resolving green through an indirection that does not actually execute
+  it, which would mean the reachability test has itself become fail-open.
+---
+
+# ADR-127 — An enforcement claim must resolve, not merely exist
+
+## Status
+
+**Accepted** · 2026-07-25.
+
+## Context
+
+A source-level comparison against an external governance reference surfaced one
+defect class this package could not see from the inside: **prose that asserts
+enforcement the code does not deliver.** Four verification agents re-read every
+load-bearing claim against this repo's own source. Five instances survived
+verification:
+
+- `src/rules/output-discipline.md` asserted "violations cause a CI exit-code-2"
+  while `lint_output_slop.ts` shipped and was wired into nothing.
+- `check_kernel_rule_bundle.ts` — the one-kernel-rule-per-PR slow-rollout gate —
+  watched `.agent-src.uncondensed/rules`, a tree retired in the ADR-051 move to
+  `src/`. A path that cannot exist never matches, so the gate reported "no kernel
+  rule touched" for every kernel-rule edit, indefinitely.
+- `docs/contracts/subagent-boundary.md` stated as fact that "every floor applies
+  inside the subagent"; the brief schema, the spawn composer, and all eight
+  worker-prompt templates contained no floor text at all.
+- The override layer documented no non-overridable class, so the shipped consumer
+  README described unconditional whole-file shadowing — an empty file at
+  `agents/overrides/rules/non-destructive-by-default.md` reading as a way to
+  remove the Hard Floor.
+- 128 ADRs, zero naming a revisit condition, because ADR frontmatter was
+  **entirely unvalidated** — `validate_frontmatter.ts` covered skills, rules,
+  commands, and personas and nothing covered `docs/decisions/`.
+
+Nothing in the existing gate set could detect any of them, for one shared reason:
+**every gate checked that a pointer resolves, never that a claim is true.** The
+claims ledger is the clearest case — three evidence forms, all existence checks
+(file present, substring present, URL carries a date), and a `last_verified`
+field that is parsed and compared to nothing.
+
+The reference object's most transferable norm, and the one adopted here: a rule
+with no feasible enforcement tier is deleted rather than kept as honor-system
+theatre, and a check with no real input is left unwired rather than run as
+decoration. Notably, the reference violates its own version of this in two places
+(a nucleus its ADR sizes at "~15 lines" that is 9; a freshness check its ADR
+promises as FAIL that registers WARN) — which is itself evidence that the defect
+class is structural, not a lapse of care.
+
+## Decision
+
+**An enforcement claim is credited only when it resolves against the filesystem
+AND the wiring. Declaration is not evidence.**
+
+1. Rules carry `enforced_by:` — `hook:` / `validator:` / `test:` / `observer:` /
+   `none` — and `check_enforcement_coverage.ts` **resolves** each value. A
+   `validator:` whose script exists but is reachable from no taskfile, workflow,
+   or hook manifest resolves to `unwired`, not covered. Reachability is
+   transitive, so a sub-check running under a wired umbrella counts; a mention in
+   a comment does not.
+2. **Blocking and instrumenting are different tiers.** A hook registered
+   `fail_closed: false` resolves to `observer`, never `validator`. Of 18
+   registered hooks, exactly one can block.
+3. `none` is legal and **counted**. Undeclared rules count as uncovered, not as
+   excluded — a coverage number over only the rules that opted in would be
+   flattering and useless. The published figure is 14 of 107 (13.1%).
+4. **Kernel and safety-floor rules are non-overridable, with a registry.** A
+   `replace`-mode override on one is refused; an `extend` (a tightening) requires
+   an entry in `agents/overrides/kernel-exceptions.yml`. Direction matters, not
+   identity — this package's own legitimate override *tightens*
+   `verify-before-complete`, and a blanket name ban would forbid it.
+5. **The override audit reports; it does not pretend to police.** A build-failing
+   lint on kernel-named override files would guard one of several routes by which
+   a consumer can tell a model to ignore a rule, and would relocate the rest out
+   of sight while reading as coverage. It hard-fails only on this package's own
+   authoring surface, where the coverage claim is true.
+6. **The subagent floor is generated and delivered.** Derived from the kernel rule
+   list, written into every dispatch prompt in `src/` **and** the shipped
+   `dist/agent-src/` projection, drift-gated with a FAIL.
+7. **ADRs name a revisit condition, not a cadence.** Required from 2026-07-25
+   forward, grandfathered by date rather than by an allowlist. A bare "annually"
+   is rejected — a calendar review is ignored; an event fires.
+8. **`exec:` evidence is scheduled by measurement, not by appeal.** The threshold
+   (≥ 10 pp of the backed ledger) was pre-registered before the count was taken;
+   the measured figure is 10 of 25 feasible (40 pp) against 0 today, so it
+   proceeds — in its own PR, not this one.
+
+## Consequences
+
+**Good.** The defect class is now continuously measurable and ratcheted: blocking
+coverage may not fall and unwired declarations may not rise. Two live defects
+were closed on the first run (D1, and the kernel gate watching a dead path), and
+a third — the floor missing from the shipped projection — was caught by grepping
+`dist/` after the generator's first pass. The kernel rule list is single-sourced,
+ending three copies and two "kept in sync with…" comments.
+
+**Cost.** 86 rules are undeclared and drag the published number down; that is
+intended, and it means the headline figure will look bad until the field is
+filled in honestly. `enforced_by` is a schema change on an
+`additionalProperties: false` schema, so it cannot be added ad hoc.
+
+**Accepted limits, stated rather than papered over.** The override carve-out is a
+norm with a partial gate: the layer is model-resolved, so an `extend` block whose
+prose says "ignore the above" passes, and other relax routes (a persona file,
+host config, a direct instruction) are outside its view. The subagent floor
+covers dispatches through this package's templates; whether a host-native spawn
+inherits anything is a host property this package does not control and does not
+claim. `non-destructive-by-default` remains `enforced_by: none` — no script can
+enforce "ask before you deploy", and adjacent hooks guard hook-bypass rather than
+destructive intent, so claiming them would inflate the number.
+
+## Alternatives
+
+- **Declaration-only `enforced_by`.** Rejected: it would have rated
+  `output-discipline` as enforced, which is the exact defect that motivated this.
+- **Blanket ban on kernel overrides.** Rejected on both council members'
+  reasoning: it forbids legitimate tightening, including this repo's own.
+- **A build-failing kernel-override lint.** Rejected as security theatre — see
+  Decision 5.
+- **Build `exec:` evidence first.** Rejected on sequencing: without the coverage
+  baseline there was no way to know whether a new evidence form, validator, and
+  renderer would move falsifiability by 7% or 60%.
+- **Retrofit `review_trigger` across all 83 structural/security ADRs.** Rejected:
+  it would mean inventing ~80 conditions to satisfy a field. Three ADRs with
+  demonstrably time-bound premises were retrofitted (ADR-016, ADR-109, ADR-110).
+
+## References
+
+- `internal/reports/enforcement-coverage.json` — the ratcheted baseline.
+- `internal/reports/exec-evidence-feasibility.json` — the pre-registered
+  measurement and its decision.
+- `docs/proof.md` § 2b — the published coverage figure and the ledger's own limit.
+- `docs/contracts/subagent-boundary.md` § Honest scope of the floor guarantee.
+- `src/agent-src/contexts/override-system.md` § The non-overridable class.
+- ADR-051 (`src/` as source of truth) — the move that silently disarmed the
+  kernel-bundle gate.

package/docs/decisions/ADR-128-executable-evidence-and-measured-escalation.md

@@ -0,0 +1,201 @@
+---
+adr: 128
+status: accepted
+date: 2026-07-25
+decision: executable-evidence-and-measured-escalation
+supersedes: —
+superseded_by: —
+phase: road-to-executable-evidence · P1–P4
+type: structural
+review_trigger: >-
+  When an `exec:` claim is found green while the thing it asserts is false —
+  which would mean the exit code stopped carrying the verdict and the form has
+  become a more expensive pointer. Also reopen when a ledger surface is edited
+  by anyone other than the maintainer, because contributor access is the
+  premise the deferred tamper-chain disagreement turned on and this package
+  does not have it yet.
+---
+
+# ADR-128 — Evidence that re-derives itself, and escalation that is measured before it bites
+
+## Status
+
+**Accepted** · 2026-07-25. Continues ADR-127.
+
+## Context
+
+ADR-127 made an enforcement claim resolve against the wiring rather than merely
+exist, and closed five live defects doing it. It deliberately left one thing
+measured and unbuilt, in its own Decision 8: the claims ledger still checked
+that an evidence pointer **resolves**, never that the claim is **true**. A ledger
+entry reading "the suite is green" whose pointer resolves to a report nobody
+regenerated stays `backed` indefinitely — the pointer resolves, the claim is
+false. The pre-registered threshold for building the fix was ≥ 10 pp of the
+backed ledger, set before counting; the measurement came back 11 of 26 feasible.
+
+A second round of the same external comparison raised four further candidates
+and a council was run over the cut (two members, two rounds). Both members
+independently scoped in the `exec:` form and a content-driven risk axis, and
+scoped out filling the 86 undeclared `enforced_by` fields and a
+lifecycle-scenario cost model. The reasoning is recorded below because kills
+that are not written down get re-proposed by the next analysis round.
+
+The missing risk axis is concrete rather than theoretical.
+`discipline_profile: auto` resolves rigor by host capability — *how much
+governance can this environment afford*. Nothing asks *how dangerous is this
+diff*. The live combination that leaves open: a weak host plus a diff in the
+installer's provenance path resolves to minimum discipline, which is precisely
+the change class hardened in 9.6.0. The fix landed; the process escalation for
+the next change of that class did not.
+
+## Decision
+
+**1. `exec:` is the fourth evidence form, and it re-runs the command.**
+`exec:<command> -> <exit-code>`. The exit code carries the verdict. The
+allowlist is a set of argv prefix tuples in
+`src/scripts/_lib/exec_evidence.ts`, never a regex over a command string — a
+regex over shell text is the classic bypass. Every argument after the matched
+prefix is re-checked for shell metacharacters and repo escape, **including the
+right-hand side of `--flag=value`**, without which `--rootdir=/etc` clears an
+allowlist that only inspected the flag name.
+
+**2. Re-execution is CI-only; the static half runs everywhere.** Whether a
+pointer is well-formed and allowlisted is a property of the *ledger*, so it
+fails on a laptop too. Whether the command actually passes is a property of the
+*environment*, so it runs only on an ephemeral CI runner and never in a
+consumer's checkout. Locally the gate reports `UNVERIFIED — re-execution is
+CI-only, skipped locally`, never a silent pass.
+
+**3. A skip is not a failure, and a failure is not a skip.** "Ran and
+disagreed" is a finding. "Could not run" is not. Collapsing the two turns the
+verifier into a rubber stamp in one direction or a nuisance in the other.
+
+**4. The feasibility count was corrected down by one, by building it.** Of the
+11 measured feasible, 10 survived contact. `context-token-reduction` was counted
+feasible because `check_token_regression` re-derives token figures with a real
+tokenizer — but the script reads `internal/bench/reports/projection-cost.json`,
+which is gitignored as a per-run artefact, so the command is not self-sufficient
+in a fresh checkout and exits 1. The `exec:` gate found this on its first CI
+run. The corrected figure is 10 of 26 (38.5 pp), still far above the
+pre-registered 10 pp bar, so the decision to build stands on the corrected
+number too — the over-count changed the margin, not the verdict.
+
+**5. The residue is published, not rounded away.** `docs/proof.md` states how
+many backed claims re-derive themselves versus rest on a pointer, and lists each
+non-re-executable claim with the reason: external cite, paid or stochastic
+benchmark output, or a prose contract with no exit code to carry a verdict.
+
+**6. Trust-boundary risk is classified now and gated later.** The classifier is
+path-based and reproducible from the diff alone — no model judgement about
+whether a change "feels risky". Three classes: authentication and token
+handling; installer, provenance, publish, and subagent-spawn paths; governance
+surfaces. The docs exemption is scoped to prose *about* a system, not to any
+markdown file: in this repo the rules, `AGENTS.md`, and the kernel set are all
+`.md` and are executable policy. An extension-only test classified
+`src/rules/icon-consistency.md` as unclassified, which a test caught before the
+report shipped.
+
+**7. Escalation is additive and the direction is encoded, not left to callers.**
+The host profile sets a floor; a risk trigger may only raise it. A weak host
+must never be able to lower an escalation — that inversion is the entire failure
+mode the second axis exists to prevent, so `escalated_floor` takes a maximum
+rather than trusting each call site to get the order right.
+
+**8. The non-declinable escalation is justified by measurement, and still not
+built here.** The threshold — ≥ 5 of ~100 first-parent merges landing in a
+trust-boundary class — was written into the roadmap before the report was first
+read. Measured: **11 of 99**. That clears the bar, so a non-declinable class for
+trust-boundary diffs is warranted and gets its own ADR and its own PR. It is
+deliberately not enabled by this one, because it trades away something the
+authority model holds (`agent-authority`, `ask-when-uncertain`) and that trade
+deserves its own decision record rather than riding along inside a measurement.
+
+**9. The prevented-failure table is generated and gated.** Each row names a
+failure mode rather than a feature, and cites a ledger claim. A cited id that is
+missing or not `backed` **throws** during generation. The format was borrowed
+from the reference; the discipline was not available to borrow — the reference's
+own equivalent table carries a headline efficiency figure that appears nowhere
+else, an order of magnitude below the cheapest scenario in its own generated
+benchmark. A number with nowhere to resolve is exactly what this ledger exists
+to catch, so the table is held to the ledger's bar.
+
+**10. Three candidates are closed rather than left open.**
+
+- **Filling the 86 undeclared `enforced_by` fields — deferred.** You cannot fill
+  them honestly without first building 86 enforcement points; what you get
+  otherwise is 86 `TODO` values, which is *strictly worse than a blank*. The
+  blank is honest about non-coverage; the TODO is a promise. This is the exact
+  failure ADR-127's own `review_trigger` names.
+- **Adversarial governance evals — killed.** A corpus of "user pressures the
+  agent to skip a gate" scores refusal as the pass condition, while this
+  package's documented authority model says the user decides. An eval asserting
+  "the agent must refuse when the user says no" would declare `agent-authority`
+  a security failure. The narrower question — does the enforcement mechanism
+  return non-zero — is already answerable per rule.
+- **A governed-writes lint — killed as the wrong layer.** A static scan for
+  `fs.writeFile` against protected paths is simultaneously too weak
+  (`child_process.exec('… > file')` walks past it) and too strong (fixture setup
+  trips it). Same reasoning as ADR-127 Decision 5: a gate covering one route of
+  several, while reading as coverage, is theatre. The type system is the right
+  layer if this is ever worth closing.
+
+**11. Tamper-evident chains — deferred with the disagreement recorded, not
+resolved by fiat.** Round 1 argued a hash chain adds nothing Git does not
+already provide, and that the external `git merge-base` line-prefix witness does
+all the work. Round 2 found the hole in that: a line-prefix witness catches
+**tail truncation** and does **not** catch **mid-sequence deletion** — dropping
+entries 50–90 out of the middle leaves a diff that is not a prefix violation and
+reads as an ordinary divergent branch. Neither round produced the number that
+settles it, which is how often a ledger surface is edited by someone other than
+the maintainer. That number is the revisit condition in this ADR's frontmatter.
+
+## Consequences
+
+**Good.** Machine-re-verifiable claims went from **0 to 10** of 27 backed. The
+form found a real defect on its first CI run — the over-counted feasibility
+entry — which is the gate doing the job it was built for, on itself. The risk
+classifier caught its own docs-exemption bug through a test before its report
+was published. Both are the intended shape: the instrument fails visibly rather
+than reporting a comfortable number.
+
+**Cost.** 17 of 27 backed claims still rest on pointers and cannot re-derive
+themselves; that is now stated on the proof page rather than implied away. The
+`exec:` allowlist is a maintenance surface — a renamed script silently drops a
+claim from re-verification to static-only, and nothing yet detects that
+downgrade.
+
+**Accepted limits, stated rather than discovered later.** The allowlist only
+covers commands whose exit code *is* the verdict; nothing about this form helps
+a claim resting on a paid benchmark. The path classifier sees paths, not intent:
+a dangerous change in a file it does not know about classifies as `none`, and
+the class list is a judgement that will need revisiting as the tree moves. The
+shadow report measures what *would* have escalated, which is not the same as
+what *should* have — it cannot tell whether those 11 merges were actually
+handled carelessly, only that they were in the class.
+
+## Alternatives
+
+- **Build `exec:` for all 26 claims.** Not possible, and the attempt would have
+  produced fake pointers for benchmark claims. 10 honest re-verifications beat
+  26 that only look uniform.
+- **Ship the non-declinable escalation in this PR.** Rejected on sequencing: the
+  measurement justifies it, but an authority-model trade deserves a decision
+  record a reader can find, not a paragraph inside a measurement PR.
+- **Let `exec:` run locally too.** Rejected: "commands execute in the repository
+  root with full filesystem access" is a property to confine, not to trust, and
+  a consumer's checkout has no business re-running this package's evidence.
+- **A regex allowlist.** Rejected — the reason the tuple form exists.
+- **Skip the prevented-failure table as marketing.** Rejected: the format names
+  failure modes rather than features, which is a better description of what this
+  package does than any feature list, and the ledger gate makes it falsifiable.
+
+## References
+
+- `internal/reports/exec-evidence-feasibility.json` — the pre-registered
+  measurement, its correction, and the built outcome.
+- `internal/reports/risk-escalation-shadow.json` — 11 of 99 first-parent merges,
+  against a threshold fixed before the first read.
+- `src/scripts/_lib/exec_evidence.ts`, `src/scripts/_lib/risk_paths.ts`.
+- `tests/scripts/exec_evidence.test.ts` — the abuse cases for the allowlist and
+  the argument hardening.
+- ADR-127 — the enforcement-resolution decision this continues.

package/docs/decisions/INDEX.md

@@ -127,6 +127,11 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-121](ADR-121-knowledge-sensitivity-classes.md) | Knowledge Sensitivity Classes | accepted | 2026-07-12 | — |
 | [ADR-122](ADR-122-adversarial-verification-council.md) | Adversarial Verification Council | accepted | 2026-07-14 | — |
 | [ADR-123](ADR-123-runtime-security-scope-and-spawn-hardening.md) | Runtime Security Scope And Spawn Hardening | accepted | 2026-07-20 | — |
+| [ADR-124](ADR-124-embedded-engine-doctrine.md) | Embedded Engine Doctrine | accepted | 2026-07-23 | ADR-088 (engine-adoption interpretation only), ADR-094 (engine-adoption interpretation only) |
+| [ADR-125](ADR-125-doc-screenshot-anonymization.md) | Doc Screenshot Anonymization | accepted | 2026-07-23 | — |
+| [ADR-126](ADR-126-internet-reach-operator-tooling.md) | Internet Reach Operator Tooling | accepted | 2026-07-24 | — |
+| [ADR-127](ADR-127-enforcement-claims-must-resolve.md) | Enforcement Claims Must Resolve | accepted | 2026-07-25 | — |
+| [ADR-128](ADR-128-executable-evidence-and-measured-escalation.md) | Executable Evidence And Measured Escalation | accepted | 2026-07-25 | — |
 | [ADR-200](ADR-200-python-to-typescript-migration.md) | Python To Typescript Migration | accepted | 2026-06-11 | — |
 
 ## Unnumbered (legacy)
@@ -134,3 +139,19 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | # | Title | Status | Date | Supersedes |
 |---|---|---|---|---|
 | [ADR-rule-kernel-and-router](ADR-rule-kernel-and-router.md) | Rule Kernel And Router Roadmap Closure | accepted | 2026-05-06 | — |
+
+## Decision records outside this directory
+
+Scanned, not hand-listed. These files are titled `# ADR — …` and record a
+decision, but live elsewhere in the tree. They are indexed here so a decision
+cannot be unfindable merely because of where it was filed; their paths are
+unchanged and their inbound references still resolve.
+
+| File | Title | Status |
+|---|---|---|
+| `agents/settings/contexts/adr-always-budget-relief-strategy.md` | Always-Budget Relief Strategy (parked, reactivation-gated) | Decided |
+| `agents/settings/contexts/adr-always-rule-context-split-not-viable.md` | Splitting an Always-rule into rule + `load_context:` is not viable under Model (b) | Decided |
+| `agents/settings/contexts/adr-artifact-engagement.md` | Artefact-Engagement Telemetry | Decided |
+| `agents/settings/contexts/adr-auto-rule-consolidation.md` | Auto-Rule Consolidation (review-routing + transient-references pairs) | locked |
+| `agents/settings/contexts/adr-frugality-savings-baseline.md` | Frugality Canon Savings Baseline | Decided |
+| `agents/settings/contexts/adr-work-engine-rename.md` | Universal Execution Engine: rename `implement_ticket` → `work_engine` | Decided |