@event4u/agent-config 8.10.0 → 8.12.0

package/docs/decisions/INDEX.md

@@ -5,8 +5,8 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | # | Title | Status | Date | Supersedes |
 |---|---|---|---|---|
 | [ADR-001](ADR-001-kernel-swap-deferred.md) | Kernel Swap Deferred | accepted | 2026-05-06 | — |
-| [ADR-002](ADR-002-kernel-bucket-overrides.md) | Kernel Bucket Overrides | — | — | — |
-| [ADR-003](ADR-003-flat-cluster-subs-and-colon-syntax.md) | Flat Cluster Subs And Colon Syntax | — | — | — |
+| [ADR-002](ADR-002-kernel-bucket-overrides.md) | Kernel Bucket Overrides | accepted | 2026-05-06 | — |
+| [ADR-003](ADR-003-flat-cluster-subs-and-colon-syntax.md) | Flat Cluster Subs And Colon Syntax | accepted | 2026-05-07 | — |
 | [ADR-004](ADR-004-rule-governance-pruning.md) | Rule Governance Pruning | accepted | 2026-05-08 | — |
 | [ADR-005](ADR-005-subagent-worktrees.md) | Subagent Worktrees No Auto Merge | accepted | 2026-05-09 | — |
 | [ADR-006](ADR-006-skill-tools-python-pilot.md) | Skill Tools Python Pilot Pass | accepted | 2026-05-09 | — |
@@ -31,7 +31,7 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-025](ADR-025-workspace-chrome.md) | Workspace Chrome | accepted | 2026-05-24 | — |
 | [ADR-026](ADR-026-explain-mode-translation.md) | Explain Mode Translation | accepted | 2026-05-24 | — |
 | [ADR-027](ADR-027-changelog-machine-vs-manual.md) | Changelog Machine Vs Manual | accepted | 2026-05-25 | — |
-| [ADR-028](ADR-028-root-layout.md) | Root Layout | accepted | 2026-05-25 | — |
+| [ADR-028](ADR-028-root-layout.md) | Root Layout | superseded | 2026-05-25 | — |
 | [ADR-029](ADR-029-multi-workspace-deferred.md) | Multi Workspace Deferred | accepted | 2026-05-25 | — |
 | [ADR-030](ADR-030-claude-code-command-projection.md) | Claude Code Command Projection | accepted | 2026-05-28 | — |
 | [ADR-031](ADR-031-validation-severity-tiers-and-projection-roundtrip.md) | Validation Severity Tiers And Projection Roundtrip | accepted | 2026-05-29 | — |
@@ -41,7 +41,7 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-035](ADR-035-model-capability-tiers.md) | Model Capability Tiers | accepted | 2026-05-30 | 034 |
 | [ADR-036](ADR-036-global-install-browser-wizard-handoff.md) | Global Install Browser Wizard Handoff | accepted | 2026-06-01 | — |
 | [ADR-037](ADR-037-cost-profile-untangle.md) | Cost Profile Untangle | accepted | 2026-06-01 | — |
-| [ADR-038](ADR-038-canonical-settings-path.md) | Canonical Settings Path | — | — | — |
+| [ADR-038](ADR-038-canonical-settings-path.md) | Canonical Settings Path | accepted | 2026-06-01 | — |
 | [ADR-039](ADR-039-claude-skills-untracked.md) | Claude Skills Untracked | accepted | 2026-06-01 | — |
 | [ADR-040](ADR-040-execution-model-projection-time-filtering.md) | Execution Model Projection Time Filtering | accepted | 2026-06-02 | — |
 | [ADR-041](ADR-041-controlled-command-verbs.md) | Controlled Command Verbs | accepted | 2026-06-03 | — |
@@ -96,7 +96,7 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-090](ADR-090-visibility-command-frontmatter-field.md) | Visibility Command Frontmatter Field | accepted | 2026-06-13 | — |
 | [ADR-091](ADR-091-split-meta-capability-packs.md) | Split Meta Capability Packs | accepted | 2026-06-13 | — |
 | [ADR-092](ADR-092-defer-command-tier-alias-removal.md) | Defer Command Tier Alias Removal | accepted | 2026-06-13 | — |
-| [ADR-093](ADR-093-ai-council-config-user-global.md) | Ai Council Config User Global | accepted | 2026-06-13 | — |
+| [ADR-093](ADR-093-ai-council-config-user-global.md) | Ai Council Config User Global | superseded | 2026-06-13 | — |
 | [ADR-094](ADR-094-agent-memory-layer-removal.md) | Agent Memory Layer Removal | accepted | 2026-06-14 | — |
 | [ADR-095](ADR-095-workspace-boundary-contract.md) | Workspace Boundary Contract | accepted | 2026-06-14 | — |
 | [ADR-096](ADR-096-analysis-workbench.md) | Analysis Workbench | accepted | 2026-06-15 | — |
@@ -106,7 +106,7 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-100](ADR-100-global-knowledge-card-sharing.md) | Global Knowledge Card Sharing | accepted | 2026-06-15 | ADR-098 |
 | [ADR-101](ADR-101-ticket-bundle-emission.md) | Ticket Bundle Emission | proposed | 2026-06-15 | — |
 | [ADR-102](ADR-102-ticket-handoff-paste-and-mcp.md) | Ticket Handoff Paste And Mcp | accepted | 2026-06-16 | — |
-| [ADR-103](ADR-103-global-knowledge-default-off-until-measured.md) | Global Knowledge Default Off Until Measured | accepted | 2026-06-16 | — |
+| [ADR-103](ADR-103-global-knowledge-default-off-until-measured.md) | Global Knowledge Default Off Until Measured | superseded | 2026-06-16 | — |
 | [ADR-104](ADR-104-ai-council-config-global-only.md) | Ai Council Config Global Only | accepted | 2026-06-22 | 093 |
 | [ADR-105](ADR-105-automatic-subagent-orchestration.md) | Automatic Subagent Orchestration | accepted | 2026-06-23 | — |
 | [ADR-106](ADR-106-recursive-verification-benchmark-gate.md) | Recursive Verification Benchmark Gate | accepted | 2026-06-23 | — |
@@ -117,14 +117,18 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-111](ADR-111-canonical-glama-listing.md) | Canonical Glama Listing | accepted | 2026-07-07 | — |
 | [ADR-112](ADR-112-stdio-lite-stays-read-only.md) | Stdio Lite Stays Read Only | accepted | 2026-07-07 | — |
 | [ADR-113](ADR-113-ci-native-release-label-trigger.md) | Ci Native Release Label Trigger | accepted | 2026-07-08 | — |
-| [ADR-114](ADR-114-commit-policy-iron-law-override.md) | Commit Policy Iron Law Override | — | — | — |
+| [ADR-114](ADR-114-commit-policy-iron-law-override.md) | Commit Policy Iron Law Override | accepted | 2026-07-08 | — |
 | [ADR-115](ADR-115-command-cluster-consolidation-phase-4.md) | Command Cluster Consolidation Phase 4 | accepted | 2026-07-08 | — |
 | [ADR-116](ADR-116-memory-tripwire-activation-path.md) | Memory Tripwire Activation Path | accepted | 2026-07-08 | — |
-| [ADR-117](ADR-117-subagents-auto-default-on.md) | Subagents Auto Default On | accepted | 2026-07-09 | 105 |
+| [ADR-117](ADR-117-subagents-auto-default-on.md) | Subagents Auto Default On | accepted | 2026-07-09 | — |
+| [ADR-118](ADR-118-loop-engineering-boundaries.md) | Loop Engineering Boundaries | accepted | 2026-07-10 | — |
+| [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-200](ADR-200-python-to-typescript-migration.md) | Python To Typescript Migration | accepted | 2026-06-11 | — |
 
 ## Unnumbered (legacy)
 
 | # | Title | Status | Date | Supersedes |
 |---|---|---|---|---|
-| [ADR-rule-kernel-and-router](ADR-rule-kernel-and-router.md) | — | — | — | — |
+| [ADR-rule-kernel-and-router](ADR-rule-kernel-and-router.md) | Rule Kernel And Router Roadmap Closure | accepted | 2026-05-06 | — |

package/docs/design/council-vs-solo-baseline.md

@@ -0,0 +1,92 @@
+# Council-vs-solo baseline eval — design (pre-registered)
+
+> Design artifact for `road-to-feedback-8.11` Phase 3. It fixes the
+> methodology **before** the first billable call; the run itself is
+> spend-gated (blocker `council-baseline-spend-authorization` — the user
+> confirms the rendered estimate in-session). This document is the "design
+> the baseline" step — not the run. Companion claim:
+> `docs/CLAIMS.md § council-vs-solo-baseline` (status: unbacked until the run
+> resolves).
+
+## Why this exists
+
+The council deliberation protocol (stance tally, chairman, debate gates,
+anti-conformity) is well-built and default-off — but there is **no evidence
+that convening the council beats a single strong model** on any decision
+class. The 2026-07-12 feedback-disposition debate (claude-sonnet-4-5 +
+gpt-4o) REJECTED adding a ≥2-of-5 admission gate for exactly this reason and
+ADOPTED this baseline as the precondition for ANY further
+deliberation-protocol expansion: admission criteria must be derived from
+empirical decision characteristics, not a-priori heuristics.
+
+Shadow-log status at design time (2026-07-12): `agents/runtime/council/
+shadow-log.jsonl` is **absent/empty** on both the main checkout and the run
+worktree — the shadow-dispatch agreement mechanism has produced zero
+analyzable lines. That absence is itself the first finding: the only
+council-vs-solo signal the package planned to collect has no data, so a
+deliberate baseline run is the only path to a verdict.
+
+## Arms
+
+| Arm | What runs | Cost profile |
+|---|---|---|
+| A — solo | ONE strong model (the council's strongest configured member, single call, standard prompt) | 1 call/decision |
+| B — council | The full configured council in `debate` mode (2 members × ≤2 rounds, current defaults; stance tally ON so dissent is recorded) | 4–5 calls/decision |
+
+Same decision text, same context budget, both arms blind to each other.
+
+## Corpus — ≥30 real decisions
+
+- Source: real decision questions from the repo's own history — the
+  council-labelled golden set (labels final per the 2026-07-11 amendment; no
+  re-labelling) plus archived council question files whose ground-truth
+  disposition is now KNOWN (the decision shipped and survived, was reverted,
+  or was killed by later evidence). Minimum n = 30; pre-register the exact
+  list in the run manifest BEFORE the first call.
+- Class mix: at least 8 decisions per impact class {low, medium, high} so the
+  per-class analysis (the whole point — which characteristics correlate with
+  council lift) is not vacuous.
+
+## Metrics — fixed before data
+
+1. **Quality**: blind post-hoc grading of both arms' verdicts against the
+   known ground-truth disposition — primary judge = strongest available
+   model, blind second judge, report Cohen's κ (reuse `cohensKappa()` /
+   `judgeKappa()` from `src/scripts/check_quality_regression.ts`); verdict
+   admissible only at κ ≥ 0.60.
+2. **Cost**: tokens + USD (from the council cost ledger) + wall-clock per
+   decision, per arm.
+3. **Characteristics capture**: per decision, record the five feedback-
+   proposed dimensions (reversibility cost, material spend/risk,
+   multi-perspective conflict, evidence tension, policy/governance change) as
+   booleans AT PRE-REGISTRATION TIME (not after results) — so the ≥2-of-5
+   hypothesis is testable as a POST-HOc correlate without having gated
+   anything.
+
+## Kill criterion (falsifiable, from the 2026-07-12 debate)
+
+- **No lift anywhere**: if council decisions show no identifiable quality
+  lift on ANY decision subset (overall AND per impact class AND per
+  dimension-count stratum), further deliberation-protocol phases STOP and
+  the protocol goes maintenance-only; `road-to-opt-council-deliberation`
+  records the honest null.
+- **Lift on a subset**: derive empirical admission criteria FROM that
+  subset's recorded characteristics (which may or may not match the ≥2-of-5
+  heuristic — the data decides), and only then design an admission gate.
+- **Judge floor**: κ < 0.60 → record κ, withhold the win-rate, do not claim
+  either direction.
+
+## Spend gate
+
+Execution requires in-session user confirmation of the rendered estimate
+(existing council estimate machinery; ~30 decisions × (1 + ~4.5) calls —
+estimate rendered by `council estimate` at run time). Authoring the corpus
+manifest and this design is unblocked and free.
+
+## Non-goals
+
+- Not a cross-provider capability comparison (both arms use the configured
+  members; provider identity is held constant per arm definition).
+- Not a re-test of the deliberation features individually (stance tally,
+  chairman) — arm B runs the current default debate shape; feature ablations
+  are follow-ups only if B beats A at all.

package/docs/design/cross-model-parity-eval.md

@@ -0,0 +1,82 @@
+# Cross-model parity eval — re-scoped design
+
+> Design artifact for `road-to-opt-measurement-unblock` Phase 3 step 1. It
+> re-scopes the archive's most-deferred item (deferred across 4+ roadmaps) to the
+> **smallest capability** that produces a real cross-vendor parity signal, so the
+> build-vs-defer decision (step 2) rests on a concrete design, not the generic
+> "the harness doesn't exist". Writing this design is autonomous; **building and
+> running it is a maintainer cost decision** (step 2/3), disclosed and gated.
+
+## What changed since the last deferral
+
+| Original blocker | Status now |
+|---|---|
+| No delegable-task corpus | **RESOLVED** — `internal/bench/orchestration/corpus/` exists (`orch-*` orchestration tasks + `pv-*` production-validator tasks) |
+| Harness cannot execute model-emitted subagent calls | **STILL TRUE** — do not assume it away; re-scope around it |
+
+The corpus blocker no longer holds, so the item is re-openable — but only if we
+stop trying to build the thing that is still blocked (a full in-host harness that
+runs arbitrary model-emitted subagent calls).
+
+## The re-scope: council-transport execution, not an in-host harness
+
+**Don't** build a harness that executes model-emitted subagent calls end-to-end
+(the still-open blocker). **Do** reuse the capability that already exists: the AI
+council transport dispatches the *same* prompt to *multiple vendors* through
+`consult(members: ExternalAIClient[], …)` in
+[`src/scripts/ai_council/orchestrator.ts`](../../src/scripts/ai_council/orchestrator.ts).
+
+The smallest capability that yields a cross-model parity signal:
+
+1. **Task adapter.** Render each corpus task (`internal/bench/orchestration/corpus/*.md`)
+   into a single self-contained council prompt: the task + its rubric, asking the
+   model to *produce the findings it would surface* (not to actually spawn
+   subagents). This sidesteps the subagent-execution blocker — we measure the
+   model's **finding output on the delegable task**, not its ability to drive a
+   live subagent runtime.
+2. **≥ 2 vendors, same corpus.** Dispatch the identical prompt set to two distinct
+   vendors via the existing `ExternalAIClient` array — no new transport, no new
+   auth surface beyond what the council already has.
+3. **Per-host finding-count distribution.** For each (host × task), record the
+   count and the findings; aggregate to a per-host distribution over the corpus.
+4. **Blind judged quality (optional, gated).** If a quality signal beyond raw
+   counts is wanted, reuse the blind second-judge + Cohen's κ from
+   [`check_quality_regression.ts`](../../src/scripts/check_quality_regression.ts)
+   — the same discipline the Phase-1 rerun uses. This is the billable half; the
+   count distributions (step 3) are cheap and already informative.
+
+**Explicitly out of scope:** running the models' emitted subagent calls, a
+persistent multi-host runtime, any new vendor integration. If the signal needs
+more than council-transport can give, that is a *separate, later* build — named,
+not assumed.
+
+## What the signal feeds — `finding_floor` calibration
+
+`finding_floor` is an **inert mechanism today** (referenced in
+`run_skill_evals.ts` / `skill_linter.ts` / `evals.schema.json`); its recorded
+deferral reason was exactly the missing calibration input this eval produces. The
+per-host finding-count distributions calibrate the floor:
+
+- Derive the floor from the **cross-host lower envelope** (e.g. a low percentile of
+  the per-task finding counts across vendors) so the gate fires on a host/task that
+  under-produces relative to the cross-vendor norm, not relative to one vendor.
+- Once calibrated, promote `finding_floor` from inert to an **enforcing CI gate**
+  (its intended end state).
+
+## Build-vs-defer decision inputs (for step 2, maintainer)
+
+- **Cost:** the count-distribution pass (steps 1–3) is `N_tasks × N_vendors`
+  council calls — small and cheap; render the `council:estimate`-class disclosure
+  before the first call. The judged-quality half (step 4) roughly doubles it.
+- **Value:** unblocks `finding_floor` (arms a real CI gate) **and** produces the
+  first honest cross-vendor parity number the portfolio has ever had.
+- **Defer condition:** if built later, park with the concrete missing capability
+  named — here it would be "council-transport task-adapter for the orchestration
+  corpus", never the generic "harness doesn't exist".
+
+## Exit criteria mapping
+
+- This design doc **exists** (step 1 — done by writing this). ✓
+- Explicit **build/defer decision recorded** (step 2 — maintainer, cost attached). ⏳
+- If built: `finding_floor` calibration data exists and the gate is armed
+  (step 3 — gated on the decision + spend). ⏳

package/docs/design/length-neutral-judge-rerun.md

@@ -0,0 +1,92 @@
+# Length-neutral judge rerun — design
+
+> Design artifact for `road-to-opt-measurement-unblock` Phase 1. It fixes the
+> methodology **before** the first billable call; the run itself is a maintainer
+> `/dev/tty`-gated, money-moving execution (disclose the estimate, confirm the
+> budget in-session, then run). This document is the "design the rerun" step —
+> not the run.
+
+## Why a rerun
+
+The 2026-07-09 discipline-lift judge run was **inconclusive** and now gates ~40%
+of the active token-program portfolio. Three recorded failure modes made it
+un-trustworthy; each has a concrete fix below. Nothing ships from the prior run —
+its verdict is void, not "weakly positive".
+
+| # | Failure mode (2026-07-09) | Magnitude | Fix in this design |
+|---|---|---|---|
+| a | **Length confound** — the preferred arm was systematically longer, so the judge rewarded length, not discipline | 69% of variance | Length-matched pairs **and** a length-partialed rubric (both, belt-and-braces) |
+| b | **Judge inconsistency** — a single judge disagreed with itself / a second grader | 33% inconsistency | Stronger judge tier + a blind second judge, reported as Cohen's κ |
+| c | **Underpowered comparison** | p = 0.196 (n too small) | Pre-registered sample size from the golden corpus, fixed before the first call |
+
+## (a) Length confound — neutralise it two ways
+
+1. **Length-matched pairing.** For each decision task, constrain the two arms
+   (vanilla vs `essential` discipline) to within a **±15% token band** of each
+   other before judging. Pairs that cannot be matched within the band are
+   dropped from the primary analysis and reported separately (never silently
+   discarded). This removes length as a *between-arm* signal.
+2. **Length-partialed rubric.** The judge prompt scores **task quality only** and
+   is explicitly instructed that response length is **not** a quality signal;
+   the harness additionally records each response's token count and runs the
+   verdict through a length-partialed check — if the win-rate correlates with the
+   length delta (Spearman ρ over the surviving pairs), the run is flagged
+   `length-confounded` and the verdict is withheld, exactly as the exit criterion
+   demands ("no length confound flag").
+
+Both, not either: matching removes the gross effect, partialing catches residual
+leakage the band still admits.
+
+## (b) Judge inconsistency — stronger tier + a second judge, reported as κ
+
+- **Judge tier.** Use the strongest available judge model for the primary grade
+  (not the cheapest); the grading cost is a fraction of the generation cost and
+  judge quality is the binding constraint here.
+- **Blind second judge + Cohen's κ — reuse, do not rebuild.** The second-judge
+  agreement machinery already exists: `cohensKappa()` + `judgeKappa()` in
+  [`src/scripts/check_quality_regression.ts`](../../src/scripts/check_quality_regression.ts)
+  align two judges' per-pair winner labels by task id and return chance-corrected
+  κ. Run both judges **blind to arm labels** and to each other; report κ
+  **alongside every verdict**.
+- **κ floor.** The verdict is admissible only when **κ ≥ 0.60** (substantial
+  agreement). Below the floor, the win-rate rests on an unreliable grader — record
+  the κ, do **not** report the win-rate as a finding, and stop (see disposition).
+
+## (c) Underpowered — pre-register the sample size
+
+- **Corpus.** Draw decision tasks from the council-labelled golden set landed by
+  PR #885 (labels are final per the 2026-07-11 amendment — **no re-labelling**).
+- **Power target.** Pre-register n for **80% power** at the smallest
+  effect worth shipping (target: detect a **≥ 10pp** win-rate difference from 50%
+  at α = 0.05). Fix n **before** the first billable call; do not grow n after
+  seeing results (that is the p-hacking the prior run's `p = 0.196` invites).
+- **Statistic.** Paired win/loss over matched pairs → the exact binomial
+  sign-test (`signTestP` already in `second_brain_retrieval.ts`) or McNemar
+  (`bench_ab_v2_stats.ts`); report the two-sided p and the effect size, never a
+  bare "significant".
+
+## Report schema (verdict artifact)
+
+Written under `internal/bench/reports/` with, inline and non-optional:
+
+- per-arm win/loss/tie counts over the **surviving matched pairs** (+ the dropped-pair count);
+- **κ** (both judges) and the κ floor used;
+- the length-confound diagnostic (Spearman ρ of win-rate vs length delta) and the
+  pass/`length-confounded` flag;
+- pre-registered n, achieved power, and the sign-test / McNemar p + effect size;
+- a one-line **verdict**: `ships-lift` / `honest-null` / `inconclusive-<reason>`.
+
+## Disposition (Phase 1 step 4)
+
+- **Trustworthy verdict, either direction** (κ ≥ floor, no length flag, powered):
+  update the token-program tracking table in `road-to-token-proof-and-story.md`
+  and unblock/close the dependent gates.
+- **Second inconclusive:** record *why* with the diagnostics above and **stop** —
+  no third run without a further design change. The anti-pattern this roadmap
+  kills is "gate pending" with no diagnosis.
+
+## What this design does NOT decide
+
+The **execution** — the cost estimate, the in-session budget confirmation, and the
+paid paired run — is the maintainer's, disclosed and confirmed per the acceptance
+criteria. This document only makes the run, when authorized, trustworthy.

package/docs/design/utilization-window-criteria.md

@@ -0,0 +1,51 @@
+# Utilization-window decision criteria — pre-registered
+
+> Design artifact for `road-to-feedback-8.11-2` Phase 0. The engagement
+> observation window (telemetry.artifact_engagement, id-only,
+> PII-excluded-by-construction) has been RUNNING in the agent-config repo
+> since 2026-07-12. Per the repo's claims convention, the window's decision
+> rules are fixed HERE, BEFORE the numbers accumulate — the reviewer's
+> warning was precise: without pre-fixed criteria "the window ends with
+> many events and no decidable statement." Companion claim:
+> `docs/CLAIMS.md § utilization-window-decidability`.
+
+## Observation floor (all three, else "underpowered")
+
+1. **≥ 100 recorded task boundaries** in `.agent-engagement.jsonl`
+   (boundary_kind `task` or `phase-step`).
+2. **≥ 2 distinct hosts** contributed records (host identity read from the
+   session context at analysis time, not stored in the event — the event
+   schema stays id-only; if host cannot be attributed without widening the
+   schema, the floor degrades to "≥ 2 distinct recording periods ≥ 14 days
+   apart" and this deviation is recorded in the closing report).
+3. **≥ 45 elapsed days** since 2026-07-12.
+
+Below the floor at day 90 → the window is **underpowered**: extend ONCE by
+30 days. Still below → STOP, record the honest null ("insufficient natural
+usage volume to decide utilization"), and do NOT rebuild collection
+apparatus without a new demand signal.
+
+## Decision rules (fixed now — no goalpost-moving)
+
+| # | Observation at window close | Bound decision |
+|---|---|---|
+| D1 | Artifact kind entry (skill/rule/command/guideline/persona id) **loaded-never-consulted** across the full window (requires the U1a `loaded` denominator; if U1a has not landed, D1 degrades to consulted-set analysis and says so) | Goes on the **retirement-candidate list** feeding U1's ranked cut list — candidate, not auto-cut; kernel + safety floors exempt by construction |
+| D2 | Artifact **consulted-never-applied** with ≥ 5 consultations and applied-ratio < 10% | Goes on the **trigger-review queue** (description/trigger overhaul, not deletion) |
+| D3 | Window closes **above the floor** | The first U1 report MUST name ≥ 1 concrete keep/cut/review decision per artifact kind, or record per kind why the data does not support one |
+| D4 | Window closes **below the floor** (after the one extension) | Honest null; lifecycle-automation and field-outcome-ledger gates STAY closed (their revisit-if remains "≥ 1 full window") |
+
+## Explicitly out of scope for this window
+
+- **Outcome-quality attribution** (did artifact X improve the result) —
+  needs the `loaded` denominator plus far more volume; stays with U1a.
+- **Cost-vs-rework economics** — owned by the orchestration telemetry
+  track (`road-to-subagent-value-realization-followup`).
+- **Cross-repo aggregation** — the window is this repo only (council
+  condition from the 8.11 disposition).
+
+## Kill criterion
+
+If the window closes decidable (D3) but its decisions are cited by zero
+actual portfolio changes within 2 releases, the analysis layer (not the
+telemetry) is the dead weight — record that honest null before building
+any further reporting on top.

package/docs/featured-skills.md

@@ -1,6 +1,6 @@
 # Featured Skills
 
-A curated subset of the 270 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 271 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 270 skills: [`dist/agent-src/skills/`](../dist/agent-src/skills/) · all 177 commands: [`dist/agent-src/commands/`](../dist/agent-src/commands/)
+→ Browse all 271 skills: [`dist/agent-src/skills/`](../dist/agent-src/skills/) · all 178 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 270 skills, 103 governed rules, and 177 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 271 skills, 104 governed rules, and 178 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 103 rules. No configuration needed.
+This is enforced automatically by 104 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 177 active commands](../dist/agent-src/commands/)
+→ [Browse all 178 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 270 skills. `dist/router.json` (99 routed rules, intent →
+A prompt does not load all 271 skills. `dist/router.json` (100 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/agent-interaction-and-decision-quality.md

@@ -95,6 +95,74 @@ When making decisions:
 - Avoid rework caused by wrong assumptions
 - Prefer: short clarification early → correct implementation once
 
+## 8. Improve before implement — pre-implementation validation
+
+_Origin: migrated from `src/rules/improve-before-implement.md` per the P4 pattern of `road-to-kernel-and-router.md`. The rule keeps the activation lists and the golden rule ("Challenge to improve, never to refuse"); the check detail lives here._
+
+Before coding a new feature, refactor, module, or behavior-altering change, quickly verify:
+
+### 8a. Is the request clear?
+
+- Are acceptance criteria defined or derivable?
+- Is the scope bounded? (not "make it better" but "add X to Y")
+- Are edge cases considered?
+
+**If unclear** → ask ONE focused question. Max 2 questions, never an interrogation.
+
+### 8b. Does it fit the existing architecture?
+
+- Does similar functionality already exist?
+- Does it follow established patterns in the codebase?
+- Does it contradict existing conventions?
+- Do **multiple valid patterns/frameworks** already exist (e.g. Tailwind + Flux, multiple form libraries, competing state stores)? If yes, do NOT pick one arbitrarily — ask which to use.
+- Is the change a **second branch on the same discriminator** — second `match`/`switch` arm, second `if/elseif`, or second class hardcoded to one enum value (e.g. `Provider::FOO`, `'stripe'`)? If yes, run the Strategy sniff test before adding the branch — see [`strategy.md`](../php/patterns/strategy.md#sniff-test--when-an-enumstring-discriminator-wants-to-become-a-strategy).
+
+**If misfit** → show evidence (file references), propose alternative.
+**If multiple valid options** → list them, ask which to use. See [§ 2 — No blind implementation](#2-no-blind-implementation).
+
+### 8c. Is the approach sound?
+
+- Is there a simpler way to achieve the same result?
+- Are there known problems with the requested approach?
+- Does the scope match the stated goal? (not over-engineered, not under-specified)
+
+**If problematic** → explain the concern, propose a better approach.
+
+### How to challenge
+
+- **Be concise** — one sentence per concern, not paragraphs
+- **Show evidence** — reference existing code, patterns, or conventions
+- **Offer alternatives** — don't just say "this is wrong"
+- **Use numbered options** — let the user choose quickly
+- **Respect "just do it"** — if the user insists after your challenge, execute immediately
+
+Example:
+
+```
+> ⚠️ `UserService` already has a `deactivate()` method that covers this case.
+>
+> 1. Use existing method — extend with new parameter
+> 2. Create new method anyway — I'll explain the overlap in a comment
+> 3. Skip validation — implement as requested
+```
+
+After presenting concerns: user picks an option → execute immediately; user says "just do it" → execute immediately. Never argue twice about the same point. Never block work — delay is only justified if it prevents a clear mistake.
+
+### Scope limits
+
+- **Max 1-2 challenges per task** — not every request needs validation
+- **Max 1 minute of analysis** — if the check takes longer, skip it
+- **Never validate simple tasks** — only features, architecture, significant changes
+- **Never validate after the user already explained their reasoning**
+
+### Verify with concrete tools, not prose
+
+If the challenge requires you to confirm current behavior before proposing an alternative, use a concrete probe — a `curl` against the endpoint, a Playwright spec, a debugger / `xdebug` step-through, or the project's test runner with a targeted filter. Asserting current behavior from memory is not validation.
+
+### Intent inference (RDP, standard host)
+
+When the literal request and the underlying goal may differ, **state the inferred goal in one line and give ONE recommendation** — do not spread 2–3 framings (that is the overplanning [`direct-answers`](../../../src/rules/direct-answers.md) suppresses). Standard host only; a strong-reasoning host self-infers, so skip it there. Engage per [`rdp-gate`](../../../src/agent-src/contexts/execution/rdp-gate.md).
+
 ## Anti-patterns
 
 - Asking 5 complex questions at once

package/docs/guidelines/agent-infra/roadmap-progress-mechanics.md

@@ -155,11 +155,11 @@ when the diff is empty. The `command:` triggers on
 `/roadmap:process-*` run; the guard is the deterministic backstop
 that catches a forgotten flip per step rather than at run end.
 
-**In-progress marker:** when a step takes more than one reply,
-mark it `[~]` the moment work starts on it and regenerate. The
-user sees one row move from `[ ]` to `[~]` to `[x]` instead of
-silent rows. `[~]` is treated as open for `count_open` but moves
-the phase percentage forward in the dashboard.
+**`[~]` semantics — superseded note:** `[~]` is **not** an "in-progress"
+indicator (the earlier in-progress-marker guidance here is superseded by
+the glyph table in § Glyph semantics below — kept as the stronger, current
+source of truth). Mid-reply work-in-flight has no checkbox change until
+the step lands; that's a normal `[ ] → [x]` transition.
 
 ## Mechanics — triggers, regen command, self-check, failures
 
@@ -190,3 +190,78 @@ The hook implementation is the specification; on Copilot the agent
 runs the regenerator itself after the same triggers fire. Skipping
 it is a rule violation, not a hook gap — the Iron Law on dashboard
 sync survives the missing hook surface.
+
+## Migrated depth from the `roadmap-progress-sync` rule (per P4)
+
+The sections below carry the long-form body of the
+`roadmap-progress-sync` rule; the Iron-Law fences and the mandatory
+pre-send self-check stay in the rule itself.
+
+### Iron Law 2 — cadence detail
+
+`/roadmap:process-step`, `/roadmap:process-phase`, `/roadmap:process-full`, and any other multi-step autonomous run flip the box for step N **before** moving on to step N+1. The checkbox itself is the real-time monitor — the markdown file is the source of truth, the dashboard is a derived view.
+
+The `command:` triggers in the rule's frontmatter ensure it loads the moment one of the `/roadmap:process-*` commands is invoked and stays loaded for the whole run — independent of whether the agent is currently editing files under `agents/roadmaps/`. The loop carries its own deterministic flip-guard at `roadmap-process-loop § 5b` — defense-in-depth, not a substitute for the inline flip. (Merged with § Autonomous execution → "Deterministic flip-guard" above, which carries the concrete guard command.)
+
+**Step counts as done** when its code/doc change is written and saved AND the verification cited in the step has passed (fresh output in this reply or an earlier one). (Merged with § Autonomous execution → "Step counts as completed" above — same contract.)
+
+### Glyph semantics — single source of truth
+
+Keep aligned with the dashboard counter in `scripts/update_roadmap_progress.ts` (regenerated via `./agent-config roadmap:progress`) and the closure-table in the `roadmap-management` skill:
+
+| Glyph | Meaning | Counts towards |
+|---|---|---|
+| `[ ]` | open — planned, not yet done | `count_open` |
+| `[x]` | done — work landed + verified | `count_done` |
+| `[~]` | deferred — planned but not happening **this** run; resolution required before archive (Iron Law 3) | `count_deferred` |
+| `[-]` | cancelled — scope dropped, won't happen at all | `count_cancelled` |
+
+`[~]` is **not** an "in-progress" indicator. Mid-reply work-in-flight has no checkbox change until the step lands; that's a normal `[ ] → [x]` transition.
+
+**Dashboard regen cadence — opt-in batching.** The checkbox flip is non-batchable. The **subprocess regen** (`./agent-config roadmap:progress`) is batchable per `roadmap.dashboard_regen_cadence` in `.agent-settings.yml` (`per_step` default · `every_5_steps` · `phase_boundary`). Run end, phase boundary, and any file-shape touch (rename / phase add / archive — Iron Law 1) always force an immediate regen regardless of cadence.
+
+**Blockers follow the same cadence as checkboxes.** Clearing a `## Blockers` entry (per `templates/roadmaps.md` rule 20) flips its `Status: resolved` and regenerates the dashboard in the same reply — Iron Law 1's "same response" obligation applies to blocker resolution exactly as it applies to a checkbox flip.
+
+### Iron Law 3 — deferred-resolution flow
+
+When the closure check fires (`count_open == 0` and `count_deferred > 0`), the agent MUST:
+
+1. Enumerate every `[~]` step in the roadmap (phase + step text + any inline `<!-- deferred: ... -->` annotation).
+2. Present numbered options (per the `user-interaction` rule) — at minimum:
+   1. **Follow-up roadmap (draft)** — spawn `agents/roadmaps/road-to-<slug>.md` with `status: draft` frontmatter, `parent_roadmap: <this-slug>`, and the deferred steps lifted verbatim into phases. Draft stays hidden from the dashboard until the user flips it to `ready`.
+   2. **Follow-up roadmap (ready, blocked)** — spawn the file with `status: ready` (default), frontmatter `parent_roadmap: <this-slug>` plus a body note (`> Blocked until <condition>`) so the dashboard surfaces it but execution waits.
+   3. **Keep in this archive** — confirm the deferred items stay searchable in the archived file; no follow-up roadmap. Choosing this records an explicit decision-to-drop in the same reply.
+   4. **Restore selected items to `[ ]`** — finish them in this roadmap before archive.
+   5. **Convert selected items to `[-]` cancelled** — drop them with rationale recorded inline.
+3. Only after the user resolves the deferrals does the `git mv` to `archive/` run. The dashboard regen happens after the resolution, not before.
+
+The migration mechanics (file naming, frontmatter pattern, body shape, parent-back-link) live in `roadmap-management § Spawn follow-up from deferred items`. The rule owns the obligation; the skill owns the procedure.
+
+### Later disposition — detail
+
+`later/` is the fourth disposition alongside `archive/` (done, none planned) and `skipped/` (won't pursue): open work remains but is blocked-for-later. Set frontmatter `status: later` + a `Blocked until` / `Trigger` resume line, `git mv` to `agents/roadmaps/later/`, migrate inbound `agents/roadmaps/<x>.md` refs to the new path, regen. Open `[ ]` items stay open — the roadmap is parked whole, not cancelled or deferred-item-by-item. `later/` is excluded from the dashboard and `/roadmap:process-*` (same as `archive/`/`skipped/`); the `lint_roadmap_later_disposition` guard enforces the `status: later` ⇔ `later/` placement contract and that every parked roadmap records a resume condition. Procedure + the Active-vs-Later test live in the `roadmap-management` skill.
+
+### PR-gate — detail
+
+A roadmap that reaches `count_open == 0 && count_deferred == 0` is **complete**
+and is archived **in the same PR that completes it** — deterministically, by a
+script, before the PR exists. There is no "hold the last item open + archive
+manually after merge" step (that step got forgotten and left finished roadmaps
+rotting unarchived in the trunk — the exact failure this gate makes impossible).
+
+The sweep — `scripts/archive_completed_roadmaps.ts`, invoked by
+`/create-pr` § 1c — archives every roadmap that is
+complete **and** touched in this branch (`git log origin/main..HEAD`), `git mv`s
+it to `archive/`, migrates inbound `agents/roadmaps/<x>.md` references to the
+archive path in the **same branch** (so links never break — this was the only
+real reason the old design deferred archival), regenerates the dashboard, and
+stages it. Completion is read from the checkbox counts; no marker is required.
+
+**Backstop:** `./agent-config roadmap:progress-check` (wrapping `update_roadmap_progress.ts --check`) hard-fails when a roadmap
+hits `count_open == 0` while still under `agents/roadmaps/`. Because
+`/create-pr` archives before the push, the PR branch is green; a push that
+bypasses the sweep red-flags in CI — the forcing function that makes
+"finished roadmap left unarchived in the trunk" structurally impossible. Legacy
+`merge-gated` annotations are archived by the next `/create-pr` like any other
+completed roadmap; the dashboard still surfaces any stranded
+complete-but-unarchived roadmap so it can never hide inside a partial progress bar.