@event4u/agent-config 9.7.0 → 9.8.0

package/docs/contracts/subagent-boundary.md

@@ -43,6 +43,21 @@ the whole of its authority.
 - **Verify, never adopt blind** — a subagent return is evidence, not truth; the orchestrator verifies per [`delegation-policy`](../../src/rules/delegation-policy.md)'s Iron Law before adopting it.
 - **Tier-size the slice, not the agent** — dispatch at the slice's complexity, not the session's.
 - **Own the safety decision** — a Hard-Floor or egress action surfaced by a subagent is decided by the orchestrator + human, never executed by the subagent.
+- **Re-confirm; the subagent's confirmation does not count** — a destructive or irreversible mutation *proposed by a subagent* is subject to the same Hard Floor as one the orchestrator proposed, and the subagent's own "I checked, it's fine" does not satisfy the gate. Without this clause, delegation is a detour around it: ask a subagent, receive a blessing, act.
+- **Deliver the floor, do not assume it** — the floor reaches a worker because [`generate_subagent_floor.ts`](../../src/scripts/generate_subagent_floor.ts) writes it into every dispatch prompt and CI fails on drift.
+
+### Honest scope of the floor guarantee
+
+The invariant above — *a subagent cannot do what its parent may not* — is now
+**delivered** for subagents dispatched through this package's prompt templates:
+the floor is generated from the kernel rules and drift-gated. It was previously
+asserted here and carried by nothing; the brief schema, the spawn composer, and
+all eight prompt templates contained no floor text at all.
+
+What stays unproven, and is therefore not claimed: whether a subagent spawned by
+a host primitive outside these templates inherits any of it. That is a host
+property this package does not control and does not test. A contract that
+quietly covered it would repeat the exact defect this section exists to close.
 
 ## Failure modes
 

package/docs/customization.md

@@ -473,6 +473,14 @@ defaults"* above). The cascade is **per-file** by basename — the
 deepest existing `agents/<kind>/<name>.md` wins; the rest are silently
 shadowed.
 
+**One exception, and it is not silent.** Kernel and `tier: safety-floor`
+rules sit outside the cascade: a `Mode: replace` override on one is
+refused and reported, and a `Mode: extend` (a tightening) needs a
+registered entry in `agents/overrides/kernel-exceptions.yml`. See
+[`override-system`](../src/agent-src/contexts/override-system.md)
+§ *The non-overridable class* — including its stated limit, since the
+class is a norm with a partial gate, not a proof.
+
 | Subdir | Cascade? | User-global allowed? | Why |
 |---|---|---|---|
 | `agents/overrides/` | ✅ Yes — deepest wins by basename. | ✅ Yes — weakest layer. | Personal developer overrides. |
@@ -489,10 +497,13 @@ fallback). Files under `~/.event4u/agent-config/agents/settings/contexts/` or
 project-shaped and must not leak across projects.
 
 The resolver lives at
-[`scripts/_lib/agents_overlay.py`](../src/scripts/_lib/agents_overlay.py)
-and is enforced by `scripts/check_overlay_cascade_subdirs.py` — drift
-between the code constants (`CASCADE_ELIGIBLE_KINDS`,
+[`scripts/_lib/agents_overlay.ts`](../src/scripts/_lib/agents_overlay.ts)
+and is enforced by
+[`scripts/check_overlay_cascade_subdirs.ts`](../src/scripts/check_overlay_cascade_subdirs.ts)
+— drift between the code constants (`CASCADE_ELIGIBLE_KINDS`,
 `USER_GLOBAL_OVERLAY_KINDS`) and the table above breaks the build.
+(Both were `.py` before the ADR-200 TypeScript port; the old paths were
+cited here long after they were deleted.)
 
 ---
 

package/docs/decisions/ADR-016-installer-architecture.md

@@ -7,6 +7,8 @@ supersedes: —
 superseded_by: —
 phase: v2.x · monorepo-phase-3-typescript-installer
 type: prospective
+review_trigger: >-
+  When a consumer reports losing a local edit to a framework-authoritative file on update, OR when any framework file legitimately needs to move between the force-update and scaffold classes — the conflict-resolution half (skip | overwrite | merge) is the part under review, not the TypeScript choice
 ---
 
 # ADR-016 — TypeScript Installer Architecture

package/docs/decisions/ADR-088-no-external-runtime-federation.md

@@ -4,7 +4,7 @@ status: accepted
 date: 2026-06-11
 decision: no-external-runtime-federation
 supersedes: —
-superseded_by: —
+superseded_by: ADR-124 (engine-adoption interpretation only)
 phase: external-runtime-coexistence
 type: structural
 ---

package/docs/decisions/ADR-094-agent-memory-layer-removal.md

@@ -4,7 +4,7 @@ status: accepted
 date: 2026-06-14
 decision: agent-memory-layer-removal
 supersedes: —
-superseded_by: —
+superseded_by: ADR-124 (engine-adoption interpretation only)
 phase: memory-layer-cleanup
 type: structural
 ---

package/docs/decisions/ADR-109-subagent-v1-contract.md

@@ -7,6 +7,8 @@ supersedes: —
 superseded_by: —
 phase: road-to-final-state-and-market-readiness
 type: standing
+review_trigger: >-
+  When a host ships a spawn primitive whose memory-inheritance semantics are documented, OR when a dispatched subagent is observed taking an action the floor forbids
 ---
 
 # ADR-109 — The `subagent-v1` contract (new discovery category, default-off, static projection)

package/docs/decisions/ADR-110-discipline-profile-resolution-locus.md

@@ -7,6 +7,8 @@ supersedes: —
 superseded_by: —
 phase: road-to-discipline-profile-tiering
 type: standing
+review_trigger: >-
+  When a diff in a downstream-trust-boundary path (installer, provenance, kernel rules, spawn path) is found to have run under minimum discipline because the HOST was weak — host capability is only one axis, and diff risk is the missing one
 ---
 
 # ADR-110 — `discipline_profile` resolves at runtime (agent-in-the-loop); projection stays configuration-independent

package/docs/decisions/ADR-113-ci-native-release-label-trigger.md

@@ -112,9 +112,17 @@ maintainer approves the run once per release.
   on deploys, a single human checkpoint before a release's own CI even
   runs is arguably a feature, not friction.
 - `RELEASE_PR_TOKEN` (a fine-grained PAT or GitHub App installation
-  token with `contents: write` + `pull-requests: write` on this repo)
-  removes the approval requirement entirely — documented as the
-  zero-friction upgrade path in `release.yml`'s header comment. Adding
+  token with `contents: write` + `pull-requests: write` + `actions: write`
+  on this repo) removes the approval requirement entirely — documented as
+  the zero-friction upgrade path in `release.yml`'s header comment. The
+  `actions: write` scope ("Actions: read and write" on a fine-grained PAT,
+  or the classic `workflow` scope) is required by release.ts step 9's
+  explicit `gh workflow run` dispatch of the tag-triggered workflows
+  (release-guard / publish-npm / cloud-release); without it that dispatch
+  returns HTTP 403. As of 2026-07-21 that dispatch is **non-fatal** — the
+  release is already complete when it runs, and a PAT-pushed tag fires
+  those workflows on the push regardless — so a missing scope degrades to
+  a logged warning, never a failed-but-shipped release. Adding
   it is a maintainer action, not part of this ADR.
 
 ## Verified facts (not assumed)

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`.