@event4u/agent-config 9.8.0 → 9.9.0

package/docs/decisions/ADR-123-runtime-security-scope-and-spawn-hardening.md

@@ -1,142 +0,0 @@
----
-adr: 123
-status: accepted
-date: 2026-07-20
-decision: runtime-security-scope-and-spawn-hardening
-supersedes: —
-superseded_by: —
-phase: road-to-runtime-security-hardening
-type: structural
----
-
-# ADR-123 — Runtime-security scope: harden subprocess spawn-env, keep behavioural enforcement out of scope
-
-- **Status:** Accepted (2026-07-20)
-- **Closes:** `agents/roadmaps/archive/road-to-runtime-security-hardening.md`
-- **Related:** `docs/threat-model.md` row (d) (lethal-trifecta); `src/rules/tool-safety.md` (Least Agency); `src/rules/lethal-trifecta-guard.md`; `src/rules/untrusted-input-defense.md`.
-
-## Context
-
-A user-supplied source-level analysis compared agent-config's security stack
-against an external reference plugin (referred to only as **Source A** per
-`source-confidentiality`; © the third party, all-rights-reserved — concept
-adoption only, no code/regex/prompt port). It surfaced two distinct things that
-were repeatedly conflated:
-
-1. **A real shipped bug.** `src/scripts/ai_council/clients.ts::_runSubprocess`
-   built its `spawnSync` options with no `env:` key, so every spawned provider
-   CLI (`codex` / `claude` / `gemini`) — and any `git` those CLIs invoke
-   internally — inherited the full parent `process.env`. An attacker-influenced
-   `GIT_EXTERNAL_DIFF` / `core.pager` / `NODE_OPTIONS` / `LD_PRELOAD` /
-   `DYLD_INSERT_LIBRARIES` in the parent environment is remote code execution
-   (CWE-426 untrusted search path, CWE-88 argument injection). This is our own
-   transport violating the Least-Agency its `tool-safety` rule preaches.
-
-2. **A proposed scope reversal.** The analysis argued that because
-   `injection_scan_hook.ts` already scans **inbound** tool responses, the
-   threat-model's "runtime enforcement out of scope" decision (row (d)) is
-   already void, so we should also scan **outbound** — the content the agent
-   writes — with a pattern guard, a turn-diff baseline, and eventually an LLM
-   diff-review.
-
-A two-round council (2026-07-20, anthropic/claude-sonnet-4-5 + openai/gpt-4o)
-was decisive: round 1 leaned toward building the outbound guard; **round 2 both
-members pivoted skeptical** on the load-bearing distinction below.
-
-## Decision
-
-**1. Fix the spawn-env RCE (accepted, shipped in this roadmap).** A shared
-`src/scripts/_lib/spawn_env.ts::hardenedSpawnEnv(overrides?)` scrubs the
-code-execution-injection env families **by family, not by allowlist** — the
-provider CLIs legitimately need arbitrary env (API keys, config paths), so an
-allowlist would break them and rot; deny-by-family removes the known vectors
-(dynamic-loader `LD_*`/`DYLD_*`/`GCONV_PATH`, git `*_COMMAND`/`GIT_EXTERNAL_DIFF`/
-`GIT_SSH_COMMAND`/`PAGER`, runtime hooks `NODE_OPTIONS`/`BASH_ENV`/`ENV`/
-`PYTHON*`/`PERL5*`/`RUBYOPT`, and `IFS`) and preserves everything else. It is
-wired into the council transport and the two consumer-runtime hook spawn sites
-(`roadmap_progress_hook`, `hot_context_hook`), and guarded by a falsifiable
-regression test (proven RED without the fix — 8 vectors leaked into the child —
-GREEN with it).
-
-**2. Input sanitization ≠ runtime behavioural enforcement — row (d) stands.**
-The inbound `injection_scan_hook` is **self-defence**: it hardens AC's own
-handling of data it *receives* from external tools. It does **not** commit AC to
-*governing what the agent writes*. An outbound command guard requires
-interpreting intent from content (`rm -rf ./build` vs `rm -rf /`) — that is a
-runtime **enforcement** layer, a categorically different mechanism, and the one
-threat-model row (d) places out of scope. AC ships the *rules*
-(`lethal-trifecta-guard`, `untrusted-input-defense`, `tool-safety`); the
-consumer's tool-execution layer is the enforcement boundary. The inbound/outbound
-"asymmetry" is a defensible separation of concerns, not security theatre.
-
-**3. The outbound guard / turn-diff baseline / LLM diff-review are deferred, not
-rejected.** They remain `## Blockers` on the roadmap with a `revisit-if`: a real
-outbound-injection incident, a consumer demand signal, or utilization evidence —
-at which point they must also pass the six-question complexity budget
-(`artifact-drafting-protocol-mechanics` § Complexity budget), given PR #983 just
-consolidated surface and `surface-consolidation-restraint` freezes new modes
-pending the first external adopter. This ADR records the deferral so the
-decision is surfaced, not silently dropped (`decision-revisit-gate`).
-
-**4. Rejected:** a consumer-supplied-pattern ReDoS/trust-framing layer (Source A
-P5) — `security_lint.ts` has no consumer-pattern surface, so guarding it would
-build a defence for a feature that does not exist. Global env/pattern allowlists
-are also rejected: per-file pragma containment (`security_lint.ts`) only.
-
-## Consequences
-
-- The council transport and consumer-runtime hooks can no longer be turned into
-  an RCE vector by a poisoned parent environment; the fix is falsifiably tested.
-- `docs/threat-model.md` gains a row for the (now-mitigated)
-  subprocess-env-inheritance vector, and row (d)'s "no additional mitigation
-  planned" cell cites this ADR for the input-sanitization-vs-enforcement
-  distinction and the deferred-guard decision.
-- AC's security posture stays **authoring-time rules + input hygiene + our own
-  Least-Agency spawn discipline** — it does not become a runtime sandbox
-  supervising every agent tool call.
-- Maintainer-only CI/git-helper spawn sites (~15) are a deferred mechanical
-  sweep (`maintainer-ci-spawn-sweep` blocker): they run in trusted CI with lower
-  attacker-control of the environment.
-
-## Alternatives considered
-
-- **Complete the runtime layer (build the outbound guard now).** Council round 1
-  position. Rejected in round 2: conflates input sanitization with behavioural
-  enforcement; adds net-new enforcement surface with a false-positive burden,
-  right after a consolidation roadmap, with no demand signal.
-- **Delete `injection_scan_hook.ts` for symmetry.** Architecturally consistent
-  but operationally worse — inbound sanitization is legitimate self-defence and
-  costs nothing to keep.
-- **Env allowlist instead of deny-by-family.** Rejected — would strip env the
-  provider CLIs need and rot as new good vars appear.
-
-## Follow-up (2026-07-21) — `road-to-spawn-env-completion`
-
-The 9.6.0 external review reproduced a working exploit against the fix this ADR
-shipped: `GIT_CONFIG_COUNT` / `GIT_CONFIG_KEY_<n>` / `GIT_CONFIG_VALUE_<n>` (and
-`GIT_CONFIG_GLOBAL` / `_SYSTEM`) survived the deny-by-family scrub — the
-`GIT_*_COMMAND` family missed them (no `_COMMAND` suffix) — letting an attacker
-set arbitrary git config (`core.fsmonitor` runs shell on every `git status`,
-which the consumer-runtime hooks trigger). `GIT_ALTERNATE_OBJECT_DIRECTORIES`
-and `HOSTALIASES` also leaked. **Confirmed empirically (all 5) and closed:**
-`hardenedSpawnEnv` now denies the whole `GIT_CONFIG`/`GIT_CONFIG_*` family by
-prefix plus the two exact vars, with falsifiable test vectors (red without the
-fix, green with it).
-
-**`maintainer-ci-spawn-sweep` blocker — resolved by classification, not mass
-migration.** Rather than migrate ~15 low-risk maintainer/CI sites, all spawn
-sites are now classified in `docs/spawn-site-policy.md` (Consumer Runtime /
-Maintainer CLI / trusted CI / install-time). The consumer-runtime dispatcher
-(`hooks/dispatch_hook.ts`) — missed in PR #984 — now routes through
-`hardenedSpawnEnv`; the maintainer/CI/install sites are documented exempt with
-rationale (env is maintainer- or workflow-controlled, not attacker-influenced).
-
-**Secure-spawn lint — rejected (council 2026-07-21, claude-sonnet-4-5 +
-gpt-4o).** A CI lint forbidding raw spawn in runtime paths was proposed (P0 in
-the review) but rejected: it is net-new governance surface (a CI gate +
-allowlist + exemption-adjudication + false-positive triage), which the folded
-complexity-budget lock (PR #983) forbids — the lock text explicitly lists
-"linter". The "retires ad-hoc review" justification failed the retirement test
-(no such review gate exists to retire). `docs/spawn-site-policy.md` is the
-self-enforcing substitute: its completeness claim is checked by git-diff
-visibility at review time, not a build gate.

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

@@ -1,255 +0,0 @@
----
-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

@@ -1,131 +0,0 @@
----
-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`.