@event4u/agent-config 14.18.0 → 14.19.0

package/README.md

@@ -18,11 +18,30 @@
 
 **A deep library of skills, commands and governed rules** — plus a capability router that loads the right skill on intent and multi-agent orchestration with consensus review. The whole layer is compiled into **20 host agents** — of 23 detected, 3 being export-only<!-- claim:host-agent-count --> (Claude Code, Cursor, Augment, Cline, Windsurf, Copilot, Gemini CLI, Codex, Continue, Zed, JetBrains, Aider and more). **Resident processes are permitted only under the supervision contract ADR-249 establishes** — a policy this repository adopted on 2026-08-27, not a description of anything running today. Six role-shaped entry paths sit on top, so any host becomes a reliable team member — without locking you to a single model or vendor.
 
+## Try it in 30 seconds
+
+**Try one thing in 30 seconds** — before the full suite, drop in a single
+self-contained subagent and see the discipline on your own repo:
+
+```bash
+mkdir -p .claude/agents
+curl -fsSL https://raw.githubusercontent.com/event4u-app/agent-config/main/docs/wedge/production-validator/production-validator.md \
+  -o .claude/agents/production-validator.md
+# then in Claude Code:  @production-validator check this branch is actually done
+```
+
+`production-validator` is read-only and installs nothing else — it gates "done"
+by hunting mocks/stubs on the shipped path and demanding real-system evidence
+([what it does](docs/wedge/production-validator/README.md)). Like it? The full
+suite installs in one command — [Quickstart ↓](#quickstart).
+
+---
+
 ### What's different
 
-It is both deep **and** disciplined — and honest about what it deliberately is not:
+Deep **and** disciplined, and honest about what it deliberately is not:
 
-- **Depth that routes itself** — a deep skill and command library, with a capability router that loads the right one on intent, not a 500-artefact context dump.
+- **Depth that routes itself** — a capability router loads the right skill on intent, not a 500-artefact context dump.
 - **Governance on every host** — rules compiled into each tool's native format at projection time; deterministic runtime hooks added on hook-capable hosts. This config-space, host-agnostic governance is the moat ([the governance advantage](docs/governance-advantage.md) · [enforcement by host](docs/enforcement-by-host.md)).
 - **Surgical uninstall** — removes only its own keys from a shared host config (matched by JSON-pointer + SHA-256), never a neighbour tool's entries.<!-- claim:surgical-uninstall -->
 - **Pack-scoped install** — writes the active pack only, not a 500-artefact dump.
@@ -39,41 +58,31 @@ See exactly [what works on which host](docs/capability-matrix.md) or jump to [th
 
 ### Pick your profile — six entry paths
 
-`agent-config setup` writes `profile.id` to `.agent-settings.yml`; each
-anchor below is the first-screen the wizard sends you to. One README,
-six entries, no role-detection guesswork.
-
-| Profile (`profile.id`) | Audience | First commands | First skills |
-|---|---|---|---|
-| 👩‍💻 [`developer`](docs/profiles.md#profile-developer) | IC engineer | `/implement-ticket` · `/work` · `/review-changes` · `/fix` · `/commit` | `developer-like-execution` · `verify-completion-evidence` · `minimal-safe-diff` · `systematic-debugging` · `test-driven-development` |
-| ✍️ [`content_creator`](docs/profiles.md#profile-content_creator) | Writers, ghostwriters, marketers | `/work` · `/post-as` · `/ghostwriter` · `/optimize-prompt` · `/video:from-script` · `/video:storyboard` | `voice-and-tone-design` · `messaging-architecture` · `editorial-calendar` · `release-comms` · `character-consistency` |
-| 🚀 [`founder`](docs/profiles.md#profile-founder) | Solo / early-stage founder | `/work` · `/feature` · `/challenge-me` · `/council` | `refine-prompt` · `rice-prioritization` · `vision-articulation` · `fundraising-narrative` · `runway-cognition` |
-| 🏛 [`agency`](docs/profiles.md#profile-agency) | Multi-client delivery shop | `/work` · `/implement-ticket` · `/refine-ticket` · `/feature` · `/roadmap` | `doc-coauthoring` · `decision-record` · `refine-ticket` · `estimate-ticket` · `perf-feedback-craft` |
-| 💼 [`finance`](docs/profiles.md#profile-finance) | CFO / fractional finance / FP&A | `/work` · `/council` · `/challenge-me` | `dcf-modeling` · `forecasting` · `scenario-modeling` · `unit-economics-modeling` · `runway-cognition` |
-| 🛡 [`ops`](docs/profiles.md#profile-ops) | RevOps, support, SRE-adjacent | `/work` · `/threat-model` · `/review-changes` · `/fix` | `incident-commander` · `dashboard-design` · `logging-monitoring` · `threat-modeling` · `launch-readiness` |
-
-**Not sure which one?** Run `npx @event4u/agent-config init` then
-`agent-config setup` — the browser wizard asks a single 8-option role
-question and maps to the closest profile. Source-of-truth:
-[`src/agent-src/profiles/`](src/agent-src/profiles/) ·
-schema: [`docs/contracts/profile-system.md`](docs/contracts/profile-system.md).
-Beyond software: [`user-types/`](src/agent-src/user-types/)
-(galabau · metalworking · truck — see [Beyond software](#beyond-software).
-
-**Per-profile experience pages** (who it's for · first tasks · packs + flows ·
-what is *not* loaded · examples):
-[developer](docs/experiences/developer.md) ·
-[content_creator](docs/experiences/content_creator.md) ·
-[founder](docs/experiences/founder.md) ·
-[agency](docs/experiences/agency.md) ·
-[finance](docs/experiences/finance.md) ·
-[ops](docs/experiences/ops.md).
+`agent-config setup` writes `profile.id` to `.agent-settings.yml` and sends you
+to that profile's first screen. Each experience page carries the full detail —
+who it's for, first commands and skills, packs and flows, and what is
+deliberately *not* loaded.
+
+| Profile | Audience | Experience page |
+|---|---|---|
+| 👩‍💻 [`developer`](docs/profiles.md#profile-developer) | IC engineer | [page](docs/experiences/developer.md) |
+| ✍️ [`content_creator`](docs/profiles.md#profile-content_creator) | Writers, ghostwriters, marketers | [page](docs/experiences/content_creator.md) |
+| 🚀 [`founder`](docs/profiles.md#profile-founder) | Solo / early-stage founder | [page](docs/experiences/founder.md) |
+| 🏛 [`agency`](docs/profiles.md#profile-agency) | Multi-client delivery shop | [page](docs/experiences/agency.md) |
+| 💼 [`finance`](docs/profiles.md#profile-finance) | CFO / fractional finance / FP&A | [page](docs/experiences/finance.md) |
+| 🛡 [`ops`](docs/profiles.md#profile-ops) | RevOps, support, SRE-adjacent | [page](docs/experiences/ops.md) |
+
+**Not sure which one?** The wizard asks a single 8-option role question and maps
+to the closest profile. Source-of-truth
+[`src/agent-src/profiles/`](src/agent-src/profiles/) · schema
+[`docs/contracts/profile-system.md`](docs/contracts/profile-system.md) · beyond
+software [`user-types/`](src/agent-src/user-types/) (galabau · metalworking ·
+truck — see [Beyond software](#beyond-software)).
 
 ### Workflows, not raw commands
 
-You don't memorize every command — you run a **work journey**. Four flows span the
-developer story end-to-end; each names the command you TYPE to start and the
-skills it composes:
+You don't memorize commands — you run a **work journey**. Four flows span the
+developer story end-to-end:
 
 | Flow | Start with | The journey |
 |---|---|---|
@@ -82,9 +91,7 @@ skills it composes:
 | 🔎 **Review** | `/review-changes` · `/judge` | self-review → judge → quality-fix → threat-model |
 | 🚢 **Delivery** | `/commit` · `/pr:create` | commit in chunks → open PR → answer review |
 
-Full detail — entry commands, canonical path, composed skills per flow:
-[`docs/flows.md`](docs/flows.md). (`agent-admin` — memory / analytics / config —
-is platform operation, not a user-work flow.)
+Composed skills and the canonical path per flow: [`docs/flows.md`](docs/flows.md).
 
 <p align="center">
   <a href="CHANGELOG.md">CHANGELOG</a> ·
@@ -122,23 +129,19 @@ lists the end-to-end workflows (`/implement-ticket`, `/work`,
 Don't take the claims on trust — **verify them.** [`docs/proof.md`](docs/proof.md)
 is generated from source: a claim→evidence table (every public claim binds to a
 resolvable pointer or CI fails), honest-null benchmarks *including the runs where
-the package changed nothing* and a "verify it yourself" block you run on a fresh
-checkout. The proof page fails CI if it drifts from its sources — reproducibility
-is the proof. Browse it on the deployed docs site — the proof page is the primary entry:
-[event4u-app.github.io/agent-config/proof/](https://event4u-app.github.io/agent-config/proof/).
-The honest comparison frame lives at
-[`docs/us-vs-the-category.md`](docs/us-vs-the-category.md).
+the package changed nothing*, and a "verify it yourself" block you run on a fresh
+checkout. It fails CI if it drifts from its sources — reproducibility is the
+proof. Read it at
+[event4u-app.github.io/agent-config/proof/](https://event4u-app.github.io/agent-config/proof/),
+with the comparison frame at [`docs/us-vs-the-category.md`](docs/us-vs-the-category.md).
 Freshest measured row: in one post-fix session, advisory context injection cut language-mirror violations 555 → 19 while the two blocking guards went 8 → 0 and 1 → 0 — advisory reduced massively, only blocking eliminated. One session and a post-hoc reading, so a recorded prior rather than a law.<!-- claim:conformance-advisory-vs-blocking -->
 
 Maintaining a skills catalog yourself? The **anti-reskin gate** that blocks
-find-replace re-skin PRs here runs on your catalog too —
-[`docs/anti-reskin-gate.md`](docs/anti-reskin-gate.md).
+find-replace re-skin PRs here runs on yours too — [`docs/anti-reskin-gate.md`](docs/anti-reskin-gate.md).
 
-Audit-disciplined by construction — every memory consult, decision
-key and hook concern lands in `agents/runtime/state/` so you can replay it.
-[Core principles](#core-principles) names the four invariants;
-[What `agent-config` is — and what it isn't](#what-agent-config-is--and-what-it-isnt)
-draws the scope boundary.
+Audit-disciplined by construction — every memory consult, decision key and hook
+concern lands in `agents/runtime/state/` so you can replay it.
+[Core principles](#core-principles) names the four invariants.
 
 ## Contribute
 
@@ -154,30 +157,13 @@ opt-in measurement loop. Source-of-truth tree is
 
 ## Quickstart
 
-**Try one thing in 30 seconds** — before the full suite, drop in a single
-self-contained subagent and see the discipline on your own repo:
-
-```bash
-mkdir -p .claude/agents
-curl -fsSL https://raw.githubusercontent.com/event4u-app/agent-config/main/docs/wedge/production-validator/production-validator.md \
-  -o .claude/agents/production-validator.md
-# then in Claude Code:  @production-validator check this branch is actually done
-```
-
-`production-validator` is read-only and installs nothing else — it gates "done"
-by hunting mocks/stubs on the shipped path and demanding real-system evidence
-([what it does](docs/wedge/production-validator/README.md)). Like it? Install the
-full suite:
-
 **One command. Detection-driven — your installed AI tools are found and
 pre-selected. Nothing is written until you click Finish. No YAML by hand.**
 
-Those four are structural: they hold on every run, because they are properties
-of the code path rather than of your machine. How *long* it takes is not one of
-them — that is dominated by network and registry latency, which we do not
-control. The install → `doctor` wall-clock is measured by CI on every umbrella
-run and published with its conditions, as evidence; it is never a promised
-number.
+Those four are structural — properties of the code path, not of your machine.
+How *long* it takes is not: that is dominated by network and registry latency.
+CI measures the install → `doctor` wall-clock on every umbrella run and
+publishes it with its conditions, as evidence rather than as a promise.
 
 ```bash
 # 1. Install — on a terminal with a display, the browser wizard launches
@@ -191,18 +177,17 @@ npx -y @event4u/agent-config init
 /work "your first real task"
 ```
 
-**Headless / CI:** `init` skips the GUI automatically on CI, on a non-TTY, on a headless host, and whenever any CLI-mode flag is present — it then runs the non-interactive installer directly. The full opt-out set is listed once, against the code, in [`gui-wizard` § When the GUI is skipped](docs/contracts/gui-wizard.md#when-the-gui-is-skipped). Pass flags (`--profile=balanced --tools=claude-code,cursor`); add `--dry-run` to preview writes. The GUI and the CLI share one installer (`src/scripts/install.ts`), so both produce identical results. Reference: [`docs/wizard.md`](docs/wizard.md).
+**Headless / CI:** `init` skips the GUI on CI, a non-TTY, a headless host, or any CLI-mode flag, and runs the non-interactive installer instead. The GUI and the CLI share one installer (`src/scripts/install.ts`), so both produce identical results. Flags, the full opt-out set and `--dry-run`: [`docs/wizard.md`](docs/wizard.md) · [`gui-wizard` § When the GUI is skipped](docs/contracts/gui-wizard.md#when-the-gui-is-skipped).
 
-**Pick specific AIs:** `--tools=claude-code,cursor,augment,windsurf,cline,gemini-cli,copilot,roocode,aider,codex,claude-desktop,continue` (any subset). Visual picker: add `--gui` (loopback-bound, CSRF-gated; contract [`gui-wizard`](docs/contracts/gui-wizard.md)). `--gui` is an opt-in that forces the wizard past the TTY and headless checks — it does **not** override `CI`, `AGENT_CONFIG_NO_UI`, or a CLI-mode flag; combining it with one of those exits non-zero rather than quietly running the CLI install. On a headless host add `--allow-headless` and connect a browser to the printed URL.
+**Pick specific AIs:** `--tools=claude-code,cursor,augment,…` (any subset). `--gui` forces the loopback-bound, CSRF-gated picker past the TTY and headless checks; it does **not** override `CI`, `AGENT_CONFIG_NO_UI` or a CLI-mode flag, and combining it with one of those exits non-zero rather than quietly running the CLI install.
 
-**Verify hook coverage:** `npx @event4u/agent-config hooks:status` prints the per-platform matrix (`--strict` for CI, `--format json` for tooling).
+**Verify hook coverage:** `npx @event4u/agent-config hooks:status` (`--strict` for CI, `--format json` for tooling).
 
-> **Scope (v2.5+):** `init` writes **global** only — `~/.event4u/agent-config/`, `~/.claude/`, `~/.cursor/`, …. The project tree gets `agents/overrides/` only (the bridge marker was retired — ADR-020 amendment 2026-07-13; the global root resolves from `~/.event4u/agent-config`). `--project` is maintainer-only behind `AGENT_CONFIG_DEV_MODE=1` ([ADR-020](docs/decisions/ADR-020-global-only-consumer-scope.md), [dev-mode](docs/maintainers/dev-mode.md)).
+> **Scope (v2.5+):** `init` writes **global** only — `~/.event4u/agent-config/`, `~/.claude/`, `~/.cursor/`, …. The project tree gets `agents/overrides/` only. `--project` is maintainer-only behind `AGENT_CONFIG_DEV_MODE=1` ([ADR-020](docs/decisions/ADR-020-global-only-consumer-scope.md), [dev-mode](docs/maintainers/dev-mode.md)).
 
-Migrating from a v1.x install? `npx @event4u/agent-config migrate` — full notes in [`docs/migration/v1-to-v2.md`](docs/migration/v1-to-v2.md).
+Migrating from v1.x? `npx @event4u/agent-config migrate` — [`docs/migration/v1-to-v2.md`](docs/migration/v1-to-v2.md).
 
 ---
-
 ## What `agent-config` is — and what it isn't
 
 A **content layer** — skills, rules, commands, guidelines, personas — distributed via npm and projected into every supported AI tool's native config format. It follows the [Agent Skills open standard](https://agentskills.io).
@@ -316,7 +301,7 @@ Create the user file interactively: `/agents user init` ([schema](docs/contracts
 
 ### Self-hosted MCP on Cloudflare — zero local install
 
-Skills, commands, rules and guidelines can be served as an MCP endpoint from your own Cloudflare Worker — any MCP client (Claude Desktop, Claude Code, Cursor, Zed, Continue, hosted agents) talks to it over HTTP. Two auth modes: `public` (default, OSS read-only deploys) and `bearer-auth` (operator opt-in, `MCP-Token` Wrangler secret).
+Skills, commands, rules and guidelines can be served as an MCP endpoint from your own Cloudflare Worker, reachable over HTTP by any MCP client. Two auth modes: `public` (default) and `bearer-auth` (operator opt-in, `MCP-Token` Wrangler secret).
 
 ```bash
 task mcp:cloud:login         # one-time, opens browser
@@ -328,7 +313,7 @@ task mcp:cloud:secret-put    # opt in to bearer-auth (recommended for private de
 
 > **Scope — Lite, not Full.** The Worker serves read-only governance (skills · commands · rules · guidelines · contexts) as MCP prompts and resources, plus small read-only tools (`memory_lookup`, `chat_history_read`, `list_*`). It does **not** execute the repository's local scripts (linters, audits, `task ci`, work-engine hooks) — those require local install per [Quickstart](#quickstart).
 
-> The built-in **local stdio** server is listed for discovery in the [Glama MCP Registry](https://glama.ai/mcp/servers/event4u-app/agent-config) (agent developers / contributors; requires a local checkout, not a turnkey install — see [ADR-067](docs/decisions/ADR-067-glama-registry-listing.md)).
+> The built-in **local stdio** server is listed in the [Glama MCP Registry](https://glama.ai/mcp/servers/event4u-app/agent-config) — it requires a local checkout, not a turnkey install ([ADR-067](docs/decisions/ADR-067-glama-registry-listing.md)).
 
 ### Deployment posture
 
@@ -338,15 +323,13 @@ task mcp:cloud:secret-put    # opt in to bearer-auth (recommended for private de
 | **Small team (3–10 people)** | ✅ today | Shared `agents/overrides/` Git repo + shared NAS for knowledge — no code change, no new server. Recipe: [`docs/deploy/small-team-recipe.md`](docs/deploy/small-team-recipe.md) |
 | **Organization mode** (SSO · central policy · team context · internal connectors) | ⏸ not started | Each shape gated on a recruited customer + funded audit + maintainer ADR. Posture rationale: [`docs/deploy/team-deployment-posture.md`](docs/deploy/team-deployment-posture.md) |
 
-The Hard Floor on organization-mode features (SSO, central policy, OAuth connectors, team-context) is preserved by design — they stay cancelled until a real first customer + funded security audit lifts them. The small-team recipe is the supported path in the meantime.
-
-> *The 9.3/10 feedback round (2026-05-25) re-asked for OAuth knowledge connectors, IAM / org governance and organization-shared memory. Each is a stable cancellation row in [`team-deployment-posture`](docs/deploy/team-deployment-posture.md) under the same three release gates — recruited team customer · funded audit · maintainer ADR.*
+Organization-mode features (SSO, central policy, OAuth connectors, team-context) stay cancelled by design until a recruited customer and a funded security audit lift them; the small-team recipe is the supported path meanwhile. Each is a stable cancellation row in [`team-deployment-posture`](docs/deploy/team-deployment-posture.md).
 
 ---
 
 ## Harness expectations
 
-Three classes of install/runtime behaviour look like package bugs but are host-harness behaviour the package cannot control — sibling-plugin namespaces (`codex:*`, `cc-gemini-plugin:*`), deferred tools surfaced via `ToolSearch` and cross-scope skill drift (real bug, fixed in the distribution-channels track). Diagnostics + the package's response: [`docs/contracts/harness-expectations.md`](docs/contracts/harness-expectations.md). First step when a skill appears twice: `task probe:skills`.
+Three classes of install/runtime behaviour look like package bugs and are host-harness behaviour the package cannot control: sibling-plugin namespaces, deferred tools surfaced via `ToolSearch`, and cross-scope skill drift. Diagnostics and the package's response: [`docs/contracts/harness-expectations.md`](docs/contracts/harness-expectations.md). When a skill appears twice, start with `task probe:skills`.
 
 ## Supported tools
 
@@ -431,7 +414,7 @@ accepts a host-supplied config root so its own settings stay profile-scoped.
 
 ## Who this is for
 
-Stack-agnostic governance core (orchestration · role modes · command clusters · quality gates · audit-discipline) plus parallel stack-specific skill sets:
+A stack-agnostic governance core (orchestration · role modes · command clusters · quality gates · audit discipline), plus stack-specific skill sets:
 
 | Stack | Coverage |
 |---|---|
@@ -455,7 +438,7 @@ Three domain-safety rules ([`domain-safety-pii`](src/rules/domain-safety-pii.md)
 
 ### Code provenance & license governance
 
-Every diff is checked against a **license policy derived from the target repo's own detected license** (`LICENSE`/`package.json`/`composer.json`, precedence-ordered; sources disagree → escalate, never guess) and a **strict linter over our own borrow ledger** ([`provenance/borrows.jsonl`](provenance/) → [`docs/THIRD-PARTY-NOTICES.md`](docs/THIRD-PARTY-NOTICES.md)) that fails a deny-class license, an unknown license, a missing transformation note or a rename-only-phrased one — wired into `ci`/`ci-strict` from day one. A third piece, `license-compliance-audit`, runs an offline/online similarity scan on demand — a human invokes it deliberately, never a pipeline. This is **provenance-governed**, **license-policy-enforced** borrow discipline backed by an **audited borrow trail** — not a copy detector.
+Every diff is checked against a **license policy derived from the target repo's own detected license** (precedence-ordered; sources disagree → escalate, never guess) and a **strict linter over our borrow ledger** ([`provenance/borrows.jsonl`](provenance/) → [`docs/THIRD-PARTY-NOTICES.md`](docs/THIRD-PARTY-NOTICES.md)) that fails a deny-class or unknown license, a missing transformation note, or a rename-only-phrased one — wired into `ci`/`ci-strict`. `license-compliance-audit` runs a similarity scan on demand, invoked by a human and never by a pipeline. This is provenance-governed borrow discipline with an audited trail — not a copy detector.
 
 <!-- provenance-scope-box -->
 #### Scope & limits
@@ -517,71 +500,10 @@ layer`), the platform's concern chain, host hook registration, and router +
 projection freshness. Deeper hook internals (fail-open/closed posture, last
 dispatcher feedback per concern): `agent-config hooks:doctor`.
 
-### A new command / skill is missing in Claude Code after an upgrade
-
-Under the single-surface model, `agent-config upgrade` refreshes the
-`~/.claude/` file projection — that IS the content surface, so a fresh
-session picks the new commands up directly. If commands are still missing,
-the usual cause is a leftover **marketplace plugin**: it is a git-SHA
-snapshot that never moves with the npm upgrade and it shadows nothing —
-it just lists everything twice while lagging behind. Remove it:
-
-```bash
-claude plugin uninstall agent-config@event4u-agent-config
-```
-
-Then start a **new** Claude Code session. `agent-config doctor` reports a
-leftover plugin as `claude-plugin: duplicate surface`; hooks are unaffected
-(they live in a managed `~/.claude/settings.json` block — verify with the
-`hook-wiring` check).
-
-### Skills / commands appear twice in Claude Code
-
-Same cause as above: the deprecated marketplace plugin is installed next to
-the `~/.claude/` file projection, so every skill lists plain **and**
-`agent-config:`-prefixed. Uninstall the plugin (command above) and start a
-new session.
-
-### `agent-config upgrade` fails with `Unknown argument: --no-ui`
-
-Known bug in 8.2.0: `upgrade` passed a `--no-ui` flag that the install
-orchestrator did not accept yet, so the run aborted early. Fixed on `main`;
-until the next release, work around it with:
-
-```bash
-AGENT_CONFIG_NO_UI=1 agent-config global   # refresh the global install, no wizard
-```
-
-### Upgrade was interrupted (Ctrl-C, wizard closed, step failed)
-
-Only the initial `npm install -g` hard-aborts an upgrade. Every later step
-(global re-deploy with hook registration, settings sync, wrapper + git-hook
-refresh) runs independently — a single failed step is reported in the
-end-of-run summary instead of silently skipping the rest. Re-run
-`agent-config upgrade` to converge and use `agent-config doctor` to name
-anything left in a mixed state.
-
-### `agent-config: command not found` / hooks stopped firing
-
-Runtime hooks resolve the **global** binary on `PATH` — a project-local
-install alone is not enough for them. Reinstall the binary:
-
-```bash
-npm install -g @event4u/agent-config
-agent-config doctor   # verifies PATH + plugin wiring
-```
-
-### Project files look stale after a package update
-
-Project-local projections are only rewritten on an explicit refresh:
-
-```bash
-agent-config refresh             # re-apply the installed version to this project
-agent-config refresh --global    # same-version re-install of the global root
-```
 
-More per-version steps: [Migration](docs/MIGRATION.md) ·
-[getting-started § Keeping current](docs/getting-started.md#keeping-current).
+Upgrade and staleness symptoms — a command or skill missing after an upgrade,
+skills appearing twice, an interrupted upgrade, `command not found`, stale
+project files: [`docs/troubleshooting.md` § Upgrade and staleness](docs/troubleshooting.md#upgrade-and-staleness).
 
 ---
 

package/dist/agent-src/README.md

@@ -17,7 +17,7 @@ it as `.augment/` (local projection).
 ├── contexts/       # Background context documents for the agent
 ├── guidelines/     # Coding guidelines by language (reference material)
 ├── rules/          # Always-active behavior rules (auto-loaded every conversation)
-├── skills/         # On-demand expertise (matched by topic)
+├── skills/         # On-demand expertise (named or trigger-matched)
 └── templates/      # File templates for roadmaps, features, skills, etc.
 ```
 

package/dist/agent-src/commands/agent-handoff.md

@@ -65,9 +65,9 @@ exactly once, then deletes it). In a terminal-capable context, offer
 to spawn the fresh session directly:
 
 - `claude` — seeds via the session_start hook (clean first message).
-- `codex` — no hook surface there; the adapter passes the handoff as the
+- `codex` — this package binds no hook there; the adapter passes the handoff as the
   initial prompt instead. Same UX, different transport.
-- Bundle hosts without hooks (Antigravity, Copilot) → use `--print` and
+- Bundle hosts this package binds no hook on (Antigravity, Copilot) → use `--print` and
   copy-paste.
 
 ## Fallback mode — summarize the LIVE conversation (`--print`)

package/dist/agent-src/commands/review/changes.md

@@ -2,14 +2,14 @@
 model_tier: high
 name: review-changes
 pack: engineering-base
-intent: "Multi-judge review of the current diff — bugs, security, tests, quality, architecture"
-routes_to: [code-review, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, architecture-review-lens, overbuild-review-lens]
+intent: "Multi-judge review of the current diff — bugs, security, tests, quality, architecture, spec, overbuild"
+routes_to: [code-review, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, architecture-review-lens, judge-spec-compliance, overbuild-review-lens]
 replaces: []
 visibility: internal
 sub: changes
 cluster: review
-skills: [code-review, subagent-orchestration, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, architecture-review-lens, overbuild-review-lens, judge-synthesis, git-workflow]
-description: Self-review local changes before creating a PR — dispatches to six specialized judges (bug, security, tests, quality, architecture, spec) and consolidates verdicts
+skills: [code-review, subagent-orchestration, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, architecture-review-lens, judge-spec-compliance, overbuild-review-lens, judge-synthesis, git-workflow]
+description: Self-review local changes before creating a PR — dispatches to seven specialized judges (bug, security, tests, quality, architecture, spec, overbuild) and consolidates verdicts
 suggestion:
   eligible: false
   rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
@@ -24,7 +24,7 @@ packs:
 ## Instructions
 
 Review all uncommitted and committed-but-not-pushed changes against
-the default branch (`main`) by dispatching to six specialized judge
+the default branch (`main`) by dispatching to seven specialized judge
 sub-skills and consolidating their verdicts.
 
 ### 1. Update the current branch
@@ -109,7 +109,7 @@ folded together, a handover the reviewer could not parse would report as "there
 was nothing to check", which is the one outcome that hides a real failure
 behind a benign one.
 
-### 4. Dispatch to the six judges
+### 4. Dispatch to the seven judges
 
 Each judge receives **the same diff plus the task context** (ticket,
 PR body, commit messages) and runs independently. The judges are:
@@ -137,8 +137,8 @@ diff cannot answer about itself. It is dispatched on demand like the others, so
 it adds no standing token cost — verified: `check_preamble_payload_budget`'s
 measured total is unchanged by this routing.
 
-**Why the sixth exists, and why it is not a severity.** The other five all ask a
-craft-or-correctness question, so a change that is correct, clean, well-tested
+**Why the sixth exists, and why it is not a severity.** The five that preceded it
+all ask a craft-or-correctness question, so a change that is correct, clean, well-tested
 and architecturally sound — and **does not do what was asked** — used to pass
 this path with five green verdicts. Its finding does **not** enter the shared
 severity axis: `judge-synthesis` carries it on its own dimension, because "this
@@ -180,14 +180,14 @@ Read `verbosity.offer_council_in_delivery` from `.agent-settings.yml`
 - `true`: when `ai_council.enabled: true` **and** at least one member
   enabled, ask (in the user's language):
 
-  > 1. Add an external council review alongside the six internal judges? (billable)
+  > 1. Add an external council review alongside the seven internal judges? (billable)
   > 2. Skip — internal judges only
 
   Also suppress when `personal.autonomy: on` (council is billable).
 
 If picked **1**:
 
-- Run `/council diff:<base>..<head>` in parallel with the six
+- Run `/council diff:<base>..<head>` in parallel with the seven
   internal judges (or sequentially after them — whichever the
   dispatch mode picked in step 4 supports).
 - Treat each council member as one extra "judge" in the consolidated
@@ -202,12 +202,12 @@ If picked **2** → continue with internal judges only.
 
 ### 4b-fresh. The fresh reviewer — the one input with no implementation context
 
-The six judges above all read **the same diff plus the task context**, and on the common
+The seven judges above all read **the same diff plus the task context**, and on the common
 path they run in-session: the party that wrote the diff also reads it, with the whole
 implementation context in scope. That is a self-review, and calling it a review is the
 defect `road-to-review-independence` exists to close.
 
-So a **seventh input** is added, and its distinguishing property is a negative one: it
+So **one further input** is added, and its distinguishing property is a negative one: it
 has **no implementation context**. Not a new mechanism —
 [`dispatch_r2_reviewer.ts`](../../../../scripts/dispatch_r2_reviewer.ts) already derives
 the scope and persists the prompt it sent:
@@ -216,7 +216,7 @@ the scope and persists the prompt it sent:
 ./scripts-run src/scripts/dispatch_r2_reviewer --slug <slug> --base origin/main
 ```
 
-The six in-session judges stay exactly as they are. This is an addition, not a
+The seven in-session judges stay exactly as they are. This is an addition, not a
 replacement — a fresh reviewer is worse than a spec judge at spec compliance, and the
 point is not to be better at their job but to be uncontaminated by the author's framing.
 
@@ -262,7 +262,7 @@ Read `subagents.adversarial_council` from `.agent-settings.yml` (default
   which supplies the four slots, the one-question budget, and the storage line
   (not persisted: `subagents.adversarial_council` is class C). What only this
   command knows is *why now*: the diff is high-risk, and the offer is a paid
-  distinct-model red-team for finding coverage against the six internal judges.
+  distinct-model red-team for finding coverage against the seven internal judges.
 - `on`: run it automatically on a high-risk diff.
 
 When run, dispatch the
@@ -315,7 +315,7 @@ window back with `./scripts-run src/scripts/review_axis_report`; it reports
   before proceeding
 - If **any** judge returned `revise` → fix 🔴 findings automatically,
   ask before fixing 🟡 findings, report 🟢 as suggestions
-- If all six returned `apply` → the diff is ready; report and stop
+- If all seven returned `apply` → the diff is ready; report and stop
 
 **Opt-in (never auto-on):** when the `revise` findings are *test-driven*
 (failing checks, not subjective craft) and you want bounded auto-repair
@@ -360,7 +360,7 @@ Per `verbosity.routine_confirmations` (default `false`):
 ## Use this command when
 
 - Preparing a self-review before opening a PR
-- Stress-testing a local branch with the same six lenses a reviewer
+- Stress-testing a local branch with the same seven lenses a reviewer
   would apply
 - Sanity-checking a diff before handing it to `/create-pr`
 
@@ -389,6 +389,6 @@ Per `verbosity.routine_confirmations` (default `false`):
 
 - **LLM-as-a-Judge** — [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685)
   MT-Bench and Chatbot Arena — judging LLM outputs with LLM judges.
-  This command adapts the pattern by dispatching to six specialized
-  judges (bug, security, tests, quality) instead of a single generic
-  judge, and consolidating their verdicts.
+  This command adapts the pattern by dispatching to seven specialized
+  judges (bug, security, tests, quality, architecture, spec, overbuild)
+  instead of a single generic judge, and consolidating their verdicts.

package/dist/agent-src/commands/review.md

@@ -8,7 +8,7 @@ intent: "Review dispatcher — multi-judge self-review of the current diff, or r
 routes_to: [review-changes, review-routing]
 replaces: []
 visibility: advanced
-description: Review orchestrator — routes to changes (five-judge self-review of the local diff) and routing (compute reviewer roles + historical bug patterns)
+description: Review orchestrator — routes to changes (seven-judge self-review of the local diff) and routing (compute reviewer roles + historical bug patterns)
 cluster: review
 type: orchestrator
 suggestion:
@@ -49,7 +49,7 @@ Sub-command names match the locked contract in
 4. If the sub-command is unknown or missing, print the menu and ask — do not
    guess:
 
-   > 1. changes — five-judge self-review of the local diff (pre-PR)
+   > 1. changes — seven-judge self-review of the local diff (pre-PR)
    > 2. routing — suggest reviewers + surface matched historical bug patterns
 
 ## Rules

package/dist/agent-src/contexts/execution/host-capability-manifest.md

@@ -150,22 +150,49 @@ against — a reader then cannot tell whether a capability was tested.
   exactly the distinction, readable from `routing:doctor` without opening the
   file.
 
-### The four-part citation — a row without all four is not admissible
+### The five-part citation — a row without all five is not admissible
 
 1. **the host** — the platform key from `hook_manifest.yaml`;
 2. **the host version** at the time of observation;
 3. **the transcript or artefact reference** the observation is read from;
-4. **the date**.
+4. **the date**;
+5. **the expiry** — the date after which the observation stops being admissible.
 
 Worked example, which a later row can be pattern-matched against:
 
 ```
-// subagent_spawn: OBSERVED — claude (Claude Code, Opus 5 1M session, 2026-08-22)
+// subagent_spawn: OBSERVED — claude (Claude Code, Opus 5 1M session, 2026-08-22,
+//   expires 2027-08-22)
 //   agents/runtime/state/subagent-ledger/2026-08.jsonl: 445 `subagent_start`
 //   records and 420 stops carrying a measured `duration_ms`, i.e. 420 child legs
 //   whose start and stop pair. A measurable child duration is the criterion.
 ```
 
+### Why an expiry, and not just a date
+
+```
+A HOST FACT WITHOUT AN EXPIRY IS A CLAIM NOBODY EVER RE-CHECKS.
+AN EXPIRED FACT IS TREATED EXACTLY AS AN UNOBSERVED ONE.
+```
+
+The date says when it was true. Only the expiry says when someone must look
+again — and a fact with no such date is one nobody looks at again, which is how
+the same stale host claims survived three correction rounds in this tree. An
+observation is about a host version that ships on its own cadence, so its
+shelf-life is a property of the observation and belongs beside it.
+
+The expiry is **not** a claim that the capability lapses on that date. It is the
+date after which this tree stops treating the observation as current, which is a
+statement about the record, never about the host.
+
+The machine-readable twin of this field is `verified.expires` in
+`src/scripts/hooks/host_lowering.yaml`, the same discipline applied to hook
+lowering: `lint_hook_manifest` refuses an expired row that still carries a
+blocking binding and warns on every other lapse, and `host_semantics.ts` reads
+an expired row exactly as `verified: null`. A registry row here has no such
+gate — the criteria are applied by a human, deliberately (see above), so the
+expiry here is a written obligation and its enforcement is the reviewer.
+
 ### Pre-state, pinned so the Phase 2 diff reads as an addition
 
 At the commit this protocol landed on, the registry was exactly:

package/dist/agent-src/rules/autonomous-execution.md

@@ -67,7 +67,7 @@ ALLOWLIST > 20 ENTRIES IN ONE SESSION = THE LINTER IS WRONG.
 STOP. PROPOSE LINTER REDESIGN OR REMOVAL. DO NOT EXPAND THE ALLOWLIST FURTHER.
 ```
 
-Crossing 20 entries counts as the 3rd validation-target failure — fix the tool shape, not the list. Enforced at tool-call time by the `block-config-weakening` PreToolUse guard (`src/scripts/hooks/block_config_weakening.ts`) **on `claude`, the one host that both binds `pre_tool_use` and honours a deny**: it counts allowlist entries added per session, warns from 5, and blocks past 20. It is *bound* on augment and cowork as well, and ignored there — `host_semantics.ts` verifies claude alone, and both trampolines discard dispatcher output and `exit 0` unconditionally. Everywhere else the cap is model-carried and "enforced at tool-call time" is not a claim this rule can make. **Corrected 2026-08-17 in both directions:** this sentence used to certify augment, claude and cowork as the enforcing set (an over-claim of two hosts) and to explain the rest with "the guard has nowhere to bind" (false for cursor, cline and gemini, whose native pre-tool events `native_event_aliases` already maps onto `pre_tool_use` — unbound, not unbindable; only windsurf and copilot have no pre-tool surface). The four states are tabulated once in [`hook-architecture-v1 § Which hosts carry pre_tool_use`](../docs/contracts/hook-architecture-v1.md). Run `agent-config hooks:status` to see which slots are bound on the host you are actually on — the sibling rules `git-history-discipline` and `evaluator-independence` qualify the identical slot, and an unqualified claim here would read as a guarantee the manifest does not give. Baselines and budget thresholds warn only — a rising count there may be a legitimate ratchet reset, which the edit alone cannot distinguish. Verify with the narrowest tool that proves the target green (a single `curl` / Playwright spec for HTTP/UI, the test runner with a `--filter`, an `xdebug` step-through) — never a meta-pipeline as per-iteration probe. Failed-attempt detail, suppression-sweep equivalents, probe-efficiency detail, and adaptive effort & stop (RDP): [`autonomy-mechanics § Validation-loop budget`](../contexts/execution/autonomy-mechanics.md).
+Crossing 20 entries counts as the 3rd validation-target failure — fix the tool shape, not the list. Enforced at tool-call time by the `block-config-weakening` PreToolUse guard (`src/scripts/hooks/block_config_weakening.ts`) **on `claude`, the one host that both binds `pre_tool_use` and honours a deny**: it counts allowlist entries added per session, warns from 5, and blocks past 20. It is *bound* on augment and cowork as well, and ignored there — `host_semantics.ts` verifies claude alone, and both trampolines discard dispatcher output and `exit 0` unconditionally. Everywhere else the cap is model-carried and "enforced at tool-call time" is not a claim this rule can make. **Corrected 2026-08-17 in both directions:** this sentence used to certify augment, claude and cowork as the enforcing set (an over-claim of two hosts) and to explain the rest with "the guard has nowhere to bind" (false for cursor, cline and gemini, whose native pre-tool events `native_event_aliases` already maps onto `pre_tool_use` — unbound, not unbindable; only windsurf and copilot have no alias row). The four states are tabulated once in [`hook-architecture-v1 § Which hosts carry pre_tool_use`](../docs/contracts/hook-architecture-v1.md). Run `agent-config hooks:status` to see which slots are bound on the host you are actually on — the sibling rules `git-history-discipline` and `evaluator-independence` qualify the identical slot, and an unqualified claim here would read as a guarantee the manifest does not give. Baselines and budget thresholds warn only — a rising count there may be a legitimate ratchet reset, which the edit alone cannot distinguish. Verify with the narrowest tool that proves the target green (a single `curl` / Playwright spec for HTTP/UI, the test runner with a `--filter`, an `xdebug` step-through) — never a meta-pipeline as per-iteration probe. Failed-attempt detail, suppression-sweep equivalents, probe-efficiency detail, and adaptive effort & stop (RDP): [`autonomy-mechanics § Validation-loop budget`](../contexts/execution/autonomy-mechanics.md).
 
 Body migrated to `contexts/execution/autonomy-mechanics.md` (per P4 of `road-to-kernel-and-router.md`) — opt-in detection summary, task-scope shapes table, N=3 mechanics, allowlist-antipattern detail, probe efficiency, adaptive effort (RDP).
 Trigger-set above activates this routing on demand, independent of the discipline profile (ADR-110).

package/dist/agent-src/rules/git-history-discipline.md

@@ -86,6 +86,6 @@ Trigger-set above activates this routing on demand, independent of the disciplin
 - [`skill:git-workflow`](../skills/git-workflow/SKILL.md) — Safe Squash-After-Push protocol and Divergent-State Recovery decision tree.
 - `git … --no-verify` / `core.hooksPath` overrides — deterministically blocked by the `block-no-verify` PreToolUse guard (`src/scripts/hooks/block_no_verify.ts`, registered in `hook_manifest.yaml`) **on `claude`, the one host that both binds `pre_tool_use` and honours a deny**. It is *bound* on augment and cowork too, and ignored there. Everywhere else the Iron Laws above are model-carried and "deterministically blocked" is not a claim this rule can make. To check the host you are on rather than trusting this sentence, run `agent-config hooks:status`.
 
-  **Corrected 2026-08-17, in both directions, because this line was wrong on each side.** It read "the guard has nowhere to bind" on cursor, cline, windsurf, gemini and copilot — refuted for three of the five by the manifest's own `native_event_aliases` table, which already maps `preToolUse`, `PreToolUse` and `BeforeTool` onto `pre_tool_use`: there the guard is **unbound, not unbindable**, and only windsurf and copilot carry no pre-tool surface. And it certified augment, claude and cowork as the enforcing set — `host_semantics.ts` verifies **claude alone**, while the augment and cowork trampolines discard dispatcher output and `exit 0` unconditionally, so a guard bound there runs and is then ignored. Both halves are the same failure: a host-capability claim this tree never established. The four states are tabulated once in [`hook-architecture-v1 § Which hosts carry pre_tool_use`](../docs/contracts/hook-architecture-v1.md).
+  **Corrected 2026-08-17, in both directions, because this line was wrong on each side.** It read "the guard has nowhere to bind" on cursor, cline, windsurf, gemini and copilot — refuted for three of the five by the manifest's own `native_event_aliases` table, which already maps `preToolUse`, `PreToolUse` and `BeforeTool` onto `pre_tool_use`: there the guard is **unbound, not unbindable**, and only windsurf and copilot carry no pre-tool alias row here. And it certified augment, claude and cowork as the enforcing set — `host_semantics.ts` verifies **claude alone**, while the augment and cowork trampolines discard dispatcher output and `exit 0` unconditionally, so a guard bound there runs and is then ignored. Both halves are the same failure: a host-capability claim this tree never established. The four states are tabulated once in [`hook-architecture-v1 § Which hosts carry pre_tool_use`](../docs/contracts/hook-architecture-v1.md).
 
-  The frequency join in `check_enforcement_coverage.ts` reports this obligation uncovered on **four** platforms — cursor, cline, windsurf, gemini. It skips `fallback_only` platforms before computing, so copilot never appears in its output and must not be quoted as if it did; copilot is uncovered for the separate reason that it has no hook surface at all.
+  The frequency join in `check_enforcement_coverage.ts` reports this obligation uncovered on **four** platforms — cursor, cline, windsurf, gemini. It skips `fallback_only` platforms before computing, so copilot never appears in its output and must not be quoted as if it did; copilot is uncovered because this package binds nothing there.

package/dist/agent-src/rules/guidelines.md

@@ -21,7 +21,7 @@ Coding guidelines live under `docs/guidelines/` organized by language. **Always
 
 - **Guidelines** = detailed coding conventions (reference material, read on demand).
 - **Rules** = always-active behavior constraints (auto-loaded every conversation).
-- **Skills** = agent capabilities and workflows (matched by topic).
+- **Skills** = agent capabilities and workflows (named or trigger-matched).
 
 Guidelines are the "how to write code" docs. Rules enforce critical subsets automatically. Skills reference guidelines when performing related tasks.
 

package/dist/agent-src/rules/session-canary.md

@@ -157,8 +157,8 @@ audit should not re-open it.
 `user_prompt_submit` slot; its `stop` fires *after* the reply, so injecting
 there could not shape the reply the reminder is for, and counting it would be
 exactly the over-credit the frequency audit exists to remove. Augment therefore
-reports as an open gap rather than as covered. **Copilot** has no hook surface at
-all — this rule is the only carrier there; re-read it when the trigger fires.
+reports as an open gap rather than as covered. **Copilot** carries no binding here —
+this rule is the only carrier there; re-read it when the trigger fires.
 
 ## See also
 

package/dist/agent-src/rules/token-efficiency.md

@@ -53,7 +53,7 @@ Exempt — the file set is enumerated **before** the first read and each read is
 - the members of a directory listing or grep result being opened in turn;
 - a declared read protocol under [`context-hygiene`](context-hygiene.md).
 
-Not exempt, and still the failure this rule exists to catch: re-reading the *same* file hoping for a different answer, re-running a failing command unchanged, or widening a grep by one word at a time instead of thinking. The discriminator is **did the previous call change what I know** — not the tool name.
+Not exempt, and still the failure this rule exists to catch: re-reading the *same* file hoping for a different answer, re-running a failing command unchanged, or widening a grep by one word at a time instead of thinking. The discriminator is **did the previous call change what I know** — not the tool name. Nor `cd X && …`: `git -C`.
 
 ## Fresh Output Over Memory