@event4u/agent-config 8.4.1 → 8.6.0

package/docs/decisions/INDEX.md

@@ -117,6 +117,9 @@ _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-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-200](ADR-200-python-to-typescript-migration.md) | Python To Typescript Migration | accepted | 2026-06-11 | — |
 
 ## Unnumbered (legacy)

package/docs/featured-commands.md

@@ -11,7 +11,7 @@ A curated subset of the 124 active commands. Full set lives in
 | [`/implement-ticket`](../dist/agent-src/commands/implement-ticket.md) | Drive a Jira / Linear ticket end-to-end through refine → plan → implement → test → verify |
 | [`/work`](../dist/agent-src/commands/work.md) | Same end-to-end loop for a free-form prompt — confidence-band gated |
 | [`/fix ci`](../dist/agent-src/commands/fix.md) | Fetch CI failures from GitHub Actions and fix them |
-| [`/review-changes`](../dist/agent-src/commands/review-changes.md) | Self-review local changes before creating a PR (five judges) |
+| [`/review-changes`](../dist/agent-src/commands/review/changes.md) | Self-review local changes before creating a PR (five judges) |
 | [`/pr:create`](../dist/agent-src/commands/pr/create.md) | Create a GitHub PR with Jira-linked description |
 
 ## For everyone

package/docs/featured-skills.md

@@ -1,6 +1,6 @@
 # Featured Skills
 
-A curated subset of the ~218 active 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 264 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.
 
@@ -20,7 +20,7 @@ Each row links to the canonical artefact under `dist/agent-src/`. Substitutions
 | [`/refine-prompt`](../dist/agent-src/skills/refine-prompt/SKILL.md) | Reconstruct a free-form prompt into actionable AC + assumptions + confidence band before the engine plans |
 | [`/work`](../dist/agent-src/commands/work.md) | Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report |
 | [`/grill-me`](../dist/agent-src/commands/grill-me.md) | Interactive grill-style interview that sharpens a fuzzy plan / idea into a copyable Markdown pitch |
-| [`/optimize-prompt`](../dist/agent-src/commands/optimize-prompt.md) | Optimize a raw prompt for ChatGPT / Claude / Gemini via the 4-D methodology |
+| [`/optimize-prompt`](../dist/agent-src/commands/optimize/prompt.md) | Optimize a raw prompt for ChatGPT / Claude / Gemini via the 4-D methodology |
 | [`decision-record`](../dist/agent-src/skills/decision-record/SKILL.md) | Lock a trade-off — options · trade-offs · consequences — before the ADR file is written |
 | [`fundraising-narrative`](../dist/agent-src/skills/fundraising-narrative/SKILL.md) | Why-now / why-us / why-this framing, market-size reasoning, traction-story construction |
 | [`okr-tree-modeling`](../dist/agent-src/skills/okr-tree-modeling/SKILL.md) | Decompose a company objective into team OKRs; audit a draft tree for measurability and laddering |
@@ -67,7 +67,7 @@ Each row links to the canonical artefact under `dist/agent-src/`. Substitutions
 |---|---|
 | [`/work`](../dist/agent-src/commands/work.md) | Free-form prompt end-to-end loop — refine → plan → implement → test → verify, confidence-band gated |
 | [`/implement-ticket`](../dist/agent-src/commands/implement-ticket.md) | Drive a Jira / Linear ticket end-to-end — same loop, ticket-anchored |
-| [`/review-changes`](../dist/agent-src/commands/review-changes.md) | Self-review local changes before creating a PR — dispatches to five specialized judges and consolidates verdicts |
+| [`/review-changes`](../dist/agent-src/commands/review/changes.md) | Self-review local changes before creating a PR — dispatches to five specialized judges and consolidates verdicts |
 | [`/commit`](../dist/agent-src/commands/commit.md) | Stage and commit all uncommitted changes — splits into logical commits following Conventional Commits |
 | [`judge-bug-hunter`](../dist/agent-src/skills/judge-bug-hunter/SKILL.md) | Correctness review — null-safety, edge cases, off-by-one, races, error handling |
 | [`judge-code-quality`](../dist/agent-src/skills/judge-code-quality/SKILL.md) | Readability review — naming, single-responsibility, DRY, dead code, codebase-convention drift |
@@ -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 ~218 active skills: [`dist/agent-src/skills/`](../dist/agent-src/skills/) · all ~129 commands: [`dist/agent-src/commands/`](../dist/agent-src/commands/)
+→ Browse all 264 skills: [`dist/agent-src/skills/`](../dist/agent-src/skills/) · all 172 commands: [`dist/agent-src/commands/`](../dist/agent-src/commands/)

package/docs/flows.md

@@ -32,7 +32,7 @@ Explore, plan, estimate, refine, and investigate **before** building.
 Drive a prompt, ticket, or feature end-to-end through plan → implement → verify.
 
 - **Entry commands:** `/work` · `/implement-ticket` · `/feature:dev` · `/bug-fix`
-- **Canonical path:** `/work` → `/review-changes` → `/quality-fix` → `/commit`
+- **Canonical path:** `/work` → `/review changes` → `/fix quality` → `/commit`
 - **Skills:** `test-driven-development` · `code-review` · `systematic-debugging` · `git-workflow`
 
 ## 🔎 Review — *check it*
@@ -40,7 +40,7 @@ Drive a prompt, ticket, or feature end-to-end through plan → implement → ver
 Self-review, judge, quality-fix, and threat-model a change before it ships.
 
 - **Entry commands:** `/review-changes` · `/judge`
-- **Canonical path:** `/review-changes` → `/judge` → `/quality-fix` → `/threat-model`
+- **Canonical path:** `/review changes` → `/judge` → `/fix quality` → `/threat-model`
 - **Skills:** `code-review` · `adversarial-review` · `quality-tools` · `threat-modeling` · `receiving-code-review`
 
 ## 🚢 Delivery — *ship it*

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 ~210 skills, ~67 rules, and ~124 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 264 skills, 95 governed rules, and 172 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-laravel.md

@@ -30,7 +30,7 @@ The Laravel quality pipeline runs PHPStan + Rector + ECS, with Pest as the test
 
 - [`quality-tools`](../dist/agent-src/skills/quality-tools/SKILL.md) — PHPStan output triage, Rector apply, ECS fix.
 - [`pest-testing`](../dist/agent-src/skills/pest-testing/SKILL.md) — Pest test authoring patterns.
-- [`/quality-fix`](../dist/agent-src/commands/quality-fix.md) — runs the full pipeline and fixes reported errors.
+- [`/fix quality`](../dist/agent-src/commands/fix/quality.md) — runs the full pipeline and fixes reported errors.
 
 ## Docker and dev environment
 

package/docs/getting-started.md

@@ -39,8 +39,11 @@ project sees the new skills, rules, and hooks at once, no per-repo bump:
 ```bash
 agent-config upgrade            # fetch + install the latest globally (content + hooks)
 agent-config refresh --global   # idempotent re-install, same version
-agent-config refresh --project  # refresh a project's minimal surface — bridge
+agent-config init --project     # initialize a project's minimal surface — bridge
                                 # marker, agents/overrides/, .gitignore (no wizard)
+agent-config refresh --project  # refresh that surface (same writer, idempotent)
+agent-config config             # open the configuration GUI (global settings hub)
+agent-config config --project   # open the project configuration surface
 agent-config doctor             # PATH, hook wiring, duplicate surfaces, bridge presence
 ```
 
@@ -168,10 +171,10 @@ Your agent now understands slash commands:
 | `/fix ci` | Fetch and fix GitHub Actions failures |
 | `/optimize skills` | Audit skills, find duplicates, run linter |
 | `/feature plan` | Interactively plan a feature |
-| `/quality-fix` | Run and fix all quality checks |
+| `/fix quality` | Run and fix all quality checks |
 | `/chat-history import` | Pull a prior session into the current chat (resume) |
 
-→ [Browse all 166 active commands](../dist/agent-src/commands/)
+→ [Browse all 172 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 258 skills. `dist/router.json` (88 rules, intent →
+A prompt does not load all 264 skills. `dist/router.json` (91 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/5w2h-analysis.md

@@ -10,7 +10,7 @@ the **Reference-Guideline Sunset Policy** (see frontmatter `upstream` /
   — L1 Quick analysis depth.
 - [`refine-ticket`](../../../.agent-src.uncondensed/skills/refine-ticket/SKILL.md)
   — completeness check on a Jira / Linear ticket before estimation.
-- [`bug-investigate`](../../../.agent-src.uncondensed/commands/bug-investigate.md)
+- [`bug-investigate`](../../../.agent-src.uncondensed/commands/bug/investigate.md)
   — gap analysis on an incident report before forming a hypothesis.
 
 > **Core principle:** "Quality of decisions equals quality of questions

package/docs/guidelines/agent-infra/ios-simulator-guide.md

@@ -11,7 +11,7 @@
   capture, multi-device test sweeps.
 - Intended companions: `react-native-setup` skill (environment),
   `mobile-e2e-strategy` skill (framework selection), `playwright-testing`
-  / `e2e-plan` skills (cross-platform E2E strategy).
+  / `/tests e2e-plan` command (cross-platform E2E strategy).
 - **macOS-only:** Xcode + simctl + (optional) idb require a macOS host.
   On Linux/Windows this guideline is reference-only — no implementation
   recipes are portable.

package/docs/proof.md

@@ -26,14 +26,24 @@ evidence pointer, or `task check-claims` fails the build.
 
 | Claim | Kind | Evidence | Resolves |
 |---|---|---|---|
+| 172 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | 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` | ✅ |
+| On the READ-ONLY FAN-OUT slice family, tier-downshifted subagent dispatch (lite/haiku vs session-tier-proxy sonnet) nets a ≥30% USD-weighted token-cost reduction at held quality — measured 2026-07-08 (n=10 paired live dispatches, 20 telemetry lines): 10/10 exact-match on BOTH arms, 29.4% fewer raw tokens, 76.5% USD-weighted cost reduction at the 3x haiku↔sonnet price ratio. FAMILY-SCOPED — the mechanical-edit family is unmeasured and its downshift (incl. the deferred tier downgrades of existing units) stays gated. Negative control held: an open-ended synthesis/unknown slice never resolves below the session tier (inferSliceTier → medium/inherit, never lite). | quant | `internal/bench/routing-downshift/results-2026-07-08.md#FAMILY-SCOPED PROVE` | ✅ |
 | The lift-carrying essential cut (kernel + downstream-changes) keeps a significant weak-host discipline lift at a fraction of the full load's tokens, and the lift is FAMILY- and HOST-SCOPED — measured on three hosts: claude-haiku-4-5 (weak) shows the family-scoped lift (trapE 0.533→1.000, 7/7 discordant, corpus cost 1.71x); claude-sonnet-4-6 (strong) is a ceiling null; gpt-5-mini (non-Claude weak, codex prompt-prepend surface) FAILED replication with headroom (corpus Δ=+0.024 p=0.70, capability trend n.s. — no harm claimed, injection-surface confound documented). Therefore discipline_profile: auto enables the lift only where measured (vendor-granular unknown_defaults). Non-claims — the balanced router profile was removed after a NULL measurement (p=0.81, n=24); no full-tier recommendation exists; no cross-vendor lift is claimed. | quant | `docs/benchmark.md#REPLICATION FAILED` | ✅ |
 | The whole layer is compiled into host agents with zero runtime daemon. | qual | `docs/contracts/no-runtime-boundary.md#file-first, no-runtime suite` | ✅ |
+| 95 governed rules. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| 264 skills (README hero + feature list). | 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` | ✅ |
 
-**4 backed claim(s)** — all evidence pointers resolve in CI.
+**8 backed claim(s)** — all evidence pointers resolve in CI.
 
-We also publish our **debt**: 4 claim(s) are logged as
+Artefact counts in public prose (skills, commands, governed rules,
+guidelines, personas) are **generated from source and CI-drift-checked**:
+`update_counts.ts` writes the numbers, `check_artefact_count_messaging.ts`
+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**: 1 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.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "8.4.1",
+    "version": "8.6.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,
@@ -38,6 +38,8 @@
         "dist/",
         "docs/",
         "src/scripts/",
+        "src/server/schemas/",
+        "src/shared/",
         "src/install/",
         "src/agent-src/scripts/",
         "src/agent-src/templates/scripts/",

package/src/agent-src/README.md

@@ -42,7 +42,7 @@ For full details see [augment-infrastructure.md](contexts/augment-infrastructure
 |---|---|
 | `/agent-handoff` | Generate context summary for a fresh chat |
 | `/fix-pr-comments` | Fix all open PR review comments |
-| `/quality-fix` | Run PHPStan + Rector and fix errors |
+| `/fix quality` | Run PHPStan + Rector and fix errors |
 | `/create-pr` | Create a GitHub PR with description |
 | `/bug-investigate` | Investigate a bug from Jira/Sentry |
 | `/tests-create` | Write tests for current changes |

package/src/agent-src/templates/scripts/work_engine/stack/runner.ts

@@ -11,7 +11,7 @@
  * runner and quality tools does this stack actually use, and what is the
  * exact command to invoke them?* It is the engine behind 6.1.0 Step 6 — the
  * toolchain resolver that lets one set of commands (`/tests execute`,
- * `/tests create`, `/quality-fix`, `/review-changes`, `/work`) adapt to
+ * `/tests create`, `/fix quality`, `/review changes`, `/work`) adapt to
  * phpunit / pest / vitest / jest / playwright / pytest / go / cargo instead
  * of exploding into per-stack command variants.
  *

package/src/config/agent-settings.template.yml

@@ -460,7 +460,7 @@ quality:
   #         tokens. The user runs quality tools manually; remote CI is
   #         the authoritative gate. The agent runs a quality tool ONLY
   #         when one of three triggers fires:
-  #           1. the user explicitly asks this turn (e.g. /quality-fix),
+  #           1. the user explicitly asks this turn (e.g. /fix quality),
   #           2. CI / the remote pipeline reports a concrete failure —
   #              then run exactly that failing check to reproduce + fix,
   #           3. the new-gate carve-out below.

package/src/install/selectedTools.ts

@@ -1,14 +1,20 @@
 /**
- * Persisted record of the AI tools the user actually selected in the wizard,
- * at `~/.event4u/agent-config/wizard-tools.json`. This is the user's prior
- * *selection* — distinct from `installed.lock` (every tool agent-config was
- * deployed to, which for an `--tools=all` install is the full set) and from
- * machine tool *detection*.
+ * Persisted record of the AI tools AND capability packs the user actually
+ * selected in the wizard, at `~/.event4u/agent-config/wizard-tools.json`.
+ * This is the user's prior *selection* — distinct from `installed.lock`
+ * (every tool agent-config was deployed to, which for an `--tools=all`
+ * install is the full set) and from machine tool *detection*.
  *
  * Written by the apply route on a real (non-dry-run) wizard-v2 apply, and
- * read by `detect-tools` so Step 1 pre-selects exactly the prior selection on
- * a repeat run. Empty / missing → first run → Step 1 falls back to
- * pre-selecting every installed tool.
+ * read by `detect-tools` / the manifest endpoint so a repeat run pre-selects
+ * exactly the prior selection. Empty / missing → first run → Step 1 falls
+ * back to pre-selecting every installed tool.
+ *
+ * `packs` was added by road-to-setup-experience (council 2026-07-08,
+ * lockfile-extension over settings-YAML surgery): the `packs:` list in
+ * `.agent-settings.yml` is only rendered into FRESH settings files, so on
+ * machines with an existing file the selection was never persisted anywhere
+ * — the wizard forgot installed packs between runs.
  *
  * `AGENT_CONFIG_WIZARD_TOOLS` overrides the path (tests only).
  */
@@ -23,17 +29,39 @@ function selectedToolsPath(): string {
     return resolve(homedir(), '.event4u', 'agent-config', 'wizard-tools.json');
 }
 
-export function writeSelectedTools(tools: string[]): void {
+export function writeSelectedTools(tools: string[], packs?: string[]): void {
     try {
         const path = selectedToolsPath();
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-        writeFileSync(path, `${JSON.stringify({ tools }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+        // Preserve a previously recorded packs list when the caller does not
+        // pass one (older call sites) — never silently drop the selection.
+        const record: { tools: string[]; packs?: string[] } = { tools };
+        const packsToWrite = packs ?? readSelectedPacks();
+        if (packsToWrite.length > 0 || packs !== undefined) record.packs = packsToWrite;
+        writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
     } catch {
         // Best-effort: a failed write just means the next run falls back to
         // pre-selecting installed tools.
     }
 }
 
+/**
+ * Return the recorded pack selection, or `[]` when absent / unreadable.
+ * Optionally intersect with the known-pack set so a stale id never surfaces.
+ */
+export function readSelectedPacks(knownIds?: ReadonlySet<string>): string[] {
+    try {
+        const raw = readFileSync(selectedToolsPath(), 'utf8');
+        const parsed = JSON.parse(raw) as { packs?: unknown };
+        const packs = Array.isArray(parsed.packs)
+            ? parsed.packs.filter((p): p is string => typeof p === 'string')
+            : [];
+        return knownIds === undefined ? packs : packs.filter((p) => knownIds.has(p));
+    } catch {
+        return [];
+    }
+}
+
 /**
  * Return the recorded selection, or `[]` when absent / unreadable. Optionally
  * intersect with the known-tool set so a stale id never surfaces.

package/src/scripts/_cli/cmd_converge.ts

@@ -250,6 +250,37 @@ export interface MainOptions {
     err?: OutSink;
 }
 
+/**
+ * Live-session notice for reaped Claude Code plugin caches — or null when no
+ * reap touched `~/.claude/plugins/`.
+ *
+ * Removing an installed plugin's cache does NOT reach into Claude Code
+ * sessions that are already running: they registered the plugin's hooks at
+ * session start and keep firing them, so every subsequent event logs
+ * `Failed to run: Plugin directory does not exist: …/plugins/cache/… — run
+ * /plugin to reinstall` until the session restarts. Claude Code's own
+ * `/plugin to reinstall` hint would recreate exactly the duplicate surface
+ * converge just removed — the correct remedy is a restart, so converge says
+ * so explicitly (road-to-truth-and-reference-hygiene follow-up, 2026-07-08).
+ */
+export function live_session_notice(executed_reaps: readonly string[]): string | null {
+    const hit = executed_reaps.some((r) => r.startsWith('~/.claude/plugins/'));
+    if (!hit) {
+        return null;
+    }
+    return (
+        '⚠️  Live-session note: Claude Code sessions that were ALREADY RUNNING still\n' +
+        '    hold the removed plugin\'s hook registrations. Until you restart them,\n' +
+        '    every event logs a non-blocking\n' +
+        '      "Failed to run: Plugin directory does not exist: …/plugins/cache/…"\n' +
+        '    error. This is cosmetic for new sessions but means the affected LIVE\n' +
+        '    session\'s plugin-sourced hooks no longer run — restart Claude Code\n' +
+        '    sessions to clear it. Do NOT follow the error\'s "/plugin to reinstall"\n' +
+        '    hint: reinstalling recreates the duplicate surface converge just removed\n' +
+        '    (the ~/.claude/ file projection already carries content AND hooks).'
+    );
+}
+
 export function main(argv: string[] | null = null, opts: MainOptions = {}): number {
     let args: Args;
     try {
@@ -329,6 +360,7 @@ export function main(argv: string[] | null = null, opts: MainOptions = {}): numb
     // Perform the cleanup — matrix-declared actions ONLY.
     let failures = 0;
     const report: string[] = [];
+    const executed_reaps: string[] = [];
     for (const f of findings) {
         if (f.command) {
             _print(out, `→ ${f.command}`);
@@ -351,6 +383,7 @@ export function main(argv: string[] | null = null, opts: MainOptions = {}): numb
             try {
                 fs.rmSync(abs, { recursive: true, force: true });
                 report.push(`${f.tool}: reaped package-tagged orphan \`${reap}\``);
+                executed_reaps.push(reap);
                 _print(out, `→ reaped ${reap}`);
             } catch (e) {
                 failures += 1;
@@ -367,6 +400,11 @@ export function main(argv: string[] | null = null, opts: MainOptions = {}): numb
     if (report.length === 0) {
         _print(out, '  (no actions completed)');
     }
+    const notice = live_session_notice(executed_reaps);
+    if (notice !== null) {
+        _print(out);
+        _print(out, notice);
+    }
     _print(
         out,
         'Rollback hint: a removed Claude Code plugin can be reinstalled with\n' +

package/src/scripts/_cli/cmd_doctor.ts

@@ -2,8 +2,8 @@
 /**
  * `agent-config doctor` — install + manifest health report (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_doctor.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_doctor.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * report lines (✅/❌/⚠️/⏭️ glyphs, ordering, fix hints), same filesystem
  * semantics. No behaviour changes — latent quirks are replicated, not fixed.
@@ -731,6 +731,7 @@ const CHECK_IDS = [
     'scope',
     'global-binary',
     'claude-plugin',
+    'claude-command-wrappers',
     'surface-state',
     'hook-wiring',
     'stale-orphans',
@@ -745,6 +746,7 @@ const CHECK_IDS = [
     'council-cli',
     'unsupported-combos',
     'wizard-state',
+    'settings-review-pending',
 ] as const;
 
 /** Checks that need only the project root and run regardless of a lockfile. */
@@ -752,6 +754,7 @@ const GLOBAL_CHECK_IDS: ReadonlySet<string> = new Set([
     'scope',
     'global-binary',
     'claude-plugin',
+    'claude-command-wrappers',
     'surface-state',
     'hook-wiring',
     'stale-orphans',
@@ -762,6 +765,7 @@ const GLOBAL_CHECK_IDS: ReadonlySet<string> = new Set([
     'tier-usage-readiness',
     'council-cli',
     'wizard-state',
+    'settings-review-pending',
 ]);
 
 /** Checks that genuinely cannot run without the project manifest. */
@@ -1077,6 +1081,69 @@ function _check_claude_plugin(): Dict {
     };
 }
 
+/**
+ * Claude Code flat-command discovery mitigation (council 2026-07-08,
+ * cc-user-command-discovery): Claude Code ≤ 2.1.204 does not register FLAT
+ * user-scope command files (`~/.claude/commands/<name>.md`) — nested
+ * commands and user-scope skills do. The installer therefore projects
+ * tier-0/1 visible flat commands as skill wrappers. This check flags the
+ * silent-failure state: a projection deployed by an OLDER release that
+ * still carries visible flat commands without wrappers (users see
+ * "Unknown command" for /commit etc. with zero error anywhere).
+ * Probe = `commit` (the canonical always-shipped visible flat command);
+ * static file checks only — never a live model call.
+ */
+function _check_claude_command_wrappers(): Dict {
+    const claude = shutilWhich('claude');
+    if (claude === null) {
+        return {
+            id: 'claude-command-wrappers',
+            status: 'skipped',
+            message: 'Claude Code CLI not on PATH — wrapper check not applicable',
+            remedy: '',
+        };
+    }
+    const anchor = path.join(os.homedir(), '.claude');
+    const commands_dir = path.join(anchor, 'commands');
+    if (!isDir(commands_dir)) {
+        return {
+            id: 'claude-command-wrappers',
+            status: 'skipped',
+            message: 'no ~/.claude/commands projection — nothing to check',
+            remedy: '',
+        };
+    }
+    const flat_probe = fs.existsSync(path.join(commands_dir, 'commit.md'));
+    const wrapper_probe = fs.existsSync(path.join(anchor, 'skills', 'commit', 'SKILL.md'));
+    if (wrapper_probe) {
+        return {
+            id: 'claude-command-wrappers',
+            status: 'ok',
+            message:
+                'flat-command skill wrappers present (Claude Code flat-command ' +
+                'discovery workaround active)',
+            remedy: '',
+        };
+    }
+    if (flat_probe) {
+        return {
+            id: 'claude-command-wrappers',
+            status: 'warn',
+            message:
+                'visible flat commands deployed WITHOUT skill wrappers — Claude Code ' +
+                '\u2264 2.1.204 does not register flat user-scope command files, so ' +
+                '/commit and other visible commands appear as "Unknown command"',
+            remedy: 'agent-config refresh --global (re-deploys with the wrapper projection)',
+        };
+    }
+    return {
+        id: 'claude-command-wrappers',
+        status: 'skipped',
+        message: 'no visible flat commands in the projection — nothing to wrap',
+        remedy: '',
+    };
+}
+
 /**
  * Matrix-driven duplicate-surface check (road-to-install-path-convergence
  * Phase 2): reads src/config/surface-matrix.yml and flags every tool whose
@@ -1167,6 +1234,7 @@ function pathExistsAny(p: string): boolean {
     }
 }
 
+
 /**
  * Managed hook wiring (single-surface model): the deterministic hook matrix
  * must be registered in ~/.claude/settings.json AND the dispatch target
@@ -1900,6 +1968,43 @@ function _check_wizard_state(): Dict {
     };
 }
 
+/**
+ * Pending settings-surface review (road-to-settings-change-review): the
+ * installer writes `state/settings-delta.json` when an upgrade changed
+ * defaults / enum vocabularies / added settings. The flag persists until
+ * the user resolves the review form (`agent-config config` → Settings →
+ * banner) — this check keeps it visible in every doctor run.
+ */
+function _check_settings_review_pending(): Dict {
+    const delta_pth = path.join(user_global_paths.event4u_root(), 'state', 'settings-delta.json');
+    if (!pathExists(delta_pth)) {
+        return {
+            id: 'settings-review-pending',
+            status: 'ok',
+            message: 'no pending settings-surface changes',
+            remedy: '',
+        };
+    }
+    let summary = '';
+    try {
+        const data = JSON.parse(readText0(delta_pth)) as {
+            oldVersion?: string;
+            newVersion?: string;
+            changes?: unknown[];
+        };
+        const n = Array.isArray(data.changes) ? data.changes.length : 0;
+        summary = `${n} change${n === 1 ? '' : 's'} (${data.oldVersion ?? '?'} → ${data.newVersion ?? '?'})`;
+    } catch {
+        summary = 'unreadable delta file';
+    }
+    return {
+        id: 'settings-review-pending',
+        status: 'warn',
+        message: `settings surface changed on upgrade — ${summary} awaiting review`,
+        remedy: 'agent-config config (Settings → “Review changes” banner)',
+    };
+}
+
 interface JsonDecodeError {
     msg: string;
     lineno: number;
@@ -2008,6 +2113,7 @@ function _run_checks(
         scope: () => _check_scope(project_root),
         'global-binary': () => _check_global_binary(project_root),
         'claude-plugin': _check_claude_plugin,
+        'claude-command-wrappers': _check_claude_command_wrappers,
         'surface-state': _check_surface_state,
         'hook-wiring': _check_hook_wiring,
         'stale-orphans': _check_stale_orphans,
@@ -2028,6 +2134,7 @@ function _run_checks(
         'council-cli': () => _check_council_cli(project_root),
         'unsupported-combos': () => _check_unsupported_combos(manifest),
         'wizard-state': _check_wizard_state,
+        'settings-review-pending': _check_settings_review_pending,
     };
     const out: Dict[] = [];
     for (const cid of CHECK_IDS) {
@@ -2082,6 +2189,7 @@ function _run_checks_no_manifest(
         scope: () => _check_scope(project_root),
         'global-binary': () => _check_global_binary(project_root),
         'claude-plugin': _check_claude_plugin,
+        'claude-command-wrappers': _check_claude_command_wrappers,
         'surface-state': _check_surface_state,
         'hook-wiring': _check_hook_wiring,
         'stale-orphans': _check_stale_orphans,
@@ -2096,6 +2204,7 @@ function _run_checks_no_manifest(
         'council-cli': () => _check_council_cli(project_root),
         'unsupported-combos': () => _skipped_manifest_check('unsupported-combos'),
         'wizard-state': _check_wizard_state,
+        'settings-review-pending': _check_settings_review_pending,
     };
     const out: Dict[] = [];
     for (const cid of CHECK_IDS) {
@@ -2572,6 +2681,7 @@ export {
     _check_lockfile_freshness,
     _check_global_binary,
     _check_claude_plugin,
+    _check_claude_command_wrappers,
     _check_bridge_drift,
     _check_mcp_mode,
     _check_offline_readiness,
@@ -2582,6 +2692,7 @@ export {
     _check_council_cli,
     _check_unsupported_combos,
     _check_wizard_state,
+    _check_settings_review_pending,
     _run_checks,
     _skipped_manifest_check,
     _check_bridge_drift_no_manifest,

package/src/scripts/_cli/cmd_explain.ts

@@ -3,8 +3,8 @@
  * `agent-config explain` — print the decision chain behind an outcome
  * (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_explain.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_explain.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output. No behaviour changes — latent quirks are replicated, not fixed.
  *

package/src/scripts/_cli/cmd_export.ts

@@ -2,8 +2,8 @@
  * `agent-config export` — eject a tool's canonical content into the project
  * (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_export.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_export.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same filesystem effects. No behaviour changes; latent quirks are
  * replicated and flagged inline, not fixed.
@@ -19,7 +19,7 @@
  *   and never calls `process.exit()`. argparse usage errors throw
  *   `ArgparseExit(2)`; `-h`/`--help` throws `ArgparseExit(0)`.
  * - The 9 marker constants and templates resolve to the same byte content as
- *   the Python originals: marker constants are re-exported from the
+ *   the retired Python implementations: marker constants are re-exported from the
  *   `install.ts` twin (single source of truth); templates are read from
  *   `dist/agent-src/templates` via `_from_template` exactly as Python does.
  * - `hashlib.sha256(content.encode("utf-8")).hexdigest()` →

package/src/scripts/_cli/cmd_fleet.ts

@@ -43,7 +43,19 @@ export interface FleetRepo {
     readonly tools?: string;
 }
 
-/** Parsed fleet config. */
+/**
+ * Parsed fleet config.
+ *
+ * INPUT-SCHEMA STABILITY: **stable, v1** (marked 2026-07-08,
+ * road-to-truth-and-reference-hygiene P3 — the output report was versioned
+ * from day one via {@link FleetReport.schema_version}; the input contract
+ * deserves the same explicitness). The accepted `fleet.yaml` shape is
+ * `repos: [<path-string> | {path, tools?}]` + optional `max_concurrency`;
+ * unknown keys are IGNORED (tolerant reader — forward-compatible by
+ * construction). Additive optional keys bump nothing; a breaking key
+ * rename/removal or semantics change requires an explicit `schema_version`
+ * field in the input and a reader that accepts the versionless v1 form.
+ */
 export interface FleetSpec {
     readonly repos: readonly FleetRepo[];
     readonly maxConcurrency: number;