@event4u/agent-config 9.0.0 → 9.2.0

package/docs/decisions/ADR-122-adversarial-verification-council.md

@@ -0,0 +1,136 @@
+---
+adr: 122
+status: accepted
+date: 2026-07-14
+decision: adversarial-verification-council
+supersedes: —
+superseded_by: —
+phase: adversarial-verification-council
+type: structural
+---
+
+# ADR-122 — Adversarial verification council: finding-coverage scope, advisory-only, default-off
+
+## Status
+
+Accepted (2026-07-14).
+
+## Context
+
+The verify/council family is mature: the external council engine, multi-round
+debate, chairman mode (ADR-120), stance tally, `verify-repair-loop` (the
+judge→revise→re-judge loop), the seven `judge-*` skills, `judge-synthesis`, the
+`subagent-orchestration` mode set, and the `verify-budget` routing all ship. A
+three-strand research pass (surface map + archived-roadmap autopsy + infra
+inventory, 2026-07-14) confirmed that almost every *decision-consensus*
+mechanism in this space is either built or is a recorded honest-null:
+
+- recursive self-correction as a capability/discipline lever — honest-null,
+  council-terminal (ADR-106);
+- the judge→revise→re-judge loop — shipped as `verify-repair-loop`;
+- personas / named-figure agents — placebo-null (Δ=0.17, p=0.607); provider
+  diversity moved quality ~15× more than persona identity;
+- browser-automation council members — maintainer-killed (council-modes 2c);
+- a `--council` in-flow UX product surface — stub, gated on the
+  orchestration-scope decision + a demand signal;
+- "council beats a solo strong model on decision quality" —
+  `council-vs-solo-baseline`, pre-registered `unbacked`, spend-gated.
+
+The one un-mined, evidence-supported wedge is **adversarial verification as
+defect FINDING coverage** (not decision quality). The `cross-vendor-parity`
+claim is *backed*: different providers surface different real findings on
+multi-file analysis; both catch a planted hollow impl; both stay silent on a
+clean control. No wired surface exists that runs a model-diverse skeptic panel
+adversarially against a real change to maximise defect-finding coverage — the
+nearest kin (`judge-with-debate`, strict-er-wins on one verdict;
+`judge-synthesis`, consume-only consensus) do something categorically different.
+
+## Decision
+
+Ship an **adversarial verification council** as a distinct, opt-in,
+**advisory-only** surface, scoped to **finding coverage, not decision quality**:
+
+1. **A 9th `subagent-orchestration` mode** `adversarial-verification-council`:
+   N (default 2) distinct-model skeptics red-team a real, already-verified
+   change through the `judge-*` lenses; each returns findings; results are
+   reconciled into a findings-by-severity verdict with per-finding provenance and
+   a cross-model confidence signal. Distinct from Mode 6 because the output is a
+   **findings-union with provenance**, not a strict-er-wins single verdict.
+2. **A machine-readable findings envelope** `adversarial-findings.json` (draft-07,
+   hand-validated like `subagent-status.json`) — filling the gap of no shared
+   judge-verdict schema.
+3. **Countable reconciliation in TS with tests** (`adversarial_reconcile.ts`):
+   dedup, severity-quorum confidence, and false-positive suppression. Never
+   LLM-computed prose (anti-lesson). Never gates the change — only ranks and
+   annotates findings.
+4. **Opt-in wiring, default-off**: a `subagents.adversarial_council: off|ask|on`
+   setting (default `off`); an opt-in escalation tier in `verify-budget` for
+   explicitly high-risk changes; an opt-in flag on `/review-changes` (or
+   `/judge`). The panel never auto-gates a change (Hard Floor: advisory only).
+5. **Prove-or-drop against a pre-registered finding-coverage claim**
+   (`adversarial-council-finding-coverage`, `unbacked` at start). The benchmark
+   is a **two-stage residual-detection protocol** (single strong judge first →
+   panel on the judge-passed residual subset), on a corpus with published
+   judge-survivable subtlety distribution, with a **dual threshold** (relative
+   ≥ +25% AND absolute ≥ +8 pp residual-recall lift) and a
+   **controversial-but-correct FP control**. Honest-null is an accepted outcome
+   and keeps the surface inert-by-default permanently.
+
+### Skeptic transport (fork F1)
+
+Everyday mode uses an in-session subagent panel with enforced model diversity.
+The **registered benchmark run and the opt-in high-risk tier require
+cross-*vendor* skeptics** (via `council_cli.ts`, artefact/diff-as-text,
+read-only) — the backed `cross-vendor-parity` signal is provider-level, so the
+claim cannot rest on same-vendor model diversity alone.
+
+## Consequences
+
+- The package gains a defect-finding verification surface that composes existing
+  primitives — no rebuilt engine, no recursion loop, no persona layer, no
+  browser automation, no `--council` UX product.
+- A new shared findings schema exists that future judge-panel work can reuse.
+- The value claim is measurable (finding coverage on a static corpus, unlike
+  orchestration value in the no-runtime harness), and its resolution is honest:
+  a null keeps the surface off by default, like recursive-verification.
+- Default-off means zero cost/behaviour change until a consumer opts in.
+
+## Landmine-clearance (do-not-relitigate map)
+
+Each settled decision this roadmap does NOT touch:
+
+- **Recursion / re-attempt loop** — not added; the panel is single-pass finding
+  generation, not a self-correction loop.
+- **judge→revise→re-judge** — reused (`verify-repair-loop`), not rebuilt.
+- **Council engine / debate / budget / redaction / chairman** — reused, not
+  re-proposed.
+- **Personas / named-figure agents / persona panel-mode** — not used; skeptics
+  are model-diverse, not persona-diverse.
+- **Browser-automation / web-subscription scraping** — not revived.
+- **`--council` in-flow UX product / verdict-report product layer** — not built;
+  the findings envelope is an engineering contract, not a productized report.
+- **council-vs-solo decision-quality claim** — out of scope; the claim here is
+  finding coverage, resting on the backed `cross-vendor-parity` signal.
+- **Orchestration value measured in a no-runtime harness** — not claimed; the
+  benchmark measures finding coverage on a static planted-defect corpus.
+- **Prose-computed reconciliation** — reconciliation is TS with tests.
+
+## Alternatives
+
+- **Extend Mode 6 `judge-with-debate`** — rejected: its strict-er-wins single
+  verdict is a go/no-go decision, categorically different from a findings-union;
+  overloading it would blur two contracts.
+- **Build on the external `ai-council` for the everyday path** — rejected: the
+  external council is artefact-only / read-only by Hard-Floor contract; the
+  everyday code path is in-session `subagent-orchestration`. External
+  cross-vendor is reserved for the registered claim + high-risk tier.
+- **Default-on** — rejected: no evidence yet; default-off until the
+  pre-registered claim is `backed`.
+
+## References
+
+- `agents/roadmaps/road-to-adversarial-verification-council.md` — the roadmap.
+- ADR-106 (recursive-verification honest-null), ADR-117 (subagents.auto flip),
+  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.

package/docs/decisions/INDEX.md

@@ -125,6 +125,7 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-119](ADR-119-global-knowledge-default-on.md) | Global Knowledge Default On | accepted | 2026-07-12 | 103 |
 | [ADR-120](ADR-120-council-chairman-mode.md) | Council Chairman Mode | accepted | 2026-07-12 | — |
 | [ADR-121](ADR-121-knowledge-sensitivity-classes.md) | Knowledge Sensitivity Classes | accepted | 2026-07-12 | — |
+| [ADR-122](ADR-122-adversarial-verification-council.md) | Adversarial Verification Council | accepted | 2026-07-14 | — |
 | [ADR-200](ADR-200-python-to-typescript-migration.md) | Python To Typescript Migration | accepted | 2026-06-11 | — |
 
 ## Unnumbered (legacy)

package/docs/design/adversarial-council-eval.md

@@ -0,0 +1,106 @@
+# Adversarial verification council eval — two-stage residual-detection design
+
+> Design artifact for `road-to-adversarial-verification-council` Phase 4. It
+> pins the benchmark that resolves the pre-registered `adversarial-council-
+> finding-coverage` claim (docs/CLAIMS.md, ADR-122). Writing this design is
+> autonomous; **curating the corpus and running the paid cross-vendor arm is a
+> maintainer cost decision**, gated on the corpus-validity check below.
+
+## What the claim is — and is not
+
+- **Is:** does a cross-vendor skeptic panel find materially more of the defects
+  that **survive a single strong judge** (the residual pool), at a false-positive
+  rate no worse than that judge on a controversial-but-correct control?
+- **Is not:** whether the council beats a solo model on *decision quality* — that
+  is the separate, `unbacked`, spend-gated `council-vs-solo-baseline`
+  (docs/design/council-vs-solo-baseline.md), explicitly out of scope.
+
+## The council's load-bearing critique (folded in)
+
+The AI-council debate (2026-07-14, anthropic/claude-sonnet-4-5 + openai/gpt-4o)
+converged on one real risk: the existing `cross-model-parity` corpus was built
+to show that different vendors catch different **obvious** things (parity), not
+to simulate the **residual** state after a competent first pass. Running the
+registered claim on it would force an honest-null as a *measurement artifact*,
+not a mechanism result. This design answers that with a two-stage protocol, a
+corpus-subtlety bar, a dual threshold, and a controversial-clean FP control.
+
+## Two-stage protocol
+
+1. **Stage 1 — single strong judge.** A single cross-model judge runs on every
+   planted-defect change. The defects it CATCHES are removed from scope.
+2. **Stage 2 — the panel on the residual.** Only the changes that PASS stage 1
+   (defect not caught) proceed to the Mode 9 panel. Recall is measured on this
+   **judge-passed residual pool** — the production-relevant quantity.
+
+This makes "residual detection" explicit rather than implicit in corpus
+selection.
+
+## Corpus-validity gate (blocks the registered run)
+
+The corpus must contain **judge-survivable subtleties**, published as a
+distribution before the registered run:
+
+- multi-file interaction defects,
+- subtle logic inversions that read as plausible,
+- security masked by correct-looking patterns,
+- edge cases in complex state.
+
+Publish the severity/subtlety distribution (share single-file <5 LoC vs
+multi-file interaction). A corpus skewed to trivially-detectable defects fails
+this gate — the registered run does not proceed until it passes.
+
+### Assessment of the existing corpus (2026-07-14)
+
+`internal/bench/orchestration/corpus/` (5 tasks: orch-01..03, pv-01 hollow,
+pv-02 control) was purpose-built for the parity signal and for A3
+production-validator Gate-A. `pv-01` is a deliberately **obvious** hollow impl
+(a floor sanity check), and none of the five tasks is designed as a
+judge-survivable residual defect. **Conclusion: this corpus does NOT meet the
+subtlety bar** — so the registered run is **blocked** pending a curated
+residual-defect corpus. The claim stays `unbacked` until then (no false
+`backed`).
+
+## Controversial-but-correct FP control
+
+The clean control includes correct-but-non-obvious cases (real perf/security
+design tradeoffs, uncommon patterns) — not only obviously-clean code — so the
+red-team posture's true FP cost is measured. Panel FP is compared to the
+single-judge FP on the SAME control.
+
+## Panel = cross-vendor
+
+The registered run and the opt-in high-risk tier use >=2 distinct **providers**
+(e.g. anthropic + openai), via the council transport (`council_cli.ts`,
+artefact/diff-as-text, read-only). The backed `cross-vendor-parity` signal is
+provider-level; same-vendor model diversity is insufficient for the claim.
+
+## The gate (locked at pre-registration)
+
+Encoded in [`src/scripts/_lib/adversarial_council_gate.ts`](../../src/scripts/_lib/adversarial_council_gate.ts)
+(`evaluateCouncilBench`), covered by `adversarial_council_gate.test.ts`:
+
+- (a) relative residual-recall lift >= **+25%**, AND
+- (b) absolute residual-recall lift >= **+8 pp**, AND
+- panel FP not worse than single-judge FP within the noise margin.
+
+Both recall thresholds are required — the dual gate guards the base-rate
+compression the council flagged (a high single-judge baseline makes relative
+lift easy but absolute must still clear). Threshold values are **locked**;
+corpus/protocol may be refined *before* the registered run, never the threshold
+after seeing results.
+
+## Outcome handling
+
+- **Pass** → flip `docs/CLAIMS.md#adversarial-council-finding-coverage` to
+  `backed` with the report pointer; document the recommended cross-vendor config.
+- **Honest-null** → record it (ADR-122 addendum + `docs/benchmark.md`), keep the
+  surface `off` by default permanently, mark the roadmap null-but-shipped-inert
+  (like recursive-verification).
+
+## Status
+
+- Gate logic: **built + tested** (deterministic TS).
+- Corpus-validity gate: **assessed — existing corpus fails the subtlety bar.**
+- Registered paid cross-vendor run: **deferred**, blocked on curating a
+  judge-survivable-subtlety corpus. Claim remains `unbacked`.

package/docs/featured-skills.md

@@ -1,6 +1,6 @@
 # Featured Skills
 
-A curated subset of the 274 skills. Three tiers, one per primary audience. Full catalog lives in [`dist/agent-src/skills/`](../dist/agent-src/skills/); see also [`docs/catalog.md`](catalog.md) for the complete index and [`docs/featured-commands.md`](featured-commands.md) for command-level highlights.
+A curated subset of the 275 skills. Three tiers, one per primary audience. Full catalog lives in [`dist/agent-src/skills/`](../dist/agent-src/skills/); see also [`docs/catalog.md`](catalog.md) for the complete index and [`docs/featured-commands.md`](featured-commands.md) for command-level highlights.
 
 > **Eval-gated messaging note.** Until `task bench --corpus non-dev` reports `selection_accuracy >= 0.60` (see `road-to-product-adoption.md` Phase 1), this page is documentation, not marketing. The entries below are the candidates the corpus tests against; their description quality is what the eval validates.
 
@@ -92,4 +92,4 @@ task lint-featured-skills
 
 CI runs this in `taskfiles/ci-fast.yml`. Stale entries (renamed / removed skill or command) fail the build. See [`scripts/lint_featured_skills.py`](../src/scripts/lint_featured_skills.py) for the matcher.
 
-→ Browse all 274 skills: [`dist/agent-src/skills/`](../dist/agent-src/skills/) · all 183 commands: [`dist/agent-src/commands/`](../dist/agent-src/commands/)
+→ Browse all 275 skills: [`dist/agent-src/skills/`](../dist/agent-src/skills/) · all 184 commands: [`dist/agent-src/commands/`](../dist/agent-src/commands/)

package/docs/getting-started-by-role.md

@@ -2,7 +2,7 @@
 
 > Pick the entry that matches what you do day-to-day. Each section names the three skills you will reach for first and shows whether MCP (no terminal) or CLI (terminal) is the simpler install path for that role.
 
-`agent-config` ships 274 skills, 104 governed rules, and 183 commands. You do not need all of them. Each role below filters to the slice that pays back in week one; the rest stays available and shows up on demand when a task references it.
+`agent-config` ships 275 skills, 105 governed rules, and 184 commands. You do not need all of them. Each role below filters to the slice that pays back in week one; the rest stays available and shows up on demand when a task references it.
 
 > **Taglines at a glance →** [`docs/role-experiences.md`](role-experiences.md) — the one-line pitch per role experience, in one table.
 

package/docs/getting-started.md

@@ -134,7 +134,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 104 rules. No configuration needed.
+This is enforced automatically by 105 rules. No configuration needed.
 
 ---
 
@@ -174,7 +174,7 @@ Your agent now understands slash commands:
 | `/fix quality` | Run and fix all quality checks |
 | `/chat-history import` | Pull a prior session into the current chat (resume) |
 
-→ [Browse all 183 active commands](../dist/agent-src/commands/)
+→ [Browse all 184 active commands](../dist/agent-src/commands/)
 
 ---
 

package/docs/governance-advantage.md

@@ -33,7 +33,7 @@ the host lacks (a static host gives it no runtime attention guarantee, but a
 runtime-only system gives it nothing at all here). A runtime-only system contributes *nothing* on these hosts.
 
 ### 2. Intent routing, not a 500-artefact dump
-A prompt does not load all 274 skills. `dist/router.json` (100 routed rules, intent →
+A prompt does not load all 275 skills. `dist/router.json` (101 routed rules, intent →
 skill, keyword/phrase/path triggers) carries the right skill on intent. The
 governance value is *selection discipline* — the host gets the relevant rule
 set, not the whole catalogue as context ballast.

package/docs/guidelines/agent-infra/api-cost-levers.md

@@ -0,0 +1,126 @@
+# API Cost Levers
+
+Reference material for a downstream AI-coding agent that wants to cut its own
+Claude API dollar bill. Four platform-level billing levers, the exact economics
+of each, and how they interact. Read on demand — not always-loaded.
+
+Facts sourced from the in-repo `claude-api` plugin skill plus platform research
+(2026-07-14). Do not invent an API shape beyond what is stated here.
+
+## The four levers at a glance
+
+| Lever | Cuts | Best for | Watch out for |
+|---|---|---|---|
+| Prompt caching | Repeated input tokens | Stable prefix reused across calls (system prompt, tools, repo map) | Any byte change in the prefix invalidates the rest |
+| Batch API | 50% input + output | Non-interactive bulk work (classification, summarization, evals) | Async, up to 24h, results unordered |
+| Model tiering | Per-token price | Routine work on a cheaper model | Switching model is a cache miss |
+| Effort / output sizing | Thinking + output tokens | Routine turns that don't need deep reasoning | Oversized `max_tokens` risks runaway output |
+
+## 1. Prompt caching
+
+Put the large, byte-**stable** context first — system prompt, tool definitions,
+a corpus or repo map, few-shot examples — behind a
+`cache_control: {type: 'ephemeral'}` breakpoint. Keep volatile content (the
+varying question, timestamps, per-request IDs) **after** the last breakpoint.
+The cache is a **prefix match**: any byte change in the cached prefix
+invalidates everything after it. Render order is tools then system then
+messages.
+
+Caching is GA — **no beta header needed**.
+
+Economics:
+
+- Cache reads cost approximately 0.1x the base input price.
+- Cache writes cost 1.25x (5-minute TTL) or 2x (1-hour TTL).
+- Break-even is after **one** read on the 5-minute TTL.
+
+Constraints:
+
+- The minimum cacheable prefix is model-dependent (approximately 1024–4096
+  tokens). Shorter prefixes silently do not cache.
+- The cache is workspace-isolated (since February 2026).
+
+Verify a hit with `usage.cache_read_input_tokens > 0`.
+
+```json
+{
+  "system": [
+    { "type": "text", "text": "<large stable system prompt>",
+      "cache_control": { "type": "ephemeral" } }
+  ],
+  "messages": [
+    { "role": "user", "content": "<the varying question>" }
+  ]
+}
+```
+
+## 2. Batch API
+
+For **non-interactive, non-latency-sensitive bulk work** — bulk classification,
+mass file summarization, eval runs. Not chatbots or interactive assistants.
+
+- **50% off both input and output tokens.**
+- Async: results within 24h (usually much less), keyed by `custom_id`, arriving
+  **unordered** — key results by `custom_id`, never by position.
+- **Stacks with prompt caching**: a cached-batch input token can reach
+  approximately 0.05x the standard input price.
+
+## 3. Model tiering
+
+Treat models like a team — a cheap model for mechanical or routine work, the
+expensive model only for hard judgment. Approximate input / output price per 1M
+tokens:
+
+| Model | Input | Output |
+|---|---|---|
+| Haiku | $1 | $5 |
+| Sonnet | $3 | $15 |
+| Opus | $5 | $25 |
+| Fable | $10 | $50 |
+
+Opus input is approximately 5x Haiku. Tier by task **difficulty**, not blindly:
+a cheaper model that gives wrong answers on judgment tasks costs correction
+cycles, which erases the saving.
+
+**Interaction with caching.** The prompt cache is keyed by `(model, prefix)`, so
+switching a call to a cheaper model is a cache **miss**. Weigh the downgrade
+saving against the lost cache-read saving before routing a cached call to a
+different model.
+
+## 4. Effort and output right-sizing
+
+- `output_config.effort` (low through max) controls thinking and output depth,
+  and therefore spend. Dial effort **down** on routine turns; reserve high / max
+  for hard reasoning.
+- Right-size `max_tokens` — do not leave a huge ceiling. An unrealistically
+  large `max_tokens` does not cost tokens by itself, but it risks runaway output
+  and defeats pre-flight budgeting.
+
+## When to reach for which
+
+| Situation | Lever |
+|---|---|
+| Same large context reused across many calls | Prompt caching |
+| Thousands of independent, non-urgent jobs | Batch API (+ caching) |
+| Turn is mechanical / narrow / well-specified | Cheaper model tier |
+| Turn is routine and does not need deep thinking | Lower `effort` |
+| Output could balloon unnecessarily | Cap `max_tokens` |
+| Interactive latency matters | Caching + tiering; not Batch |
+
+## Claude Code note
+
+In Claude Code, prompt caching is automatic — resending the same context prefix
+is cheap, so keeping a stable prefix pays off without any explicit
+`cache_control`. The session-level hygiene levers are `/clear` and `/compact` to
+shed accumulated context, plus subagent delegation for verbose output so it
+never lands in the main context window.
+
+## See also
+
+- [`model-recommendation.md`](model-recommendation.md) — tier routing (the
+  capability band behind lever 3).
+- [`size-and-scope.md`](size-and-scope.md) — token discipline for the artifacts
+  that become the cached prefix.
+- The Claude Code `claude-api` plugin skill (external, not vendored here) — the
+  authoritative, versioned API reference these figures derive from; re-check it
+  when Anthropic pricing or the caching/batch surface changes.

package/docs/guidelines/agent-infra/cross-source-consistency-mechanics.md

@@ -0,0 +1,109 @@
+# Cross-Source Consistency — Mechanics
+
+> The discrepancy taxonomy, the scan procedure, the confidence-tiered noise control, worked examples, and the precedence table for the `cross-source-consistency` rule
+
+_Companion to `src/rules/cross-source-consistency.md` (P4 pattern of `road-to-kernel-and-router.md`). The Iron Law, the fire/not-fire scope, and the subordination clauses stay in the rule; this file carries the taxonomy detail, the scan procedure, and the examples._
+
+## The discrepancy taxonomy
+
+| # | Class | Definition | Canonical example |
+|---|---|---|---|
+| a | **text ↔ image** | The ticket/spec text contradicts an attached mockup, screenshot, or diagram. | Text: "show birthdays **today**". Mockup: a birthday from two days ago. |
+| b | **silent-but-needed** | The spec is silent on a behavior that is clearly required for the feature to be correct. | Spec: weekend-shifting only. Clearly also needed: public-holiday shifting — but never specified. |
+| c | **spec ↔ codebase/reality** | The spec contradicts what the code, DB, API, or a real source actually does. | Spec: "the endpoint returns `dueDate`". The DTO has no such field. |
+| d | **intra-ticket** | Acceptance criteria, description, and comments contradict each other. | Description: real-time. AC: "nightly batch is fine." |
+
+Type (a) and (d) are **contradictions between present sources** — the agent
+must not pick one silently. Type (b) is a **scope decision** — the inferred
+behavior may be right, but adding it is a scope expansion the user owns. Type
+(c) routes the *verification* to `source-discovery` (read the real source); this
+rule only owns *surfacing the conflict and asking*.
+
+## The scan procedure
+
+Run this whenever planning, refining, estimating, roadmapping, or implementing
+from a ticket/spec that carries a second source:
+
+1. **Enumerate the sources.** Ticket text, every attachment (mockup / screenshot
+   / diagram), the AC block, description, comments, and — for implementation —
+   the relevant codebase/DB/API surface. If an attachment cannot be read,
+   say so; do not assume it agrees.
+2. **Compare pairwise for type (a), (c), (d).** For each pair, ask: do they state
+   the same thing about the same requirement? A mismatch is a discrepancy.
+3. **Scan for type (b) — silence.** List the behaviors the feature obviously
+   needs but the spec never mentions (weekend/holiday shifts, empty states,
+   error paths, permission edges, pagination, timezone). Each unstated-but-needed
+   behavior is a candidate to surface — not to implement.
+4. **Classify confidence.** High = the sources plainly disagree, or the missing
+   behavior is clearly load-bearing. Low = the "conflict" is a plausible
+   re-reading, or the missing behavior may be intentionally out of scope.
+5. **Decide per the setting** (below), then **batch** every surviving discrepancy
+   into ONE question folded into this turn's single `ask-when-uncertain` prompt.
+
+## Confidence-tiered noise control (`consistency.cross_source`)
+
+The rule fires only under a real trade-off (it must pass the
+`no-cheap-questions` Pre-Send Self-Check). The setting tunes how aggressively:
+
+| Value | High-confidence discrepancy | Low-confidence discrepancy |
+|---|---|---|
+| `on` (default) | Surface + ask before proceeding. | Surface + ask (batched into the same question). |
+| `auto` | Surface + ask. | State as an explicit assumption and proceed (no question). |
+| `off` | No cross-source checking — legacy behavior. | No cross-source checking. |
+
+Batching is the anti-noise mechanism: N discrepancies for one artefact become
+one numbered-options block, never N prompts. Plain vagueness (a single unclear
+source, no second source to compare) is **not** a discrepancy — it stays with
+`ask-when-uncertain` so the two disciplines never double-fire on the same input.
+
+## Worked examples
+
+### Example 1 — text ↔ image (type a)
+
+Ticket: *"The tile shows employees who have their birthday **today**."* Attached
+mockup: a card with a birthday dated **two days ago**.
+
+- Wrong: implement "today" (or implement "recent, like the mockup") and move on.
+  Both are silent guesses on a real contradiction — a violation even if the
+  chosen reading turns out correct.
+- Right: *"The ticket text says 'today' but the mockup shows a birthday from two
+  days ago. Which is authoritative — (1) strictly today, (2) a recent window as
+  the mockup implies, (3) something else?"* Then implement the confirmed reading;
+  `design-fidelity` governs building it 1:1 afterwards.
+
+### Example 2 — silent-but-needed (type b)
+
+Ticket update: *"If a birthday falls on the weekend, show it on the next
+workday."* The spec never mentions public holidays.
+
+- Wrong: also shift birthdays that fall on a public holiday, because it is
+  "obviously" consistent with the weekend rule — a silent scope expansion.
+- Right: *"The spec covers weekend-shifting but is silent on public holidays.
+  Should birthdays on a public holiday also shift to the next workday? (1) yes,
+  same as weekends, (2) no, holidays are out of scope, (3) only regional
+  holidays."* Obvious-to-the-agent ≠ in-scope; `scope-control` owns the
+  expansion permission.
+
+## Precedence & subordination
+
+| Neighbour rule | Relationship |
+|---|---|
+| `ask-when-uncertain` | **Parent ask discipline.** This rule folds its discrepancy into that rule's single question. `ask-when-uncertain` fires on *missing* info; this adds *conflicting present* sources. Never a second question block. |
+| `scope-control` | **Permission authority** for the type-(b) silent-scope-expansion. This rule surfaces the expansion; `scope-control` gates it. |
+| `design-fidelity` | **Fires after** this rule. This rule resolves a text↔image conflict at decision time; `design-fidelity` then enforces build-time 1:1 fidelity to the resolved design. |
+| `source-discovery` / `source-discovery-gate` | **Owns verification** for type (c). This rule surfaces the spec↔code conflict; `source-discovery` provides the evidence procedure. |
+| `no-cheap-questions` | **Floor.** A discrepancy ask must carry a real trade-off; batch, never nag. |
+| `active-remediation` | **Sibling shape.** Its never-silently-ignore ladder is the response model this rule applies to source discrepancies rather than code issues. |
+
+## Failure modes
+
+- **Silent-correct-guess.** Picking the right reading of a contradiction without
+  asking. Correct output, wrong process — still a violation.
+- **Double-firing.** Emitting a discrepancy question AND a separate
+  `ask-when-uncertain` / `improve-before-implement` question about the same
+  underlying uncertainty. Fold into one turn's one question.
+- **Noise creep.** Surfacing plausible re-readings as if they were hard
+  contradictions. Use the confidence tier; `auto` states low-confidence as an
+  assumption instead of asking.
+- **Silent scope expansion.** Implementing an inferred-but-unspecified behavior
+  because it seems obvious. It is a scope decision the user owns.

package/docs/installation.md

@@ -3,7 +3,8 @@
 **Principle:** Global is the only consumer scope. `init` writes to
 user-scope paths (`~/.event4u/agent-config/`, `~/.claude/`,
 `~/.cursor/`, …); the project tree only gets `agents/overrides/`
-and `agents/.event4u-bridge.yml`. Opt-in `export` if a team wants
+(the bridge marker was retired — ADR-020 amendment 2026-07-13; the
+global root resolves from `~/.event4u/agent-config`). Opt-in `export` if a team wants
 a tool's config committed to a repo. No Task, no Make, no build
 tools required.
 

package/docs/maintainers/dev-mode.md

@@ -23,8 +23,9 @@ With the flag set, the installer:
 1. Allows project-scope writes back into the repo tree (so a
    maintainer can run `task dev:install-global` and iterate on the
    working copy).
-2. **Skips** writing `agents/.event4u-bridge.yml` into the package
-   repo (per `consumer-bridge § Writer contract`). The repo is the
+2. **Skips** consumer-surface writes into the package repo. (The
+   `agents/.event4u-bridge.yml` marker is retired — ADR-020 amendment
+   2026-07-13 — and no longer written at all.) The repo is the
    source, not a consumer of itself.
 3. Treats `~/.event4u/agent-config/` as a peer install — touches are
    limited to the working-copy projection.

package/docs/proof.md

@@ -27,7 +27,7 @@ evidence pointer, or `task check-claims` fails the build.
 | Claim | Kind | Evidence | Resolves |
 |---|---|---|---|
 | The release process is documented as an inheritable runbook + succession doc, and the project's bus-factor (trailing-90-day distinct human reviewers) is tracked and reported truthfully — currently 1, not implied to be more. | qual | `docs/succession.md#trailing 90 days` | ✅ |
-| 183 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| 184 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | A MEASURED-BUT-NOT-SHIPPED experiment — the thin rule projection reduced eager rule load 78,513 → 13,881 GPT-tokens (whole always-loaded projection 98,529 → 33,897, ~65.6%), but FAILED the quality gate (thin win-rate 36.2% vs required 48%) and does not ship; it un-defers only behind `discipline_profile: essential`. Shipped behavior does NOT include this reduction. Method: `agent-config benchmark` over the pinned token baseline; the baseline is the honest "what the user pays if everything loads eagerly", NOT a synthetic full-corpus strawman (council Q4); quality gate per the Phase-0 paired judge run. | quant | `internal/bench/reports/token-baseline.json#eager_rule_load` | ✅ |
 | The first cross-vendor parity pass (5 orchestration-corpus tasks × 2 vendors × 3 repeats, identical prompts via the council transport, $0.16) measured real per-host finding-count differences — claude-sonnet-4-5 surfaced ~2× the findings of gpt-4o on the multi-file analysis task (median 11 vs 5) while both vendors were identical on the planted hollow-implementation task (2 vs 2) and perfectly silent on the clean-code negative control (0 vs 0, no spurious findings). The per-task `finding_floor` values are calibrated from the cross-host lower envelope and the gate is armed. | quant | `internal/bench/reports/parity-count.json#min over hosts of median` | ✅ |
 | On a weak host (claude-haiku-4-5) the package produces a significant, placebo-controlled discipline lift on scope/downstream traps; on a strong host the same measurement is a published null — the package transplants discipline a weak model lacks, not model intelligence. | quant | `docs/benchmark.md#weak-host-specific` | ✅ |
@@ -41,11 +41,11 @@ evidence pointer, or `task check-claims` fails the build.
 | The whole layer is compiled into host agents with zero runtime daemon. | qual | `docs/contracts/no-runtime-boundary.md#file-first, no-runtime suite` | ✅ |
 | On a 12-fixture option-decision corpus (3 arms × 2 providers, blind rubric judge claude-opus-4-8, pre-registered hypotheses), famous-figure identity framing added nothing beyond the underlying method text (method 5.04 vs figure 4.88, Δ=0.17, sign-test p=0.607), and provider diversity moved judged quality ~15× more than persona identity (provider Δ=2.58 vs identity Δ=0.17); the whole persona layer lifted only +0.08 over bare prompts. Honest null — persona panel-mode stays CUT, evidence-closed. | quant | `internal/bench/reports/persona-placebo.json#honest-null` | ✅ |
 | On the live end-to-end retrieval benchmark (9 tasks × 3 arms × 3 seeds on claude-haiku, fixture store with keyword-overlapping confusers), the memory retrieval substrate scored precision@5 = 100% (9/9) with 100% poisoned-entry rejection, and the retrieval-on arm passed 27/27 model-scored tasks vs 2/27 with retrieval off and 4/27 with a placebo injection. Known limit stays published: mean tie-set 4.1 means top-k ties break by store order, not relevance (the ADR-116/FTS5 signal). | quant | `internal/bench/reports/second-brain-retrieval.json#retrieval-on` | ✅ |
-| 104 governed rules. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| 105 governed rules. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | On a deterministic multi-session recall corpus, the memory substrate produces a measured, placebo-controlled recall lift — memory-on 27/27 vs no-memory 10/27 and vs equal-byte placebo 9/27 (claude-haiku-4-5, n=9 tasks x 3 seeds, sign test p=0.031 for BOTH pairings). Scoped honestly: this is the context-value upper bound (perfect retrieval on a one-fact-per-task corpus), not retrieval precision under a large store. | quant | `internal/bench/reports/second-brain-delta.json` | ✅ |
 | Removing the perfect-retrieval assumption, the substrate's REAL keyword retrieval recalls the needed decision into the top-5 under keyword-overlapping confusers (precision@5 9/9) and the model disambiguates it from the co-injected confusers — retrieval-on 27/27 vs no-memory 5/27 and vs equal-count placebo 5/27 (claude-haiku-4-5, 9 tasks x 3 seeds, sign test p=0.008 both). Named limit: retrieval RECALLS but does not RANK (mean tie-set 3.3, ties broken by store order, not relevance) — the discrimination gap that motivates the SQLite-FTS5 activation path (ADR-116) at larger scale. | quant | `internal/bench/reports/second-brain-retrieval.json` | ✅ |
 | Every artifact the package ships — source AND the condensed projection that reaches consumers — is machine-scanned in CI for hidden-Unicode, mixed-script-confusable, and instruction-smuggling payloads (the rules-file-backdoor class); a finding blocks the release before `npm publish`, not just the merge. | qual | `.github/workflows/publish-npm.yml#lint_agent_security` | ✅ |
-| 274 skills. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| 275 skills. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | Removes only its own keys from a shared host config (matched by JSON-pointer + SHA-256), never a neighbour tool's entries. | qual | `docs/contracts/install-layout.md#JSON-pointer` | ✅ |
 
 **21 backed claim(s)** — all evidence pointers resolve in CI.
@@ -56,7 +56,7 @@ guidelines, personas) are **generated from source and CI-drift-checked**:
 fails the build on any count-shaped prose mention that drifts from the
 source count — or on two different numbers for the same artefact kind.
 
-We also publish our **debt**: 4 claim(s) are logged as
+We also publish our **debt**: 5 claim(s) are logged as
 `unbacked` inventory in the ledger — not yet bound, and therefore not
 allowed to carry a marker in public prose. Hiding them would be the
 opposite of the point.
@@ -77,11 +77,11 @@ shipping theater; the full per-cell data is committed at
 `internal/bench/reports/persona-placebo.json`.
 
 **Behavioural-eval coverage — the honest baseline.** Skill *quality* is only
-as good as its measurement. Today **42 of 274** skills carry a behavioural
+as good as its measurement. Today **42 of 275** skills carry a behavioural
 `evals.json`; the highest-traffic / highest-cost tiers (default-surface +
 `rich` + routers) are **fully covered (35 of 35)**, the long tail
-(7 of 239) is not. We publish that gap rather than imply
-"274 evaluated skills": coverage is measured per tier
+(7 of 240) is not. We publish that gap rather than imply
+"275 evaluated skills": coverage is measured per tier
 (`./scripts-run src/scripts/skill_eval_coverage`), **CI-ratcheted so it can
 only rise**, and the priority tiers carry a hard **tier floor**: every
 rich / default-surface / router skill MUST have a behavioural eval or an

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "9.0.0",
+    "version": "9.2.0",
     "description": "Universal AI Agent OS — audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/src/agent-src/templates/scripts/work_engine/_lib/agent_settings.ts

@@ -252,7 +252,10 @@ const _AGENTS_DIR_MARKERS: readonly string[] = [
     'roadmaps',
     'settings/.ai-council.yml',
     'roadmaps-progress.md',
-    '.event4u-bridge.yml',
+    // `overrides/` is the guaranteed minimal-consumer surface (ADR-020).
+    // Replaced the retired `.event4u-bridge.yml` marker (ADR-020 amendment
+    // 2026-07-13) so a bare consumer `agents/` dir stays anchorable.
+    'overrides',
 ];
 
 /**