@event4u/agent-config 9.6.0 → 9.8.0

package/docs/decisions/ADR-124-embedded-engine-doctrine.md

@@ -0,0 +1,255 @@
+---
+adr: 124
+status: accepted
+date: 2026-07-23
+decision: embedded-engine-doctrine
+supersedes: ADR-088 (engine-adoption interpretation only), ADR-094 (engine-adoption interpretation only)
+superseded_by: —
+phase: road-to-native-code-intelligence
+type: structural
+---
+
+# ADR-124 — Embedded-engine doctrine: this suite may own deterministic in-process engines; the service/daemon prohibition stands
+
+## Status
+
+**Accepted** · 2026-07-23. **Maintainer-directed reversal** of the
+engine-rejection *interpretation* accumulated across ADR-088, ADR-094 and the
+archived harvest-cycle REJECT records of 2026-06/07. The council ratification
+round reviewed the *boundary wording*, not the direction — the direction is a
+maintainer product decision: the prior councils optimized for scope discipline
+and, in doing so, systematically excluded a capability class (deterministic
+code/corpus intelligence) that competing suites ship as their headline
+feature. The ratification round ran 2026-07-23 (see References); its three
+convergent wording patches — the tightened `--watch` termination clause, the
+maintainer-approves-per-dep ladder note, and the "changes *what* the tool can
+answer, not just *how fast*" state-store test in § 6 — are folded in, and the
+ADR is accepted on that sealed wording.
+
+## Context
+
+### What the record actually prohibits (verified 2026-07-23)
+
+The "no runtime" identity rests on instruments whose literal scope is narrower
+than the posture they produced:
+
+1. **ADR-088** prohibits **cross-vendor runtime federation**: "agent-config
+   does not bridge to, or drive, external tool runtimes. It is a content suite
+   (skills, rules, commands) for AI coding tools — not a runtime coordinator."
+   It says nothing about whether this suite may run an in-process algorithm of
+   its own. The frequently-cited gloss "no runtime orchestration (work
+   stealing, load balancing)" is a harvest-cycle REJECT line (council,
+   2026-07-07) that *cites* ADR-088 — it is not ADR-088's text.
+2. **ADR-094** removed one specific companion package (Layer 2:
+   PostgreSQL + pgvector + MCP memory server + decay engine) because "its
+   PostgreSQL + MCP runtime contradicted the suite's 'no app runtime'
+   positioning." It is a removal record, not a forward-looking ban list.
+3. **Archived REJECT records** (council convergences, 2026-06 → 2026-07,
+   quoted inline per the transient-reference rule): the MCP deferred-rule
+   retrieval **server** ("council REJECT, 2026-07-07", three re-open
+   conditions); "SQLite memory *service*, vector clocks, distributed memory —
+   the second-brain verdict and Layer-2 sunset stand"; a web console ("no
+   runtime to monitor"); a browser daemon + compiled runtime ("compiled
+   runtime betrays no-runtime identity" — routed to `agent-ide-plugin`); an
+   in-process swarm/topology engine ("an in-process actor runtime is
+   identity-rejected").
+4. **`src/rules/external-code-graph-interop.md`** codified the resulting
+   ceiling: "This suite is an **orchestrator, not a competitor**: query the
+   existing index first … NEVER REBUILD WHAT THE INDEX ALREADY ANSWERS." This
+   is the single most on-point prior commitment against a native code-graph
+   engine — an active tier-2a rule, and it is amended by this ADR (§ 2).
+
+In practice these instruments were *interpreted* wider than written: a
+2026-07-23 inventory sweep across all roadmap dispositions (active, archive,
+later, skipped, stubs) found **44 engine-shaped rejects across ~30 cycles** —
+harvests of at least six external references (a code-graph suite, an
+orchestration runtime, a control-plane/enforcement suite, and three memory
+systems) adopted **protocol discipline only** and reflexively rejected every
+**engine**, including engines that are neither services nor daemons.
+
+### The precedent — read honestly
+
+**ADR-116** pre-decided SQLite FTS5 via `node:sqlite` — a persisted,
+incrementally-updated engine, in-process — as compatible with the Layer-2
+sunset: "no service, no always-on worker, zero npm dependency." Two facts keep
+this precedent honest rather than convenient:
+
+- **That engine was never built.** The activation path was re-resolved to a
+  hand-rolled stdlib BM25 + trigram prefilter (`_lib/lexical_index.ts`); only
+  the engine choice moved, per the ADR-116 amendment banner.
+- **Its compatibility argument rested on being a zero-npm-dep Node built-in.**
+  ADR-116 explicitly rejected `better-sqlite3` and a minisearch dependency
+  *for being npm deps*. It is therefore precedent for "embedded engine ≠
+  runtime" **in principle**, and **counter-precedent on the dependency axis**.
+  This ADR does its own work on that axis (§ 1, Class A) instead of borrowing
+  authority ADR-116 does not carry.
+
+### Dependency reality
+
+The package ships **13 runtime npm dependencies** today (fastify, commander,
+execa, tsx, zod, js-yaml, the MCP SDK, …). No package-wide "zero
+dependencies" commitment exists — the closest claim was a README bullet
+deliberately dropped before 2.2.0. The zero-dep virtue in ADR-061/ADR-116 is a
+*feature-level* stdlib preference, not a distribution-level promise. An engine
+dependency is therefore a **cost to justify per adoption**, not a broken vow.
+
+### The product goal has changed
+
+The maintainer directs: the suite should be able to natively own capability
+classes (deterministic code intelligence first) when owning them makes the
+package better, closes gaps and improves agent behavior — not merely defer to
+whatever index a consumer happens to ship.
+
+## Decision
+
+### 1. Three engine classes; the boundary moves, it does not vanish
+
+| Class | Definition | Verdict |
+|---|---|---|
+| **A — Embedded engine** | Deterministic, in-process, invoked-per-command, no resident process, no listening socket, no network in the build path; state only as gitignored, rebuildable build/index artifacts under the suite's own runtime dirs (`agents/runtime/state/`). **Termination clause (council patch, 2026-07-23): a Class-A engine terminates after command completion; in-memory state never spans CLI invocations** — a memory-only long-lived process that "never touches disk" is Class B regardless of its storage story. The sole exception is an explicit `--watch` flag on a stateless file-regeneration command where (a) the process lifecycle is bounded to file-system event observation, (b) **each regeneration cycle is a fresh Class-A invocation with no shared in-memory state between cycles**, and (c) the flag emits a first-launch notice that a long-running process started; any other persistent process (REPL, server, daemon, background worker) is Class B regardless of flag naming, and the `--watch` mode itself is a Class-B escalation under § 5. Implementation preference in order: Node built-ins / stdlib → exact-pinned pure-npm or WASM dependencies (admissible with a per-dependency justification in the adopting ADR — the justification states why a lighter dependency does not suffice, and the maintainer approves it in that ADR, not in a downstream feature PR) → native-compiled (node-gyp) deps only via an explicit per-dependency exception on the same terms. Every subprocess it spawns routes through `hardenedSpawnEnv()` per ADR-123 and `docs/spawn-site-policy.md`. | **ADOPTABLE.** This suite may build, fork, or vendor Class-A engines natively. |
+| **B — Resident service / daemon** | Anything with a lifecycle beyond one command: DB servers, MCP *servers* run as memory/retrieval backends, watchers, browser daemons, background workers, web consoles. (In-process actor runtimes/swarms are equally out of scope, but by the ADR-109 identity floor preserved in § 3 — not by this lifecycle definition; they can terminate within one command and are still excluded.) | **PROHIBITED in core**, unchanged. Route to `agent-ide-plugin` or a sibling package where genuinely needed. ADR-088/094 remain authoritative here. |
+| **C — Network/LLM-dependent build path** | Any index/graph/corpus *build* step that requires network or model calls (embedding pipelines included — ADR-061's "embeddings only on measured recall failure" remains the sole doorway). | **PROHIBITED by default**, unchanged. Query-time LLM use follows existing council/budget governance. |
+
+### 2. What is explicitly superseded
+
+- The **blanket engine-rejection interpretation** of ADR-088 and ADR-094.
+  Their literal text (no cross-vendor federation; Layer-2 removal) stands; any
+  archived REJECT that cites them against a Class-A engine is void and must be
+  re-evaluated (§ 4).
+- The **"orchestrator, not a competitor" ceiling** in
+  `external-code-graph-interop.md`. New wording: "orchestrator *first* —
+  query a consumer-shipped index when present and fresh; owner *where it
+  wins* — the suite's native engines cover the gap when none is shipped or
+  ours is measurably better." Interop behavior toward existing indexes is
+  unchanged.
+
+### 3. What is explicitly NOT superseded
+
+- **Falsifiability-first.** Every native engine ships **default-off**,
+  activates via tripwire or explicit setting, and earns default-on only
+  through a pre-registered benchmark with an honest-null publication path.
+  The evidence gates now govern *defaults*, no longer *existence*.
+- Claims Ledger, budget/spend gates, minimal-safe-diff, source
+  confidentiality, and the security posture (ADR-123 spawn hardening applies
+  to every engine subprocess; the no-network floor applies to every build
+  path).
+- The `agent-ide-plugin` routing for genuinely runtime-shaped capability.
+- ADR-109's no-runtime identity floor for subagent artifacts (no daemon, no
+  auto-write, no in-process swarm, no dispatch we enforce) — a command-invoked,
+  non-dispatching engine does not touch it.
+
+### 4. Mandatory re-evaluation sweep
+
+Every engine-shaped REJECT recorded 2026-06-01 → 2026-07-22 is re-classified
+A/B/C. Class-A rejects are re-opened as candidates (adoption still demand- and
+benchmark-gated); Class-B/C rejects are re-affirmed with the class cited. The
+population was inventoried on 2026-07-23 (44 entries); the classification
+table is committed as `docs/decisions/engine-reclassification-2026-07.md` by
+the implementing roadmap — no silent re-openings, no silent re-affirmations.
+
+### 5. Extension clause
+
+Opening Class B (e.g., a resident index server for very large fleets) requires
+its own ADR with: a named consumer demand signal, a measured Class-A failure
+(the embedded engine demonstrably cannot serve the need), and a security
+review under ADR-123. This clause exists so the next escalation is a decision,
+not a drift.
+
+### 6. Contract reconciliation — obligations this ADR creates
+
+The doctrine is not landed until the published claims agree with it. The
+implementing roadmap carries, in the same change-set as the first engine:
+
+- **`docs/contracts/no-runtime-boundary.md`** — the "Cross-session persistent
+  state stores" prohibition row gains an explicit carve-out: *gitignored,
+  deterministic, rebuildable build/index artifacts under
+  `agents/runtime/state/` are build outputs, not state stores* (they carry no
+  authority, are reproducible from the working tree, and are never
+  auto-written memory). One-shot subprocess spawning is already sanctioned by
+  the contract's Allowed table; daemons remain prohibited. **State-store test
+  (council ratification patch): if deleting the artifact changes *what* the
+  tool can answer rather than only *how fast* it answers, it is a state store,
+  not a build artifact — even if deterministically rebuildable.** A code-graph
+  cache passes the test (deleting it only slows the next query; the answer is
+  identical, recomputed from source); a learned index that enables query
+  semantics absent from the source tree (vector/embedding search) fails it and
+  stays Class C.
+- **`docs/comparison.yaml` row 1** — "no state database" is reworded to "no
+  resident database or service; deterministic, rebuildable file indexes only",
+  so the machine-checked claim stays true rather than quietly weakening.
+- **`src/rules/external-code-graph-interop.md`** — ceiling sentence amended
+  per § 2.
+- **Config-surface guard alignment** — a planned no-runtime config-surface
+  guard (parked in a later-disposition roadmap) denylists `vector`/`daemon`/
+  `decay`/`pgvector` keys and `setInterval`/`setTimeout` outside dev tooling.
+  Its denylist must except Class-A engine surfaces when it lands, or Class-A
+  engines will fail CI after this doctrine flips; this ADR is the anchor that
+  guard must cite.
+
+## Consequences
+
+- The suite may natively own: code-graph extraction/query (first instance —
+  WASM tree-sitter, Class A), lexical/FTS index engines (in-principle
+  precedent: ADR-116, with the honest reading above), deterministic
+  clustering/analysis over its own graph outputs, and comparable future
+  engines — each behind the § 3 gates.
+- **Sequencing rule:** no second native engine starts before the first has a
+  published benchmark verdict. The § 4 table is the queue, not a starting gun.
+- Positioning language changes from "no engines, governance only" to "no
+  *resident runtime*; deterministic embedded intelligence is in scope."
+  README/docs claims still bind to bench rows via the Claims Ledger.
+- **Named cost:** the first engine introduces parser-class runtime
+  dependencies (exact-pinned WASM). That breaks the feature-level stdlib
+  pattern ADR-061/116 prize — accepted deliberately, justified per dependency
+  in the adopting artifact, never silently.
+- **Named risk:** scope-dilution pressure on a single-maintainer package with
+  a live adoption gap. Mitigation is structural, not aspirational — the § 3
+  gates, the sequencing rule, and the § 4 table as the only intake path for
+  further engines.
+
+## Alternatives considered
+
+- **Keep the orchestrator-only posture** — rejected by maintainer directive:
+  it structurally cedes the headline capability class to peer suites and makes
+  the interop rule a promise with no machine behind it when consumers ship no
+  index (the common case).
+- **Repeal ADR-088/094 outright** — rejected: their literal scope
+  (cross-vendor federation; resident memory runtime) is correct and keeps the
+  differentiation that a reversal must not destroy.
+- **Class-A via native node-gyp bindings** — rejected: perpetual
+  consumer-install failure tax on a solo-maintainer package; WASM carries the
+  same fidelity without the toolchain.
+
+## References
+
+- ADR-061 (engine-fork ban; embeddings doorway) · ADR-088 (no external-runtime
+  federation) · ADR-094 (Layer-2 removal) · ADR-109 (subagent contract,
+  no-runtime identity floor) · ADR-116 (FTS5 pre-decision + amendment) ·
+  ADR-123 (spawn hardening).
+- `docs/contracts/no-runtime-boundary.md` · `docs/comparison.yaml` ·
+  `docs/spawn-site-policy.md` · `src/rules/external-code-graph-interop.md`.
+- Pre-landing adversarial council review: 2026-07-23, debate mode, 2 rounds,
+  members claude-sonnet-4-5 (Anthropic) + gpt-4o (OpenAI). Convergence:
+  A/B/C taxonomy well-drawn; the rebuildable-build-artifact carve-out judged
+  honest (deterministic from source, no runtime decisions recorded, byte-stable
+  rebuild) and categorically distinct from a state store; code-graph confirmed
+  as the correct first engine (retriever too incremental, policy evaluator
+  needs its predicate language designed first); benchmark thresholds sound.
+  Adopted patches: the Class-A termination clause (§ 1) and the benchmark
+  confound controls (implementing roadmap, Phase 5). A round-1 proposal to
+  block engine *construction* on an external adoption signal was rebutted by
+  both members in round 2 (capability-before-adoption causality; the engine is
+  the differentiation the launch story needs) — the adopted middle path is the
+  bench-as-launch-story inversion plus the existing default-off gates.
+- Council ratification round on wording: 2026-07-23, debate mode, 1 round,
+  members claude-sonnet-4-5 (Anthropic, verdict FLAG-with-patches) + gpt-4o
+  (OpenAI, verdict RATIFY-with-patches). Both converged on three wording
+  patches, all folded in on acceptance: (1) the `--watch` termination clause
+  now requires each regeneration cycle to be a fresh Class-A invocation with
+  no shared in-memory state (§ 1); (2) the dependency ladder names the
+  maintainer as the per-dep approver in the adopting ADR, not a downstream PR
+  (§ 1); (3) the state-store test — "changes *what* the tool can answer, not
+  just *how fast*" — is added to the § 6 no-runtime-boundary carve-out, which
+  explicitly keeps vector/embedding indexes on the Class-C side. No member
+  flagged the direction; the round sealed the wording and the ADR is accepted
+  on it.

package/docs/decisions/ADR-125-doc-screenshot-anonymization.md

@@ -0,0 +1,131 @@
+---
+adr: 125
+status: accepted
+date: 2026-07-23
+decision: doc-screenshot-anonymization
+supersedes: —
+superseded_by: —
+phase: road-to-doc-screenshot-anonymization
+type: structural
+---
+
+# ADR-125 — Doc-screenshot anonymization: human-gated, capture-delegated, detection-as-helper
+
+- **Status:** Accepted (2026-07-23)
+- **Closes:** `agents/roadmaps/road-to-doc-screenshot-anonymization.md`
+- **Related:** `src/rules/doc-screenshot-hygiene.md`; `src/skills/screenshot-hygiene/SKILL.md`; `src/rules/non-destructive-by-default.md` (the egress Hard Floor this routes into); `src/rules/domain-safety-pii.md` (text-surface sibling); `src/rules/lethal-trifecta-guard.md`; `src/skills/image-analyser/SKILL.md` (detection helper); `src/skills/readme-writing/SKILL.md` (unrequested-screenshot check).
+
+## Context
+
+The maintainer wants agents to create screenshots for documentation when
+genuinely useful — e.g. when generating a Starlight docs site — and embed them,
+with a hard requirement: **sensitive data visible on a screenshot must be
+anonymized / pixelated before the screenshot ships.**
+
+A code sweep established the gap: the package has image *generation* skills and a
+Starlight docs path (`docs/media/` → `site/sync-docs.mjs` auto-copy/rewrite), but
+**no screenshot-capture discipline and no anonymization of sensitive content
+inside a captured screenshot.** `domain-safety-pii` scopes to text surfaces only
+(drafts / logs / exports / legal privilege); media governance
+(`media-governance-routing`, `image-likeness-and-rights`) scopes to *generated*-
+image rights/likeness. Neither covers redacting sensitive data inside a captured
+screenshot.
+
+An AI council debate (2026-07-23, anthropic/claude-sonnet-4-5 + openai/gpt-4o,
+2 rounds) surfaced the load-bearing tension: agents creating screenshots
+autonomously + a "must anonymize" security guarantee + imperfect detection are
+mutually constraining. Automated detection (OCR + pattern-match + allowlist)
+cannot *prove* a screenshot is safe — it misses semantic leaks (aggregate counts,
+real-vs-fake data tells, re-identification via name structure), and an allowlist
+of "known-fake data" degenerates into an unmaintainable cross-cultural dictionary
+and an identity-resolution hazard.
+
+## Decision
+
+Build the feature (the maintainer has decided *whether*; the council informed
+*how*), with these locked choices:
+
+1. **Capture is delegated to the host** (`claude-in-chrome` / Playwright). The
+   package ships NO bundled capture engine — respects the no-runtime-floor
+   doctrine (ADR-109 §7). The package owns only the anonymization + embedding
+   discipline.
+
+2. **Standalone rule + skill, not a "Surface 5" on `domain-safety-pii`.**
+   Screenshots are opaque binary artifacts requiring OCR/vision, not the
+   text-pattern surfaces `domain-safety-pii` contracts around. Bolting them on
+   would break that rule's scope contract.
+
+3. **Detection is a HELPER, never a CLEARANCE.** The automated OCR + pattern
+   pass flags candidate regions and pre-redacts to make review cheap; it never
+   certifies a screenshot as safe. **The gate is human confirmation** for
+   data-bearing screenshots.
+
+4. **Egress teeth via the kernel, not a new kernel rule.** A data-bearing
+   screenshot embedded into shipped docs is an *irreversible published egress*.
+   The rule's Iron Law routes that embed INTO the existing kernel
+   `non-destructive-by-default` Hard Floor (publish/commit already require
+   this-turn confirmation). This gives the gate real teeth **without** adding a
+   new `always`/kernel rule — which would demand an ADR-gated kernel-membership
+   re-run + 24 h soak and would fail the kernel cross-cutting criterion (the
+   concern is docs/media-scoped, not cross-cutting across all work). The rule
+   ships as `auto` tier-2a; its severity is borrowed from the kernel Hard Floor
+   it routes into. ("Route, don't rebuild.")
+
+5. **Conservative default:** uncertain / unresolved / cannot-confirm-safe →
+   redact-or-refuse, never ship-and-hope.
+
+6. **Terminal / CLI / IDE screenshots are forbidden.** They are the highest leak
+   vector (absolute local paths, env tokens) and least reliably OCR-able. Steer
+   to text code blocks with text redaction — cheaper and safer.
+
+7. **Redaction is a deterministic opaque box/blur** over flagged regions; reject
+   lossy provider inpaint (docs need visual accuracy). The redaction tool is
+   **optional / tool-agnostic** — `sharp` is a `site` dependency only, not a
+   package dependency; mandating it breaks framework-neutrality + no-runtime-
+   floor. Missing tool → STOP and hand off to the maintainer; never silently
+   downgrade the guarantee.
+
+8. **The identity allowlist is the maintainer's OWN public handles + a small
+   fake-data seed** (`screenshots.identity_allowlist`, default `[]`) — NOT a
+   global fake-data dictionary and NOT identity-resolution. Default: everything
+   is treated as sensitive unless a human decides or it matches the allowlist. A
+   public handle co-located with a real name does not whitelist the name.
+
+## Consequences
+
+- New `auto` tier-2a rule `doc-screenshot-hygiene` (obligation surface + taxonomy
+  + risk tiers) routing to a new `screenshot-hygiene` skill (the decide →
+  capture → detect → redact → audit → embed workflow + the human-gate checklist).
+- New `screenshots.*` config keys (allowlist + terminal-forbid policy + gate)
+  with conservative defaults.
+- `readme-writing` strengthens its unrequested-screenshot check for data-bearing
+  shots; illustrative/no-data docs screenshots are the reconciled exception.
+- The "must anonymize" requirement is honored as a **human-gated** guarantee,
+  not a false-confidence automated one — the failure mode the council flagged
+  (agent ships PII because the automated audit "passed") is structurally avoided.
+- Cost: agents cannot autonomously embed data-bearing screenshots; a human
+  confirmation is required. This friction is intentional and symmetric with the
+  irreversibility of the egress.
+
+## Alternatives considered
+
+- **New `always`/kernel rule (Anthropic Round 1).** Rejected: fails the kernel
+  cross-cutting criterion, and the ADR+24 h-soak gate is disproportionate. The
+  route-into-Hard-Floor synthesis delivers the same teeth without kernel churn.
+- **Fully automated redaction pipeline as the gate (OpenAI Round 1).** Rejected
+  as a *clearance*: detection can't prove safety; "audit passed" would license
+  agents to skip human review — the exact inversion the gate exists to prevent.
+  Kept only as a *helper* that flags + pre-redacts.
+- **Extend `domain-safety-pii` with Surface 5.** Rejected: breaks the text-
+  surface scope contract of that rule.
+- **Bundle a `sharp`-based capture+redaction engine.** Rejected: `sharp` is a
+  site-only dep; bundling breaks framework-neutrality + no-runtime-floor.
+- **"Don't build it at all" (Anthropic Round 1 core).** Out of scope — the
+  maintainer decided to build; the ADR records the safe *how*.
+
+## References
+
+- AI council debate 2026-07-23 (anthropic/claude-sonnet-4-5 + openai/gpt-4o,
+  2 rounds), inlined in `agents/roadmaps/road-to-doc-screenshot-anonymization.md`.
+- ADR-109 (no-runtime-floor doctrine); `src/rules/non-destructive-by-default.md`;
+  `docs/contracts/kernel-membership.md`; `docs/threat-model.md`.

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.