@event4u/agent-config 9.6.0 → 9.8.0

package/docs/benchmark.md

@@ -559,7 +559,7 @@ replication on a per-token-billed key.
 - Runner: `src/scripts/bench_ab_v2_run.ts --host codex` (checkpoint-resumable).
 - Roadmap: `agents/roadmaps/archive/road-to-opt-measurement-unblock.md` Phase 2.
 
-## adversarial-verification-council finding coverage — UNBACKED (pending corpus + run)
+## adversarial-verification-council finding coverage — HONEST NULL (resolved 2026-07-21)
 
 Pre-registered claim `adversarial-council-finding-coverage` (docs/CLAIMS.md,
 ADR-122): on the RESIDUAL defect pool — defects that survive a single strong
@@ -574,14 +574,38 @@ controversial-but-correct control.
   **AND** absolute >= +8 pp, **AND** panel FP not worse than baseline within
   noise — encoded + tested in
   [`src/scripts/_lib/adversarial_council_gate.ts`](../src/scripts/_lib/adversarial_council_gate.ts).
-- **Status: UNBACKED.** The corpus-validity gate BLOCKS the registered run: the
-  existing `internal/bench/orchestration/corpus/` was built for cross-vendor
-  *parity* (obvious, model-differentiating defects), not judge-survivable
-  residual subtleties, so a run on it would be a measurement artifact (the
-  council's Round-1 critique). Resolving the claim needs (1) a curated
-  judge-survivable-subtlety corpus with a published distribution, then (2) a
-  maintainer-gated paid cross-vendor run. Honest-null on that run keeps the
-  surface default-off permanently, like recursive-verification.
+- **Status: HONEST NULL (resolved 2026-07-21).** A curated judge-survivable
+  corpus was built (`internal/bench/adversarial-council/`: 12 planted-defect
+  fixtures across 4 subtlety classes + 3 controversial-but-correct clean
+  controls; subtlety distribution published; passed an independent validity
+  audit after one fixture was repaired). The registered cross-vendor run
+  (anthropic `claude-sonnet-4-5` + openai `gpt-4o`, spend-authorized) resolved
+  the claim NEGATIVE:
+
+  | quantity | value |
+  |---|--:|
+  | judge-passed residual pool | 5–7 defects (missed by both neutral passes) |
+  | single-skeptic residual recall | 0.60 |
+  | 2-vendor panel residual recall | 0.60 (**zero lift**) |
+  | single-skeptic FP on clean controls | 1.00 |
+  | panel FP on clean controls | 1.00 |
+
+  The second vendor's residual catches were a **strict subset** of the first's,
+  so the panel added no marginal coverage; both recall thresholds (+25% rel,
+  +8 pp abs) missed → **honest-null**. Under the adversarial-skeptic posture
+  both the single skeptic and the panel false-flagged **all three**
+  controversial-but-correct controls (100% FP) — the posture over-flags correct
+  code. Stable across two runs. Per the locked gate, the Mode 9 surface stays
+  **default-off permanently** (like recursive-verification). Reproducible
+  artifact: `internal/bench/adversarial-council/runs/`.
+- **Transport lesson.** The first run attempted via `council_cli run` was
+  REJECTED as a measurement artifact: that transport runs multi-round
+  peer-review with cross-member visibility and returns prose ("Round 2 …
+  Reviewer A"), which both violates the independent-skeptic requirement and
+  defeats JSON scoring. The valid run uses direct, independent per-vendor
+  client calls (`bench_adversarial_council.ts`) with a strict-JSON system
+  prompt and a deterministic, pre-validated scorer
+  (`adversarial_bench_score.ts` + its synthetic red/green test).
 
 
 ## Defect-finding: team vs self-review vs council (2026-07-20) — HONEST NULL (ceiling-limited) {#honest-null-defect}
@@ -622,3 +646,140 @@ defect-finding *quality/lift* claim binds; team mode stays documented as
 judge-survivable-subtlety corpus that breaks the recall ceiling, or (b) a new
 model generation. The worker-via-bundle delegate (roadmap Phase 3 Step 4) stays
 deferred — it re-opened only on a measured review lift, which did not occur.
+
+## Internet-reach prescriptions vs host-native web tools (2026-07-24) — HONEST NULL (capability), cost signal unregistered {#honest-null-reach}
+
+**Question (pre-registered before the run):** does a reach-prescription layer —
+`gh api` for repository metadata, a local feed parser, a keyless discussion-search
+API, `curl` + local HTML→text — beat the host's own web-search / web-fetch tools
+on credential-free dev-research tasks, and at what token cost? The layer was
+prototyped in gitignored scratch first, so both arms were real at scoring time.
+
+**Design.** 12 tasks × 2 arms (`native` = host web tools only; `reach` = the
+prototype prescriptions), 4 parallel subagents, arms judged independently on
+pre-declared acceptance evidence — no arm-vs-arm comparison at scoring time.
+Thresholds, verdict bands and the run protocol were committed **before** the run
+(`internal/bench/reach-vs-native/README.md`); the report is
+`internal/bench/reach-vs-native/VERDICT.md`, raw rows in `results.csv`.
+
+**Result — capability: NULL.** The native arm passed **12/12**. Under the
+pre-registered rule (reach wins only where native fails; **ties are native
+wins**) the reach arm scored **0 outright wins of 12** → band **`stop`**. Two
+reach failures were prescription defects (a 400-char excerpt cap; a `jq`
+projection dropping the release body), and repairing them **cannot** move the
+band: the native arm passed those tasks too, so a repaired reach arm scores a
+tie. Zero native failures ⇒ zero possible reach wins.
+
+**Consequence: no router skill shipped.** The `internet-reach` router was
+cancelled pre-authoring by its own Phase-0 gate. What did ship is the
+verdict-independent operator tooling — 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.
+
+**Honest bound.** The credential-free constraint (needed for reproducibility)
+structurally excluded the two cases where a reach advantage was hypothesized:
+video subtitles (backend absent → `untested`) and authenticated / rate-limited
+platform access (impossible in a keyless set). The null therefore reads narrowly:
+*on public, credential-free dev-research tasks, a reach prescription layer buys
+no capability the host does not already have.* It says nothing about gated-platform
+access. Testing that needs a credentialed task set with its own pre-registration.
+
+**Unregistered observation — cost, not capability.** On all 8 tasks both arms
+solved, the reach arm was cheaper: **3,070 vs 6,730 tokens (0.46×)**, largest
+gaps on repository metadata (0.26×) and discussion search (0.31×). The native
+arm's overhead was *discovery*: it repeatedly had to find the machine-readable
+endpoint the prescription already knows. This is recorded **outside** the
+decision — S0b was authored as a ≤1.5× guardrail, never a win condition, and
+promoting it to one after seeing the data would be the post-hoc rigging the bands
+exist to prevent. Acting on it requires a separate, cost-primary pre-registration
+(equal-evidence tasks, token cost as the primary metric, a stated minimum saving
+worth the maintenance burden).
+
+## Gated-platform reads (2026-07-25) — SHIP (3 channels), with a narrowed gap on one {#ship-gated-reach}
+
+**Question (pre-registered before the run):** on platforms the host's own web tools
+cannot reach at all, are credential-free prescriptions **reliable** enough to justify
+their maintenance weight — measured **per channel**, never aggregated?
+
+This is deliberately not the question the parent bench asked. The
+[internet-reach null](#honest-null-reach) measured whether a prescription layer beats
+native tools on credential-free dev research, answered **no** (0/12, band `stop`), and
+named its own bound: *"It says nothing about gated-platform access. Testing that needs
+a credentialed task set with its own pre-registration."* This run is that test —
+except it turned out **no credentials are needed**, which is itself the finding that
+made it worth running.
+
+**The capability gap is established, not assumed.** Measured the same session, first
+hand: `reddit.com` is refused at the domain level by the host's own tool (a
+client-side refusal, not a 403 from Reddit); `x.com/<user>/status/<id>` answers **HTTP
+402**; a YouTube watch page answers 200 with metadata and no transcript.
+
+**Design.** 6 tasks per channel with pre-declared acceptance evidence, each with a
+**native-arm control**, thresholds frozen before the run (≥5/6 ship · 3–4/6 park ·
+≤2/6 drop), one documented repair per task allowed, verdicts never aggregated.
+Pre-registration: `internal/bench/gated-reach/README.md`; rows and evidence:
+`internal/bench/gated-reach/results.md`.
+
+| Channel | reach | native | Verdict |
+|---|---|---|---|
+| `reddit` tier 1 — Atom text | **6/6** | 0/6 | **ship** |
+| `reddit` tier 2 — ranking + thread structure | **6/6** | 0/6 | **ship** — time-bounded |
+| `twitter-oembed` — single tweet | **6/6** | 2/6 | **ship** — narrowed gap, below |
+| `youtube-transcripts` | not run | — | **park** — unexercised (backend absent by design) |
+
+**Reddit is a real, unambiguous capability.** Post text, comment text with authors
+(147 feed entries on the test thread, 135 author-bearing), and — via server-rendered
+HTML — **comment scores and reply nesting** (134 comments across 7 depth levels,
+scores cross-checked against the rendered page). Native scores 0/6 by construction:
+there is no native path to a domain the host refuses. The rate limiting that makes
+this fragile is solved with **no new code** — `curl --retry 8 --retry-max-time 110`
+measured 5/5 against 2/6 without it, because curl treats 429 as retryable and backs
+off exponentially when `--retry-delay` is omitted.
+
+**Tier 2 ships with an expiry, not a promise.** Reddit announced a login requirement
+for the server-rendered interface on 2026-06-30 and withdrew its earlier commitment to
+keep it available. Logged-out access still worked on 2026-07-25. It therefore ships
+with a kill-switch keyed on an **observed** login wall — never on the announcement —
+and with tier 1 as the permanent fallback. Degradation is a documented output
+(`login_wall: true`, "ranking unavailable"), because presenting unranked text as
+ranked is the one failure mode here that produces wrong conclusions rather than a
+missing answer.
+
+**The control rule fired, and the Twitter story is narrower than its 6/6.** The first
+task set used the most-quoted tweets in existence; native scored **5/6** on them — not
+by reading `x.com`, but because a canonical tweet's text is reproduced everywhere.
+Those five tasks were **removed and replaced** per the pre-registered control rule.
+On five genuinely obscure tweets native dropped to **2/6**, and one of its two
+"passes" came from the author's Threads and Mastodon cross-posts rather than Twitter.
+Where it failed it failed usefully badly: on one tweet it produced a paraphrase and a
+**confidently wrong month**, and it cannot distinguish a deleted tweet from a live one
+(both answer 402). So the honest reading of Twitter's 6/6 is: *the channel is reliable,
+and the gap it closes is narrow* — for any tweet discussed anywhere, native search
+already recovers the content; the channel earns its place on the case where a specific
+URL is in hand and nothing mirrors it.
+
+**A bench limitation, published rather than engineered away.** The control rule says a
+native pass means the task was mis-scoped, so the two native-passed Twitter tasks
+should have been replaced again. They were not, and the reason is structural: every
+tweet-sourcing channel available to a host that cannot read Twitter — HN links, Reddit
+links, search — selects for tweets that *were* discussed publicly, which is exactly the
+population native search recovers. Sourcing an undiscussed tweet requires the access
+this bench exists because we lack. The 6/6 stands on the frozen threshold; the caveat
+is recorded here so nobody later reads it as "six things only this channel can do".
+
+**YouTube is parked, not scored.** `yt-dlp` is absent and the package never
+auto-installs. Per the pre-registered unexercised rule, a channel that cannot be
+exercised cannot reach ship and is not counted as a drop — an uninstalled tool is a
+fact about this machine, not about the channel. What did ship for it is the readiness
+check that closes the blind spot the parent bench left open: a passing `yt-dlp
+--version` does **not** imply extraction works, because full YouTube support needs an
+external JS runtime, so the doctor inspects the yt-dlp config semantically and reports
+a distinct `not-ready` state with an idempotent fix command.
+
+**Three prescription defects were found by executing the prescriptions verbatim** —
+none would have been caught by review: a single HTML-entity decode pass leaves
+`&mdash;` in tweet text; a missing `-f` makes a deleted tweet answer **exit 0 with
+3,663 bytes of error HTML** that a caller reads as success; and a dropped `-L` makes
+the oEmbed endpoint answer 301 with an empty body, which looks like a dead service.
+All three are fixed and documented as load-bearing in
+[`docs/guides/gated-platform-reads.md`](guides/gated-platform-reads.md).

package/docs/catalog.md

@@ -1,13 +1,13 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **673 public artefacts** shipped by
+Consumer-facing catalog of all **678 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
 > **Regenerate:** `./scripts-run src/scripts/generate_index`
 > Auto-generated — do not edit manually.
 
-## Skills (278)
+## Skills (281)
 
 > **Behavioural-eval coverage is measured, not implied.** A skill is
 > behaviourally evaluated only if it ships `evals/evals.json`; most do
@@ -61,6 +61,7 @@ are excluded.
 | skill | [`character-consistency`](../dist/agent-src/skills/character-consistency/SKILL.md) | official | Use when a character must stay visually identical across AI video scenes — locks identity tokens (silhouette, palette, wardrobe, prop) in JSON. Triggers 'character lock', 'same character'. |
 | skill | [`check-refs`](../dist/agent-src/skills/check-refs/SKILL.md) | official | Use when verifying cross-references between skills, rules, commands, guidelines, and context documents are not broken after edits, renames, or deletions. |
 | skill | [`churn-prevention`](../dist/agent-src/skills/churn-prevention/SKILL.md) | official | Use when designing churn defence — health-score signals, churn-cause split (involuntary / value / relationship / fit), early-warning loop. Triggers on 'why are accounts leaving'. |
+| skill | [`code-intelligence`](../dist/agent-src/skills/code-intelligence/SKILL.md) | official | Route codebase-structure questions (who calls X, where used, what imports, change-impact) to a code-graph first, grep fallback. Triggers 'who calls', 'where is this used', 'call graph'. |
 | skill | [`code-refactoring`](../dist/agent-src/skills/code-refactoring/SKILL.md) | official | Use when the user says 'refactor this', 'rename class', or 'move method'. Safely refactors code in any language — finds all callers, updates downstream dependencies, verifies via quality tools. |
 | skill | [`code-review`](../dist/agent-src/skills/code-review/SKILL.md) | official | Use when the user says \"review this\", \"check my code\", or wants feedback on changes. Reviews for correctness, quality, security, and coding standards. |
 | skill | [`command-routing`](../dist/agent-src/skills/command-routing/SKILL.md) | official | Use when the user invokes a slash command like /create-pr, /commit, /fix-ci, or pastes command file content — routes to the right command with context inference and GitHub API patterns. |
@@ -124,6 +125,7 @@ are excluded.
 | skill | [`frontend-render-security`](../dist/agent-src/skills/frontend-render-security/SKILL.md) | official | Writing/reviewing client-side UI (React/Vue/vanilla) — insecure-render + client-trust gaps AI ships: XSS via innerHTML, client secrets, client-only auth, CORS wildcard, token in localStorage |
 | skill | [`fundraising-narrative`](../dist/agent-src/skills/fundraising-narrative/SKILL.md) | official | Use when shaping a capital-raise pitch — why-now / why-us / why-this framing, market-size reasoning, traction-story construction. Triggers on 'tighten the pitch', 'why-now is weak'. |
 | skill | [`funnel-analysis`](../dist/agent-src/skills/funnel-analysis/SKILL.md) | official | Use when diagnosing where a SaaS or product funnel leaks — visitor → signup → activation → paid → retained — channel-agnostic, conversion-rate-driven. |
+| skill | [`gated-reach`](../dist/agent-src/skills/gated-reach/SKILL.md) | official | Read a Reddit thread or single tweet the host cannot fetch — 'what does this Reddit thread say', 'top comment on this post', 'what does this tweet say' — when reddit.com is refused or x.com 402s. |
 | skill | [`git-workflow`](../dist/agent-src/skills/git-workflow/SKILL.md) | official | Use when working with Git — branch naming, commit messages, PR creation, rebasing, or the code review process — even when the user says 'push this' or 'merge the branch' without naming Git. |
 | skill | [`github-ci`](../dist/agent-src/skills/github-ci/SKILL.md) | official | Use when working with GitHub Actions — workflow YAML, quality gates, test matrices, deployment triggers, reusable workflows — even when the user just says 'my CI is failing' or 'add a check'. |
 | skill | [`grafana`](../dist/agent-src/skills/grafana/SKILL.md) | official | Use when working with Grafana — dashboards, Loki LogQL queries, alerting rules, monitoring panels — even when the user just says 'build me a dashboard' or 'query the logs' without naming Grafana. |
@@ -256,6 +258,7 @@ are excluded.
 | skill | [`runway-cognition`](../dist/agent-src/skills/runway-cognition/SKILL.md) | official | Use when reasoning about cash runway — burn shape, fundraise triggers, layoff-vs-cut-vs-grow decisions. Triggers on 'how long do we have', 'should we raise', 'cut or grow'. |
 | skill | [`scenario-modeling`](../dist/agent-src/skills/scenario-modeling/SKILL.md) | official | Use when constructing base / upside / downside scenarios — three-statement modeling, sensitivity analysis, optionality reasoning. Triggers on 'model the scenarios', 'what if growth halves'. |
 | skill | [`scene-expander`](../dist/agent-src/skills/scene-expander/SKILL.md) | official | Use when expanding a one-line idea into the 12-block Cinematic Scene Blueprint — provider-agnostic, includes optional dialogue + ambient. Triggers 'expand this scene', 'blueprint for X'. |
+| skill | [`screenshot-hygiene`](../dist/agent-src/skills/screenshot-hygiene/SKILL.md) | official | Use when creating and embedding a documentation screenshot — detect and redact sensitive data, human-gate data-bearing shots before ship. Triggers 'screenshot for docs', 'screenshot admin panel'. |
 | skill | [`script-writing`](../dist/agent-src/skills/script-writing/SKILL.md) | official | Use when adding or editing any script under `scripts/` — `--quiet`, `_lib/script_output`, silent Taskfile wiring, Iron-Law carve-outs; fires on 'add a check script for X'. |
 | skill | [`secrets-management`](../dist/agent-src/skills/secrets-management/SKILL.md) | official | Use when picking a secrets store, designing rotation, or wiring scanning gates — multi-cloud (Vault, AWS, Azure, GCP), CI, and Kubernetes — decision framework, provider deep-dives externalized. |
 | skill | [`security`](../dist/agent-src/skills/security/SKILL.md) | official | Use when applying security best practices — authentication, authorization, CSRF protection, input sanitization, rate limiting, or secure coding — stack-agnostic. |
@@ -306,7 +309,7 @@ are excluded.
 | skill | [`wireframe`](../dist/agent-src/skills/wireframe/SKILL.md) | official | Explore a flow or layout with 3+ disposable lo-fi greyscale wireframes on a named axis, before any hi-fi work. Use when the user wants to sketch directions or explore structure. |
 | skill | [`worktree-lifecycle`](../dist/agent-src/skills/worktree-lifecycle/SKILL.md) | official | Use when governing a worktree across its whole life — scope-lock declaration, merge-readiness status, scoped verification, and safe cleanup that refuses while unique unmerged commits exist. |
 
-## Rules (104)
+## Rules (106)
 
 | kind | name | type | description |
 |---|---|---|---|
@@ -337,6 +340,7 @@ are excluded.
 | rule | [`design-fidelity`](../dist/agent-src/rules/design-fidelity.md) | auto | A provided prototype/mockup/design system is the spec — build 1:1; never swap fonts, controls, or layout unconfirmed |
 | rule | [`devcontainer-routing`](../dist/agent-src/rules/devcontainer-routing.md) | auto | Wiring DevContainers/Codespaces (devcontainer.json, features, ports) — route to the devcontainer skill |
 | rule | [`direct-answers`](../dist/agent-src/rules/direct-answers.md) | always | Always — direct, unembellished answers. No flattery, no invented facts (verify load-bearing claims, otherwise ask). Emojis only as functional markers. Brevity is the default. |
+| rule | [`doc-screenshot-hygiene`](../dist/agent-src/rules/doc-screenshot-hygiene.md) | auto | Screenshots for docs — anonymize sensitive data before shipping; data-bearing shots are human-gated (published egress); terminal/CLI/IDE screenshots forbidden |
 | rule | [`docker-commands`](../dist/agent-src/rules/docker-commands.md) | auto | Running PHP inside Docker — artisan, composer, phpstan, rector, ecs, phpunit, tests, migrations, any CLI tool |
 | rule | [`domain-adoption-policy`](../dist/agent-src/rules/domain-adoption-policy.md) | auto | Adopting a new domain track (mobile, ML, IoT…) — demand/owner/CI gates BEFORE harvest |
 | rule | [`domain-safety-disclaimer`](../dist/agent-src/rules/domain-safety-disclaimer.md) | auto | Advisory content (legal, medical, financial, consulting) — matching 'not X advice' disclaimer; refuse diagnosis/dosage |
@@ -391,6 +395,7 @@ are excluded.
 | rule | [`rule-type-governance`](../dist/agent-src/rules/rule-type-governance.md) | auto | Creating/editing rules, or auditing rule types — decides when a rule should be always vs auto |
 | rule | [`runtime-safety`](../dist/agent-src/rules/runtime-safety.md) | auto | Skill declares execution metadata — enforce safety constraints for assisted/automated execution types |
 | rule | [`scope-control`](../dist/agent-src/rules/scope-control.md) | always | Scope control — no unsolicited architectural changes, refactors, or library replacements |
+| rule | [`secret-vcs-guard`](../dist/agent-src/rules/secret-vcs-guard.md) | auto | About to write a credential into a tracked file or stage/commit one in any VCS (git/svn/hg) — STOP, show the match, ask, offer alternatives; never silently commit, never silently strip |
 | rule | [`security-sensitive-stop`](../dist/agent-src/rules/security-sensitive-stop.md) | auto | Security-sensitive paths (auth, billing, tenants, secrets, uploads, webhooks) — threat-model BEFORE editing |
 | rule | [`senior-engineering-discipline`](../dist/agent-src/rules/senior-engineering-discipline.md) | auto | Writing/generating code — generalize (no overfit or tautological tests), supply the invisible cross-cutting controls the prompt didn't name, never invent an API/field/package |
 | rule | [`size-enforcement`](../dist/agent-src/rules/size-enforcement.md) | manual | Creating or editing rules, skills, commands, guidelines, AGENTS.md, or copilot-instructions.md — enforce size and scope limits |

package/docs/comparison.yaml

@@ -12,34 +12,76 @@
 # check_claims pointer resolver); every `checkable: true` row's `our_evidence`
 # resolves. build_proof renders these rows. check_no_external_sources guarantees
 # no named source leaks in.
+#
+# `failure_mode` (optional) — what this row's claim prevents, in adopter-facing
+# voice. A populated row ALSO renders in the "What each one prevents" view on the
+# proof page; an empty field is the honest signal that the row is comparative
+# only. Membership in that view is therefore a data property, never a curated
+# short-list that can drift from this table.
+#
+# THE PIN SHAPE IS REFUSED HERE, DELIBERATELY. A number in these rows is bound by
+# a resolving pointer — never by a test asserting that a literal string appears in
+# a doc. A comparable suite pinned a marketing figure with an
+# `assertIn("<number> tokens", …)` test; its own published formula yields a value
+# ~4x larger, and the pin turned the wrong number into a protected invariant that
+# CI actively defended. A pointer can go stale and be re-derived; a pin makes
+# staleness the passing condition.
 
 rows:
-  - claim: "No runtime — no background daemon, no state database, no auto-write memory."
+  - claim: "No resident runtime — no background daemon, no state database or service, no auto-write memory; deterministic, rebuildable file indexes only."
     our_evidence: "docs/contracts/no-runtime-boundary.md#file-first"
-    their_evidence: "Swarm-runtime tools in this category ship a background process and/or a state store by design; that is an architectural fact of the runtime approach, not a defect."
+    their_evidence: "Swarm-runtime tools in this category ship a background process and/or a resident state store by design; that is an architectural fact of the runtime approach, not a defect."
     checkable: true
+    failure_mode: >-
+      A background process keeps running after you stop using it, holds state you did not write, and has to be kept alive and upgraded.
 
   - claim: "Capability/benchmark results are published — including the runs where the package changed nothing."
     our_evidence: "docs/benchmark.md"
     their_evidence: "A category headline figure (e.g. an '84.8%' score) appears across marketing surfaces with no reproducible methodology published — so it cannot be verified either way."
     checkable: true
+    failure_mode: >-
+      You adopt on a headline number nobody can re-run, and never learn which of its measurements changed nothing.
 
   - claim: "Every public claim binds to machine-checked evidence."
     our_evidence: "docs/CLAIMS.md"
     their_evidence: "Marketing claims in this category are not bound to a machine-checked ledger a reader can reproduce."
     checkable: true
+    failure_mode: >-
+      A shipped number drifts from the artefact it came from and stays published, because nothing re-checks the claim against its source.
 
   - claim: "Skills publish their own known limits, each with a witness test."
     our_evidence: "tests/scripts/witness/check_refs_relative_gap.test.ts"
     their_evidence: "Published known-limitation surfaces backed by reproducing tests are not a standard artifact in this category."
     checkable: true
+    failure_mode: >-
+      A limitation is discovered by you, in your repo, at the moment it costs you something — instead of being stated up front and held by a test.
 
   - claim: "A 30-second single-file wedge exists — one read-only subagent, one command, verdict with file:line — and its promise is a scoped, published eval, not a feature list."
     our_evidence: "internal/bench/orchestration/pv-a3-results.md#token_delta_provenance: measured"
     their_evidence: "Category entry points typically install the full platform (profiles, packs, runtime) before the first felt win; single-artifact entries with a published eval behind the promise are not a standard artifact."
     checkable: true
+    failure_mode: >-
+      Evaluating the tool means installing the whole platform first, so the first thing you learn is the setup cost rather than whether it works.
 
   - claim: "The persona-identity question was tested and published as an honest null (identity swap ~zero effect, provider choice ~15x larger) instead of being shipped as theater."
     our_evidence: "internal/bench/reports/persona-placebo.json#honest-null"
     their_evidence: "Named-persona prompts are shipped as a feature across the category without a published A/B separating identity from method."
     checkable: true
+    failure_mode: >-
+      You pay tokens for prompt theater that was never measured against the method text it wraps.
+
+  - claim: "Every upstream-tool install prescription the package ships is version-pinned, intake-recorded, and enforced offline in CI — an unpinned version, a branch/archive install source, or a pipe-remote-to-shell instruction fails the build."
+    our_evidence: "src/scripts/validate_reach_prescriptions.ts"
+    their_evidence: "Capability layers in this category commonly install themselves and their upstream dependencies from a moving target (a branch archive or an unpinned package) via a piped remote installer; whether any given one pins is observable per repo, but a CI gate that fails the build on an unpinned prescription is not a standard artifact."
+    checkable: true
+    failure_mode: >-
+      An install instruction silently follows a moving target — an unpinned package or a piped remote script — so what lands in your repo is whatever the source held that day.
+
+  - claim: "Platform reads that the host's own web tools cannot perform at all (a refused domain, an HTTP 402) are shipped as credential-free prescriptions whose reliability was measured per channel against a native control, with the thresholds frozen before the run and the narrowing caveat published alongside the pass."
+    our_evidence: "docs/benchmark.md#ship-gated-reach"
+    their_evidence: "Reaching gated platforms is commonly solved in this category by asking for an API key or a session cookie, and the capability is asserted from a feature list rather than a per-channel reliability measurement with a native-arm control; publishing the case where the native tools already suffice, next to the pass, is not a standard artifact."
+    checkable: true
+    failure_mode: >-
+      You hand over a credential — or your account — for a read the tools could
+      already do, and you cannot tell which channels actually work because the
+      capability was claimed rather than measured.

package/docs/contracts/local-server-ports.md

@@ -0,0 +1,53 @@
+# Contract: local server ports + host integration
+
+> The loopback/port contract `src/server/port.ts` enforces, plus the
+> host-integration surface (config root + embed) a host like agent-switch binds
+> to. This file resolves the long-standing pointer in `src/server/port.ts`.
+
+## Port range
+
+- The GUI/API server binds on **loopback `127.0.0.1` only**, on a free port in
+  **41000–41999** (per ADR-012). `src/server/port.ts` picks a free port by
+  actually binding (no is-free → bind race) and refuses any range that overlaps
+  the privileged ports `[0, 1024]` or strays outside this documented range —
+  both are anti-regression guards (`validateRange`).
+- The chosen port is ephemeral per process; a host discovers the live port from
+  the server-info readout, never by assuming a fixed value.
+
+## Auth token
+
+- `src/server/token.ts`: a 32-byte hex token, per-process, mode `0600`, replaced
+  on every boot. The SPA reads it once from `?token=` at boot, then strips it
+  from the URL; subsequent calls use the `Authorization: Bearer` header. There is
+  no cookie. A host must re-read the token after every respawn.
+
+## Host integration — config root
+
+- `agent-config --config-root <path>` (flag) or `EVENT4U_CONFIG_HOME` (env) sets
+  AC's config home. Precedence: **flag > env > default**; absent → default
+  behavior is unchanged. This lets a host give AC a per-profile config root so
+  profile-scoped settings do not silently collide.
+
+## Host integration — embed
+
+- `?embed=1` renders AC chrome-stripped (no standalone nav/brand, no theme
+  toggle — the host owns the theme); settings deep-links `#/settings` and
+  `#/settings/<section>` keep working.
+- **Framing:** AC sends CSP `frame-ancestors 'none'` and is **never** iframe-able
+  — a host renders AC's URL in a **separate top-level window**, not a frame.
+- `?theme=light|dark` feeds the pre-paint `data-theme` stamp (no flash).
+
+## Capability discovery
+
+- `GET /api/v1/ping` and `agent-config --version --json` carry a `capabilities`
+  block: `{ configRoot: true, embed: { supported: true, version: 1, features:
+  ['theme', 'deepLink'] } }`. A host checks a capability, not a version number —
+  an older AC omits the block and the host degrades to a clear "not supported".
+
+## References
+
+- Port range: ADR-012. Enforcement: `src/server/port.ts`.
+- Token transport: `src/server/token.ts`.
+- Capabilities source: `src/shared/capabilities.ts`.
+- Host-side plans: `agents/roadmaps/road-to-ac-embeddable-gui.md`,
+  `agents/roadmaps/road-to-reciprocal-ecosystem.md`.

package/docs/contracts/no-runtime-boundary.md

@@ -37,7 +37,7 @@ and violating the no-runtime principle).
 | Category | Why |
 |---|---|
 | **Background processes / daemons** | No spawned subprocesses that outlive the current agent turn |
-| **Cross-session persistent state stores** | No SQLite, pgvector, MCP memory servers, Redis, or any store that persists beyond the git working tree — agent-memory layer sunset applies here |
+| **Cross-session persistent state stores** | No SQLite, pgvector, MCP memory servers, Redis, or any store that persists beyond the git working tree — agent-memory layer sunset applies here. **Carve-out (ADR-124 § 6): a gitignored, deterministic, rebuildable build/index artifact under `agents/runtime/state/` is a build output, not a state store** — it carries no authority, is reproducible from the working tree, and is never auto-written memory. State-store test: if deleting the artifact changes *what* the tool can answer rather than only *how fast* it answers, it is a state store and prohibited (a code-graph cache passes — deletion only slows recompute; a vector/embedding index fails — it enables query semantics absent from source, and stays Class C). |
 | **Event loops / polling** | No `while true; do …; done`, no `inotifywait`, no cron-inside-mission |
 | **Auto-PR / auto-push** | Hard-Floor (`non-destructive-by-default`): missions never push to remote or open PRs autonomously; those gates require explicit user confirmation every turn |
 | **Network egress from mission scripts** | Mission scripts may not initiate outbound HTTP calls; skills that need network access declare `allowed_tools` explicitly and go through the normal lethal-trifecta gate |

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-122-adversarial-verification-council.md

@@ -134,3 +134,33 @@ Each settled decision this roadmap does NOT touch:
   ADR-120 (council chairman mode), ADR-109 (subagent-v1 contract).
 - `docs/CLAIMS.md#adversarial-council-finding-coverage` — the pre-registered claim.
 - `cross-vendor-parity` (backed) — the evidence the finding-coverage scope rests on.
+
+## Addendum (2026-07-21) — finding-coverage claim resolved HONEST-NULL
+
+The pre-registered `adversarial-council-finding-coverage` claim was executed and
+resolved **negative**. A curated judge-survivable corpus
+(`internal/bench/adversarial-council/`: 12 planted-defect fixtures across
+multi-file-interaction / logic-inversion / security-masked / complex-state + 3
+controversial-but-correct clean controls; subtlety distribution published;
+passed an independent validity audit after one fixture was repaired) was run
+cross-vendor (anthropic `claude-sonnet-4-5` + openai `gpt-4o`) under the
+maintainer spend authorization.
+
+**Result:** on the judge-passed residual, the 2-vendor skeptic panel matched the
+single skeptic exactly (residual recall 0.60 = 0.60, **zero lift** — the second
+vendor's catches were a strict subset of the first's), at a **100%** false-
+positive rate on the controversial-but-correct controls under the adversarial-
+skeptic posture. Both locked recall thresholds missed -> honest-null. **The
+Mode 9 `adversarial-verification-council` surface stays default-off permanently**
+(no settings change — it already ships off), recorded like recursive-verification
+(ADR-106). Detail + reproducible artifact:
+`docs/benchmark.md#adversarial-verification-council`,
+`internal/bench/adversarial-council/runs/`.
+
+**Transport lesson (durable):** `council_cli run`/`debate` is a *deliberation*
+transport — multi-round peer-review with cross-member visibility, prose output.
+It is the WRONG tool for an independent-skeptic, structured-output benchmark (it
+violated the independence requirement and defeated JSON scoring; the first run
+through it was rejected as an artifact). The valid measurement uses direct,
+independent per-vendor client calls with a strict-JSON contract and a
+deterministic, pre-validated scorer.

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

@@ -109,3 +109,34 @@ are also rejected: per-file pragma containment (`security_lint.ts`) only.
   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.