@event4u/agent-config 16.5.0 → 17.0.0

package/CONTRIBUTING.md

@@ -332,6 +332,44 @@ the policy is interpreted as follows:
 | **Minor** (x.X.0) | New skills, rules, commands, or guidelines. New tool support. New installer flags. New `.agent-settings.yml` keys with safe defaults. |
 | **Patch** (x.x.X) | Wording fixes and improvements in existing skills, linter fixes, CI changes, documentation updates, internal refactors with no user-visible effect. |
 
+Consumer impact: a commit states what it costs a consumer in a
+`Consumer-Impact:` Git trailer (for a squash merge, in the squash commit's
+body). A trailer counts only in a trailer block: a paragraph in which every
+line is a `Key: value` trailer (an indented line continues the one above). That
+block need not be the final paragraph — a GitHub squash merge keeps each
+squashed commit's trailers in an earlier paragraph and ends the body with its
+own `Co-authored-by:` paragraph. The same line anywhere else — quoted in prose,
+or inside a code fence — is ignored. The key is spelled exactly
+`Consumer-Impact` and the value is exactly one of the lowercase words `none` |
+`automatic` | `notice` | `action`. A misspelt key (`consumer-impact`), an
+unknown value, or two `Consumer-Impact` trailers with different values in one
+block make the trailer invalid; a repeated identical trailer is accepted. When
+several blocks carry a valid value (a squash of several commits), the most
+severe one counts, as it does across a release span.
+
+- `none` — nothing a consumer can observe.
+- `automatic` — the update handles it; the consumer does nothing.
+- `notice` — the consumer should read the release notes.
+- `action` — the consumer must do something or the install breaks.
+
+An optional `Security: yes` trailer, in any trailer block, marks a security
+fix. A commit with no valid `Consumer-Impact:` trailer is recorded as `none`,
+with the absence kept. A breaking commit should carry a valid trailer; one that
+lost it — a squash merge that dropped the commit bodies, say — is recorded as
+`none` like any other, and `task release` does not refuse it. A commit is
+breaking when any of these holds, whether or not its subject is a Conventional
+Commit: a `!` before the colon of a conventional subject (`feat!:`,
+`feat(api)!:`); `BREAKING CHANGE` or `BREAKING-CHANGE` anywhere in the subject;
+or a body line that starts with `BREAKING CHANGE:` or `BREAKING-CHANGE:`, in
+any paragraph. Until the
+numbering model is decided, the trailer is recorded and the bump table above
+is unchanged — a breaking commit, by the rule above, is still a major.
+
+Settings keys: A settings key may be removed or renamed in a minor release
+only when no consumer project can rely on it — default-neutral and derivable,
+proven by a named test; any other removal or rename ships only in a major, and
+a renamed key's alias is dropped only in a major.
+
 Release notes live in [`CHANGELOG.md`](CHANGELOG.md) and are generated by
 `scripts/release.py` from [Conventional Commits](#commit-conventions) since
 the last tag. Contributors do **not** edit the changelog by hand; writing
@@ -536,6 +574,15 @@ push / PR. If `administration: write` becomes unacceptable, swap to
 a fine-grained PAT in repo secrets and document the rotation cadence
 here.
 
+The apply job reads that fine-grained `RELEASE_PR_TOKEN` and fails at
+its first step when the secret is missing. It never runs `npm ci`: it
+fetches only `yaml` at the version `package-lock.json` pins, checks the
+tarball against the lockfile's integrity hash, and runs
+`sync_github_metadata.ts` under plain `node --experimental-strip-types`,
+so no devDependency executes where the admin token is readable. The
+dry-run job installs the full tree and holds only the read-only Actions
+token.
+
 ## License of contributions
 
 By contributing you agree that your contributions are licensed under the

package/README.md

@@ -1,14 +1,14 @@
 <p align="center"><a href="https://event4u.app"><img alt="event4u Agent Config" src=".github/assets/banner.png"></a></p>
 
-# Agent Config — every claim machine-checked, including the counts in these badges
+# Agent Config — every claim machine-checked, including the artifact counts in these badges
 
-[![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config) [![MCP Toplist](https://mcptoplist.com/badge/glama%2Fevent4u-app%2Fagent-config.svg)](https://mcptoplist.com/server/glama%2Fevent4u-app%2Fagent-config)
+[![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config) [![MCP Toplist](https://mcptoplist.com/badge/glama%2Fevent4u-app%2Fagent-config.svg)](https://mcptoplist.com/server/glama%2Fevent4u-app%2Fagent-config) [![downloads](https://img.shields.io/npm/dm/@event4u/agent-config?style=flat-square&label=downloads%2Fmonth&color=orange)](https://www.npmjs.com/package/@event4u/agent-config)
 
-[![Skills](https://img.shields.io/badge/Skills-300-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-122-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-205-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-121-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/) <!-- claim:published-artifact-counts -->
+[![Skills](https://img.shields.io/badge/Skills-301-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-122-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-209-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-121-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/) <!-- claim:published-artifact-counts -->
 
-<sub>**How these are counted** — one canonical counter, `agent-config` → `update_counts --check`, re-derives all six from the tree and fails CI on a drift of one. Two bases are not what the linked directory shows, so they are stated here rather than left to be inferred: **Commands 205** counts every command file **recursively** (the linked directory holds 60 at its top level), and **Rules 121** counts the **source** rules while the linked projection holds 120 — one rule is dormant and is not projected. **Personas 29** excludes the directory README. Counts are of files and directories: none of them measures quality, activation, or adoption. <!-- claim:published-artifact-counts --></sub>
+<sub>**How these are counted** — one canonical counter, `agent-config` → `update_counts --check`, re-derives all six from the tree and fails CI when one is off by one. Two bases are not what the linked directory shows, so they are stated here rather than left to be inferred: **Commands 209** counts every command file **recursively** (the linked directory holds 62 at its top level) and **Rules 122** counts the **source** rules while the linked projection holds 121 — one rule is dormant and is not projected. **Personas 29** excludes the directory README. Counts are of files and directories: none of them measures quality, activation or adoption. <!-- claim:published-artifact-counts --></sub>
 
-**Try it in 30 seconds** — drop one read-only subagent into any repo and watch it gate "done": `@production-validator check this branch is actually done`. No wizard, no lock-in, nothing else installed — the [30-second wedge ↓](#quickstart) is the whole first step. Start at the proof, not the catalog: **[event4u-app.github.io/agent-config/proof/](https://event4u-app.github.io/agent-config/proof/)**.
+**Try it in 30 seconds** — drop one read-only subagent into any repo and watch it check "done": `@production-validator check this branch is actually done`. No wizard, no lock-in, nothing else installed — the [30-second wedge ↓](#quickstart) is the whole first step. Start at the proof, not the catalog: **[event4u-app.github.io/agent-config/proof/](https://event4u-app.github.io/agent-config/proof/)**.
 
 ![The trust surface running green — every "verify it yourself" command from a real, CI-re-executed run](docs/media/proof-demo.gif)
 
@@ -16,7 +16,7 @@
 
 > **Choose your experience — developer · founder · content · agency · finance · ops. Add packs. Get a focused command set, not a 500-artefact dump.** Bring your own AI provider.
 
-**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.
+**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 policy](docs/decisions/ADR-249-supervised-resident-process-permitted-under-governance.md) this repository adopted on 2026-08-27** — a rule, 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
 
@@ -51,14 +51,14 @@ suite installs in one command — [Quickstart ↓](#quickstart).
 
 ### What's different
 
-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 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.
+- **Governance on every host** — rules compiled into each tool's native format; 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** — its own keys in a shared config, never a neighbour's<!-- claim:surgical-uninstall -->; under `--purge`, only files it recorded, never the anchor<!-- claim:uninstall-purge-inventory-bounded -->.
+- **Pack-scoped install** — writes active pack plus dependencies; others are owed [reach](./docs/decisions/ADR-289-skills-owe-reach-not-presence.md).
 
-**What it deliberately is *not*** — the core is a governance layer with optional, individually opt-in embedded engines (code intelligence, gated reach, the setup GUI, the bench lab — [ADR-124](docs/decisions/ADR-124-embedded-engine-doctrine.md)): **no mandatory or always-on daemon, no separate state database, no self-rewriting memory, no auto-build pipeline.** Engines are never mandatory, never default-on without measured lift, and terminate with the command that invoked them. The host agent runs the loop; every learned change is human-reviewed; the same layer stays portable across tools. Capability without a process to babysit.
+**What it deliberately is *not*** — the core is a governance layer with optional, individually opt-in embedded engines (code intelligence, gated reach, the setup GUI, the bench lab — [the embedded-engine doctrine](docs/decisions/ADR-124-embedded-engine-doctrine.md)): **no mandatory or always-on daemon, no separate state database, no self-rewriting memory, no auto-build pipeline.** Engines are never mandatory, never default-on without measured lift and terminate with the command that invoked them. The host agent runs the loop; every learned change is human-reviewed; the same layer stays portable across tools. Capability without a process to babysit.
 
 > **Where this comes from (honest provenance).** The skills, rules and personas
 > are distilled from real production work on TypeScript and PHP codebases. The
@@ -72,7 +72,7 @@ See exactly [what works on which host](docs/capability-matrix.md) or jump to [th
 
 `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
+who it's for, first commands and skills, packs and flows — and what is
 deliberately *not* loaded.
 
 | Profile | Audience | Experience page |
@@ -141,7 +141,7 @@ 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
+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/),
@@ -179,9 +179,9 @@ publishes it with its conditions, as evidence rather than as a promise.
 
 **The one command is [above ↑](#try-it-in-30-seconds).**
 
-**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).
+**Headless / CI:** `init` skips the GUI on CI, a non-TTY, a headless host or any CLI-mode flag; it 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,…` (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.
+**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; 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` (`--strict` for CI, `--format json` for tooling).
 
@@ -192,7 +192,7 @@ Migrating from v1.x? `npx @event4u/agent-config migrate` — [`docs/migration/v1
 ---
 ## 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).
+A **content layer** — skills, rules, commands, guidelines, personas — distributed via npm and projected into every supported AI tool's native config format. Skills use [`SKILL.md`](https://agentskills.io) with package-specific frontmatter keys.<!-- claim:skill-format-package-keys -->
 
 It is **not** an agent runtime. The agent loop, the LLM dispatcher and tool orchestration stay with the host tool (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI, Copilot). Think of it as a playbook and style guide for those tools — not a replacement.
 
@@ -279,7 +279,7 @@ UI-shaped work routes to one of three directive sets — `ui` (full audit→desi
 
 ### Profiles — how much governance gets loaded
 
-Safety floor (non-destructive defaults · ask-before-guessing · mirror-the-user's-language) ships in **every** profile. What changes is how much extra coaching gets pulled in.
+Safety floor (non-destructive defaults · ask-before-guessing · mirror-the-user's-language) ships in **every** profile, as [a guardrail, not a security boundary](docs/enforcement-by-host.md). Profiles add coaching.
 
 | Profile | What you get | When to pick it |
 |---|---|---|
@@ -331,7 +331,7 @@ Organization-mode features (SSO, central policy, OAuth connectors, team-context)
 
 ## Harness expectations
 
-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`.
+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
 
@@ -407,7 +407,7 @@ in its own profile (`CLAUDE_CONFIG_DIR` per profile), so switching accounts
 never means logging out and back in. The two compose — **agent-switch isolates
 the accounts, agent-config governs what the agents do inside them**. When
 agent-config runs under an agent-switch profile it says so in the settings hub,
-warns before writes that would land in a shared (cross-profile) tree, and
+warns before writes that would land in a shared (cross-profile) tree and
 accepts a host-supplied config root so its own settings stay profile-scoped.
 
 → [How the two compose →](docs/guides/works-with-agent-switch.md)
@@ -440,7 +440,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** (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.
+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
@@ -468,7 +468,7 @@ When a prompt matches a command's purpose ("setze ticket ABC-123 um" → `/imple
 - **Verify with real execution** — no "should work"
 - **Challenge to improve** — agents are thought partners, not yes-machines
 - **Strict by design** — quality over flexibility
-- **Governed runtime** — resident processes require supervision, scoped writes, and a stop control
+- **Governed runtime** — resident processes require supervision, scoped writes and a stop control
 
 ---
 
@@ -498,7 +498,7 @@ For "why didn't rule/hook X fire?" questions: `agent-config routing:doctor`
 — a read-only, live diagnosis that reports every session-start gate as
 ACTIVE/INACTIVE with the concern's own reason (e.g.
 `session-canary: ACTIVE for "Alex"` vs `INACTIVE — no name on any settings
-layer`), the platform's concern chain, host hook registration, and router +
+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`.
 
@@ -523,13 +523,13 @@ task dev:setup        # boot the onboarding wizard against the working tree
 
 **Invoking the CLI from a source checkout:** `./agent-config <command>` (the maintainer shim at the repo root → `scripts/agent-config` → `dist/cli/agent-config.js`). `npx @event4u/agent-config` doesn't resolve in the source repo without a prior `npm link`, since there's no `node_modules/.bin/agent-config` symlink — use `./agent-config` instead. Build the TS binary with `npm run build:cli` if `dist/cli/agent-config.js` is missing.
 
-→ Full project structure and commands: [**docs/development.md**](docs/development.md) · [CONTRIBUTING.md](CONTRIBUTING.md). Stack: **TypeScript** throughout — CLI, UI, and the build / lint scripts. MCP registry payloads render under `dist/mcp/` ([submission checklist](docs/distribution/mcp-submission-checklist.md)).
+→ Full project structure and commands: [**docs/development.md**](docs/development.md) · [CONTRIBUTING.md](CONTRIBUTING.md). Stack: **TypeScript** throughout — CLI, UI and the build / lint scripts. MCP registry payloads render under `dist/mcp/` ([submission checklist](docs/distribution/mcp-submission-checklist.md)).
 
 ---
 
 ## Requirements
 
-- **Node ≥ 20.11** — `npx @event4u/agent-config init` is the canonical install path. No Python anywhere on the install path (the Python installer retired with the TypeScript migration).
+- **Node ≥ 22.6** — `npx @event4u/agent-config init` is the canonical install path. No Python anywhere on the install path (the Python installer retired with the TypeScript migration).
 - **Platform:** macOS 12.3+, Linux, WSL2. Git Bash needs Developer Mode for symlinks. Contributors rebuilding `.augment/` also need [Task](https://taskfile.dev/).
 
 ### Windows
@@ -549,7 +549,7 @@ path reopens it (see `agents/roadmaps/` — road-to-credible-install Phase 3).
 
 ## Funding
 
-The package is free, MIT, and stays that way — no paid tier, no dual
+The package is free, MIT and stays that way — no paid tier, no dual
 licensing. If it saves you time and you want to chip in, the GitHub Sponsor
 button at the top of the repo is the whole mechanism. If you would rather not,
 use it anyway; nothing here is gated on it.

package/dist/agent-src/commands/{design.md → agent-design.md}

@@ -1,15 +1,15 @@
 ---
 model_tier: medium
-name: design
+name: agent-design
 disable-model-invocation: true
 argument-hint: "[audit|render|review|polish|quieter|bolder|distill|harden|clarify] [path]"
 pack: engineering-base
 intent: "Design dispatcher — inventory, capture, review, or run one bounded intervention verb"
 routes_to: [existing-ui-audit, design-review, fe-design]
-replaces: []
+replaces: [design]
 visibility: internal
 description: Design orchestrator — routes audit/render/review to the Class-A commands and the six intervention verbs to fe-design with a declared operation
-cluster: design
+cluster: agent-design
 type: orchestrator
 suggestion:
   eligible: true
@@ -21,11 +21,15 @@ packs:
   - meta
 ---
 
-# /design
+# /agent-design
 
 One entry point for work on an existing UI surface. A **command**, not a skill —
-the skill catalogue is already the largest standing cost in this suite, and this
-adds a router rather than a 295th entry to it.
+every skill adds a catalogue entry that is loaded in every session, and this
+adds a router rather than one more entry to that catalogue.
+
+Formerly `/design`. The host registers its own `/design` built-in, which this
+package must never shadow, so the router takes the name `/agent-design`
+(`replaces: [design]`).
 
 ## Sub-commands
 

package/dist/agent-src/commands/agents/init.md

@@ -92,9 +92,16 @@ always with numbered options where applicable:
 3. **Architecture style** — e.g. "Controllers thin, logic in services,
    validation via FormRequests". Offer `/agents optimize` style presets
    based on detected framework.
-4. **User-facing strings strategy** — translation files? hardcoded?
+4. **Goal** — one to three sentences a plan can be checked against, not a
+   mission statement. Offer no default and invent nothing: an empty answer
+   OMITS the section and is reported in step 8. A goal the agent wrote is a
+   goal nobody decided.
+5. **No-gos** — bullets, each naming a path, a command, a dependency or a
+   behavior ("never edit `migrations/` by hand"). Same rule: empty omits
+   the section and is reported, never filled with a plausible default.
+6. **User-facing strings strategy** — translation files? hardcoded?
    default per framework.
-5. **Additional conventions** — free text, optional.
+7. **Additional conventions** — free text, optional.
 
 ### 4. Generate files
 
@@ -110,9 +117,22 @@ Read the templates, substitute placeholders:
 | `{{project_structure_notes}}`, `{{testing_notes}}`, `{{quality_tools_notes}}` | Offer framework-specific defaults, let user edit |
 | `{{architecture_notes}}`, `{{coding_standards}}`, `{{framework_conventions}}` | Offer defaults + user edits |
 | `{{test_all_command}}`, `{{test_targeted_command}}`, `{{testing_extra_notes}}` | From detected test framework |
-| `{{user_facing_strings_strategy}}` | Step 3.4 |
+| `{{project_goal}}` | Step 3.4 — omitted entirely when the answer was empty |
+| `{{project_no_gos}}` | Step 3.5 — omitted entirely when the answer was empty |
+| `{{user_facing_strings_strategy}}` | Step 3.6 |
 | `{{target_language_level}}` | e.g. "PHP 8.2 / Laravel 11" |
 
+Write the **Goal** and **No-gos** sections from 3.4 and 3.5 into the
+consumer's filled `AGENTS.md`, below the template's own content, using the
+copy-in shapes in `consumer-agents-md-guide.md`. An answer that was empty
+contributes no section and no heading.
+
+**The template file is never edited for this.** `src/agent-src/templates/AGENTS.md`
+sits one character under the 2,500-byte FAIL cap `lint_agents_md` enforces
+(2,499 since 2026-10-12), so nothing of any size fits there; and a section
+whose content comes from the consumer does not belong in a file shipped to
+every consumer.
+
 Remove the HTML comments starting with `<!-- AGENTS.md — entry point …`
 and `<!-- copilot-instructions.md — read by GitHub Copilot …` — they are
 instructions for the human user and no longer needed once filled.
@@ -150,6 +170,37 @@ Next steps:
   3. Run `/agents optimize` periodically to deduplicate against .augment/
 ```
 
+### 6b. No-gos that name a path or a command (optional)
+
+A no-go the agent reads after the edit is a no-go it has already broken. The
+two kinds that CAN be enforced become deny rows the host refuses on; the rest
+stays instruction-only. Skips silently when step 3.5 was empty.
+
+Show what the bullets would become — this writes nothing:
+
+```bash
+./scripts-run src/scripts/no_go_deny_rows AGENTS.md --host {detected_host}
+```
+
+Then ask **once**, with the rows on screen (per
+[`user-interaction`](../../rules/user-interaction.md)):
+
+```
+> 1. Add these rows to .claude/settings.json
+> 2. Skip — leave every no-go instruction-only
+```
+
+On 1, re-run with `--apply`. It appends to the existing deny list, keeps every
+entry the consumer already had and its order, and skips a row the file already
+carries. On 2, run nothing — the command's default writes nothing, so a skip is
+the absence of a second call rather than an undo.
+
+A bullet that names neither a path nor a command is reported as
+instruction-only with the reason beside it, and no row is built for it: a
+guessed row on a vague sentence blocks legitimate work and the agent cannot
+say why. On a host with no deny list established in this tree the rows are
+printed as a report and nothing is written.
+
 ### 7. Module-root proposal (optional)
 
 Surface configurable-module candidates so the team file can opt in to
@@ -181,6 +232,18 @@ If `.agent-settings.yml` does not exist, suggest running `scripts/install` (then
 If module candidates surfaced in Step 7 but the user skipped, note that
 `./scripts-run src/scripts/propose_modules_config` can be re-run anytime.
 
+Report which of the four contract sections the filled file carries:
+
+```bash
+./scripts-run src/scripts/report_project_contract AGENTS.md
+```
+
+It prints `N of 4` and names the missing ones. It is READ-ONLY and infers
+nothing: a goal the agent could guess from the description is still a goal
+nobody wrote, so an omitted section is reported as missing rather than
+quietly filled. `4 of 4` is not a target the initializer pursues on the
+user's behalf — it is a statement about what the file says.
+
 ## Rules
 
 - **Never copy from the package's own root `AGENTS.md` or

package/dist/agent-src/commands/agents/user/init.md

@@ -115,6 +115,9 @@ language: "..."
 role: "..."
 style:
   pace: "...""
+  # avoid:                 # optional — the user's own "never say X" list, max 32
+  #   - pattern: "..."     # 1-64 chars, a literal, never a regex
+  #     match: word        # word | substring
 voice_sample: |
   ...
 last_updated: "YYYY-MM-DD"

package/dist/agent-src/commands/{optimize/deep.md → analyze/and-optimize.md}

@@ -1,13 +1,14 @@
 ---
 model_tier: high
-name: optimize-deep
-pack: meta
+name: analyze-and-optimize
+pack: analysis-workbench
 visibility: internal
-sub: deep
-cluster: optimize
+sub: and-optimize
+cluster: analyze
+replaces: [optimize-deep, optimize:deep]
 skills: [ai-council, roadmap-writing, subagent-orchestration, decision-review]
-description: "Autonomous deep-refactoring loop — subagent analysis, verified findings, council, central + sub-roadmaps, PR, then N refinement loops (default 3). E.g. 'run a deep optimization pass'."
-argument-hint: "[--mode=plan|execute] [--loops=N] [--scope=<path>] [--no-external]"
+description: "Analyse and improve this project, repository or module — analysts reading code, exchange, council, ready roadmaps, PR, N refinement loops (default 3). E.g. 'run a deep optimization pass'."
+argument-hint: "[--mode=plan|execute] [--loops=N] [--scope=<path>|repo] [--project=<path>] [--quick] [--no-external]"
 limits:
   mode_default: plan
   max_iterations: 3
@@ -24,10 +25,10 @@ packs:
   - meta
 ---
 
-# /optimize-deep
+# /analyze:and-optimize
 
 Autonomous deep-improvement loop: **analyze → verify → council → roadmaps →
-PR → refine ×N**. The autonomous sibling of [`/optimize project`](project.md)
+PR → refine ×N**. The autonomous sibling of [`/optimize project`](../optimize/project.md)
 (which is interview-driven and asks the user); this command answers its own
 questions in the AI council and ends with a pull request plus a
 council-refined roadmap set.
@@ -35,7 +36,10 @@ council-refined roadmap set.
 This is a **coordinator** over existing primitives — it composes, never
 reimplements: subagent fan-out analysis, `/analyze:decision`-style decision
 challenge, `ai-council` resolution, `/roadmap:create` output shape,
-`/create-pr` mechanics.
+`/create-pr` mechanics. One of the four analysis doors (ADR-288), formerly
+`optimize:deep` — `optimize:deep` and `optimize-deep` stay aliases;
+shared vocabulary, lenses and tiers:
+[`analysis-loop`](../../contexts/execution/analysis-loop.md).
 
 ## When to invoke
 
@@ -118,58 +122,85 @@ above that, re-invoke deliberately with fresh context.
 
 ## Steps
 
-### Step 0 — Preflight (read-only)
+### Step 0 — Preflight and scope (read-only)
 
-1. Live remote state first (`direct-answers` live-state law): fetch,
+1. **Resolve the scope** with `src/scripts/analysis_target.ts` and print its
+   line before any read: `Scope: <repo|module|subdir> <name> at <path>
+   (anchor: <…>)`. `--scope=<path>` fixes the scope root and must lie inside
+   the project, `--scope=repo` widens to the whole repository, `--project`
+   fixes the project root. Inside a module the scope is the module, with or
+   without a marker in its own `agents/`, and the outer project stays
+   `project_root`. Nothing below reads outside the scope root.
+2. Live remote state first (`direct-answers` live-state law): fetch,
    open PRs, recently merged work overlapping the scope — never from memory.
-2. Create or enter an isolated worktree on a fresh branch off the trunk
+3. Create or enter an isolated worktree on a fresh branch off the trunk
    (branch/worktree creation is authorized by invoking this command; every
    Hard-Floor action below stays gated).
-3. Seed it per the
+4. Seed it per the
    [`using-git-worktrees` § 4b allow/deny list](../../../../skills/using-git-worktrees/SKILL.md#4b-seed-the-worktree--allow--deny-list)
    — symlink or fully install dependencies, copy or regenerate the generated
    projections, regenerate build output, and never copy `.agent-settings.yml`
    into a worktree.
-4. Read the lock inventory: honest nulls, DR memories, `later/` resume
+5. Read the lock inventory: honest nulls, DR memories, `later/` resume
    conditions, standing ADRs. These are constraints for Step 4, surfaced —
    never silently relitigated (`decision-revisit-gate`).
-
-### Step 1 — Deep analysis (parallel subagents)
-
-Fan out read-only analysis subagents over the repo's load-bearing surfaces
-(token/context cost, execution flows, CI/PR pipeline, routing/activation,
-decision debt, archived intelligence) plus — unless `--no-external` —
-tree-level deep-dives of named external references (`external-reference-deep-dive`:
-file trees + raw files, never README summaries). Each agent returns
-structured findings with file:line evidence and an effort estimate.
+6. Open the run (`src/scripts/analysis_run.ts`): run id, pinned head, token
+   budget; a budget cap ends the run `handed-back`, never raises the budget.
+
+### Step 1 — Deep analysis: analysts, lenses, exchange
+
+The read set is `readSet` (`src/scripts/analysis_and_optimize.ts`): the anchor
+table of the scope (`analysis_anchors.ts` — skipped tests, issues, FIXME/TODO,
+open roadmap steps, ADRs) **and the scope's code**, not only its roadmaps and
+ADRs. Every path lies under the scope root.
+
+1. **Analysts** (`analysis_analysts.ts`): three by default, one under
+   `--quick` or a scope below the pre-registered size, all on the same brief,
+   each stamped with its family and context relation. Unless
+   `--no-external`, tree-level deep-dives of named external references
+   (`external-reference-deep-dive`: file trees + raw files, never README
+   summaries) join the brief.
+2. **Seed + three lenses each** — coverage, adversary, overbuild-sequencing
+   (`analysis-loop` § The loop shape); every loop appends a ledger row with
+   tiered evidence (`analysis_ledger.ts`). Each analyst returns structured
+   findings with `file:line` evidence and an effort estimate.
+3. **One exchange** (`analysis_exchange.ts`): inventory, cross-exam, converge,
+   with a disagreement ledger and a minority audit.
 
 ### Step 2 — Verification gate (non-negotiable)
 
 Hand-verify every damning finding before it may steer the roadmap
 (`plausible-mechanism-is-not-evidence`): re-run the grep/measurement the
 finding rests on, in this checkout, at this SHA. A finding that fails
-verification is dropped with a note. Findings colliding with a recorded
-lock are marked and routed to Step 3 only if the mechanism differs
-(mechanism-match test) — otherwise honored as locked.
+verification is dropped with a note. Only `executed` and `read` tiers count as
+verified. Findings colliding with a recorded lock are marked and routed to
+Step 3 only if the mechanism differs (mechanism-match test) — otherwise
+honored as locked.
 
-### Step 3 — Council pass
+### Step 3 — Council pass and the gain gate
 
 Run the AI council (`council:estimate` → `council:run --confirm`) on the
 contested decisions only: priority order, roadmap topology, lock collisions
 that pass the mechanism-match test, and the loop count when the user gave
 none. Surface the fast-path marker verbatim where the low-impact path
 resolves something. High-impact and user-required classes still reach the
-user per `ai-council-config` — autonomy never rewires that floor.
+user per `ai-council-config` — autonomy never rewires that floor. Then the
+gain gate (`analysis_gate.ts`) decides whether one more exchange round is
+offered; questions route by `analysis_questions.ts` — council first, the owner
+once.
 
-### Step 4 — Roadmap set
+### Step 4 — Roadmap set: emit and validate
 
 Author ONE central roadmap (goal, verified findings, locks honored,
 sub-roadmap management table, pre-registered success criteria, provenance —
 external sources anonymized + `ENC1:`-encrypted per `source-confidentiality`)
-plus sub-roadmaps cut along the council's topology. Foundation-class
+plus sub-roadmaps cut along the council's topology, through the emit stage
+(`analysis_emit.ts`: `status: ready`, owner-first landing). Foundation-class
 work (whatever must be true for the rest to be verifiable — typically the
-CI oracle) gates the leverage-class work explicitly. Regenerate the
-dashboard (`roadmap:progress`) in the same response as any roadmap write.
+CI oracle) gates the leverage-class work explicitly. The validate stage
+(`analysis_validate.ts`) runs before anything leaves the machine; a failure
+stops the run in `emitted`. Regenerate the dashboard (`roadmap:progress`) in
+the same response as any roadmap write.
 
 ### Step 5 — Pull request (execute mode only)
 
@@ -178,7 +209,15 @@ dashboard (`roadmap:progress`) in the same response as any roadmap write.
 and present the plan (plan mode's defined end state). Then push the branch
 and open the PR per [`/create-pr`](../pr/create.md) — its mechanics and the
 always-active PR-surface rules govern the body and reply shape; do not
-restate them here.
+restate them here. The publish stage (`analysis_publish.ts`) does it: own
+branch only, the allowed path set, a leased push, a non-draft PR exactly once.
+
+**Run record.** Every run writes `run.json` for its round through
+`src/scripts/analysis_run_record.ts` — one row per analyst and loop, the
+stages, seats used and failed, and the gain estimate. It is written whatever
+the run's end state, including `handed-back`, because the retro's
+`analysis-run` unit reads adoption per run and a missing record reads as a run
+that never happened. An unread turnaround is `missing`, never `0`.
 
 ### Step 6 — Refinement loops (×N, execute mode only)