@event4u/agent-config 8.4.1 → 8.6.0

package/docs/contracts/command-clusters.md

@@ -28,15 +28,15 @@ column 1 of this table.
 
 | Cluster | Phase | Sub-commands | Replaces |
 |---|:-:|---|---|
-| `fix` | 1 | `ci` · `pr-comments` · `pr-bot-comments` · `pr-developer-comments` · `portability` · `refs` · `seeder` · `comments` | `fix-ci` · `fix-pr-comments` · `fix-pr-bot-comments` · `fix-pr-developer-comments` · `fix-portability` · `fix-references` · `fix-seeder`; `comments` added 2026-06-22 — audits the **code comments** in the current branch's diff (simplify / shorten / remove), distinct from the PR-review-thread `pr-comments` sub |
-| `optimize` | 1 | `agents-dir` · `augmentignore` · `rtk` · `skills` | `optimize-augmentignore` · `optimize-rtk-filters` · `optimize-skills` · former `/optimize agents` and `/optimize agents-md` moved to the `/agents` file-family cluster 2026-05-09; `/agents prepare/audit/cleanup` collapsed into the single `/optimize agents-dir` (flags or wizard) per the agent-doc consolidation |
+| `fix` | 1 | `ci` · `pr-comments` · `pr-bot-comments` · `pr-developer-comments` · `portability` · `refs` · `seeder` · `comments` · `quality` | `fix-ci` · `fix-pr-comments` · `fix-pr-bot-comments` · `fix-pr-developer-comments` · `fix-portability` · `fix-references` · `fix-seeder`; `comments` added 2026-06-22 — audits the **code comments** in the current branch's diff (simplify / shorten / remove), distinct from the PR-review-thread `pr-comments` sub; `quality` added 2026-07-08 — replaces `quality-fix` (slug reorder, `replaces:` alias) |
+| `optimize` | 1 | `agents-dir` · `augmentignore` · `rtk` · `skills` · `project` · `prompt` | `optimize-augmentignore` · `optimize-rtk-filters` · `optimize-skills` · former `/optimize agents` and `/optimize agents-md` moved to the `/agents` file-family cluster 2026-05-09; `/agents prepare/audit/cleanup` collapsed into the single `/optimize agents-dir` (flags or wizard) per the agent-doc consolidation; `project` (slug-neutral nest of `optimize-project`, pack move engineering-base → meta) + `prompt` (slug-neutral nest of `optimize-prompt`) added 2026-07-08 — the head now spans agent-layer / project-wide / prompt scopes with a disambiguating menu |
 | `feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` · `dev` | `feature-explore` · `feature-plan` · `feature-refactor` · `feature-roadmap` · `feature-dev` |
 | `chat-history` | 2 | `show` · `import` · `learn` | `chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only` (auto-adopt + structural hooks); `import` (verbatim cross-session render) and `learn` (project-improving learning extraction) added in the v4 stateless schema |
 | `agents` | 2 | `init` · `optimize` · `audit` · `user` | AGENTS.md file family (high-frequency) — repurposed 2026-05-09: `init` (was `/copilot-agents init`) · `optimize` (merger of `/optimize agents-md` + `/copilot-agents optimize`) · `audit` (was `/optimize agents`, collapses old `audit` + `check` verbs); legacy folder ops (`prepare` / `cleanup` / folder-`audit`) moved to `/optimize agents-dir`; `user` sub-cluster added 2026-05-15 — manages the project-root `.agent-user.md` persona file (sub-sub-commands: `init` · `show` · `review` · `accept` · `update`) per [`agent-user-schema`](agent-user-schema.md) |
 | `memory` | 2 | `add` · `load` · `promote` · `propose` · `mine-session` · `learn-low-impact` | `memory-add` · `memory-full` · `memory-promote` · `propose-memory`; `mine-session` added 2026-05-10 — manual transcript-mining sub-command from an internal roadmap (local-only), opt-in via `--confirm-transcript-access` per invocation; `learn-low-impact` added 2026-05-15 — upstreams `## Validated` entries from `agents/decisions/low-impact-decisions.md` to the package seed via a DRAFT PR (re-runs the privacy-floor redactor as a second gate per `low-impact-corpus-privacy-floor`) |
 | `roadmap` | 2 | `create` · `ai-council` · `process-step` · `process-phase` · `process-full` | `roadmap-create` · `roadmap-execute` (replaced — autonomous, no per-step gate; `process-phase` is the default execution scope); `ai-council` added 2026-05-07 — wraps `/council default` with `--input-mode roadmap --depth deep` |
 | `module` | 2 | `create` · `explore` | `module-create` · `module-explore` |
-| `tests` | 2 | `create` · `execute` | `tests-create` · `tests-execute` |
+| `tests` | 2 | `create` · `execute` · `e2e-plan` · `e2e-heal` | `tests-create` · `tests-execute`; `e2e-plan` / `e2e-heal` added 2026-07-08 — replace the flat `e2e-plan` / `e2e-heal` (slug reorders, `replaces:` aliases; composite sub-names per ADR-003 §2) |
 | `context` | 2 | `create` · `refactor` | `context-create` · `context-refactor` |
 | `override` | 2 | `create` · `manage` | `override-create` · `override-manage` |
 | `judge` | 2 | `solo` · `on-diff` · `steps` | `judge` (legacy standalone) · `do-and-judge` · `do-in-steps` |
@@ -46,7 +46,7 @@ column 1 of this table.
 | `challenge-me` | — | `vision` · `with-docs` | new — Pocock-inspired one-question-at-a-time interview; `vision` is the standard 95%-confidence variant, `with-docs` adds doc/glossary awareness with a session-scoped glossary and load-bearing claim-vs-code verification |
 | `research` | 2 | `deep` · `report` | preliminary-research scaffolder ported from `Weizhena/Deep-Research-skills` (cluster head emits `outline.yaml` + `fields.yaml` against the `research-schema` contract). `:deep` populates per-item JSON in batches with native web-search + JSON-Schema self-validation (no Python runtime); `:report` renders `report.md` directly + optionally emits a `jq` template for deterministic regeneration. `add-items` / `add-fields` intentionally **not** ported — re-run `/research <topic>` to extend the field framework. |
 | `orchestrate` | — | _(none yet — cluster head only)_ | new — runtime executor for YAML pipelines under `.agent-config/orchestrations/` per the [`orchestration-dsl-v1`](orchestration-dsl-v1.md) contract; chains personas / skills / commands / sub-agents deterministically. Single cluster head; sub-commands deferred until a second verb is needed. |
-| `sync-gitignore` | — | `fix` | new sub-command 2026-05-11 — cluster head retains the existing append-only sync as its default flow; `:fix` adds `--cleanup-legacy` semantics, scrubbing pre-`/agents/` runtime patterns wherever they appear in the consumer's `.gitignore` (inside or outside the managed block) and re-syncing the canonical entries. |
+| `sync` | 4 | `agent-settings` · `gitignore` · `gitignore-fix` | new cluster 2026-07-08 — absorbs the former single-sub `sync-gitignore` cluster (slug-neutral nests: `sync-agent-settings`, `sync-gitignore`, `sync-gitignore-fix` keep their slugs; the gitignore node keeps its own `fix` sub-dir, mirroring the `agents/user` deep-nest precedent). Bare `/sync` shows the menu. |
 | `ghostwriter` | — | `fetch` · `write` · `list` · `show` · `delete` | new cluster 2026-05-15 — third voice primitive for AI-assisted writing in the public voice of a public figure. Hybrid storage: real-person profiles live consumer-side under `agents/reference/ghostwriter/<slug>.md` (gitignored by default); package source ships only `fictional: true` fixtures. Zero network code in the package — `:fetch` delegates web-fetch / web-search to the host agent. Mandatory disclosure footer on every `:write` output (no opt-out). Schema: [`ghostwriter-schema`](ghostwriter-schema.md). |
 | `post-as` | — | `me` · `ghostwriter` | new cluster 2026-05-15 — consumer-facing write entry points. `:me` reads `.agent-user.md.voice_sample` and drafts in the maintainer's own voice (no disclosure footer — the user is the author); `:ghostwriter` is a thin alias for `/ghostwriter:write` with the mandatory disclosure footer. Both share the procedural [`write-engine`](write-engine.md) contract — style source and footer are the only axes of variation. |
 | `video` | — | `from-script` · `from-song` · `scene` · `storyboard` · `stitch` | new cluster 2026-05-17 — AI video generation pipeline. Cluster head orchestrates the full flow; `:scene` runs a single scene end-to-end (script → blueprint → still → motion → clip); `:storyboard` expands a script into per-scene blueprints + reference stills with character-lock JSON; `:from-script` walks a multi-scene script through storyboard + per-scene generation; `:from-song` builds a music-video from a song + reference images — derived/briefed timed script (via the `song-to-script` skill + `probe-audio.sh` hybrid segmentation), optional character-lock, then stitch with the song muxed as the master track and a mandatory AI-generation disclosure; `:stitch` concatenates scene clips with `ffmpeg` against a scene manifest. Provider-agnostic via the adapter contract under `scripts/media/lib/adapter-contract.md`; cost-gated with mandatory `AIV_DRYRUN=true` default and explicit confirmation before live provider calls. |
@@ -58,13 +58,43 @@ column 1 of this table.
 
 | `team-knowledge` | — | `consolidate` · `bootstrap` | new cluster 2026-07-05 (`road-to-knowledge-system` Phases 5-6) — the repo-tracked team-knowledge layer under `agents/knowledge/{sessions,concepts,procedures,decisions}/`. Distinct from the pre-existing [`knowledge`](#locked-clusters) cluster (arbitrary local-file ingestion into `agents/memory/knowledge/`) — different namespace, different concern. `:consolidate` reads pending typed-observation events (`consolidate_knowledge_events.ts`), finds the nearest existing page per topic (mechanical similarity), and presents a NEW/EXTEND/CONFIRM/CONFLICT batch for human approval — never writes a page automatically. `:bootstrap` (`bootstrap_knowledge.ts`) stages a one-shot deterministic seed (detected package manifest, top-level directories, known config filenames — never file content, never an LLM-invented claim) to a gitignored staging dir for review-then-commit. |
 | `profile` | — | `activate` · `deactivate` · `show` | new cluster 2026-06-02 (`road-to-session-profile-activation`) — session-profile activation: an ephemeral `runtime.active_packs` overlay that biases the surfaced command/skill set to the active pack closure, with no persistence and no execution-gating (recommendation-bias MVP). `:activate <name…>` resolves an alias (`src/config/discovery/session-profiles.yml`) or a raw pack id, fails fast on a not-installed pack, expands the `requires_hint` closure, and writes the overlay atomically to `agents/settings/.agent-settings.local.yml`; `:deactivate [name…]` clears it (or drops named packs, keeping deps a still-active pack needs); `:show` is the observability surface (active packs + surfaced/hidden counts). Overlay = runtime modulation of the existing `pack` axis, not a fifth axis (ADR-010 addendum). Library: `scripts/config/session_profiles.py`; schema in [`session-profile-overlay`](session-profile-overlay.md). |
+| `analyze` | 4 | `postmortem` · `premortem` · `decision` · `near-miss` · `incident` · `reference-repo` | analysis-workbench cluster, registered in this table 2026-07-08 (pre-existing head + five framework subs); `reference-repo` added 2026-07-08 — slug-neutral nest + pack move of `analyze-reference-repo` (engineering-base → analysis-workbench, co-locating with its head) |
+| `bug` | 4 | `fix` · `investigate` | new cluster 2026-07-08 — slug-neutral nests of `bug-fix` + `bug-investigate`; triage entry point (investigate = root cause, fix = plan + implement). Bare `/bug` shows the menu. |
+| `project` | 4 | `analyze` · `health` | new cluster 2026-07-08 — slug-neutral nests of `project-analyze` + `project-health`; project-wide inspection (analyze = full audit, health = read-only). Bare `/project` shows the menu. |
+| `review` | 4 | `changes` · `routing` | new cluster 2026-07-08 — slug-neutral nests of `review-changes` (tier moved to the head: sub is internal, head is the advanced surface) + `review-routing` (pack move meta → engineering-base). `prepare-for-review` deliberately stays flat (council-rejected slug change). Bare `/review` shows the menu. |
+| `package` | 4 | `test` · `reset` | new cluster 2026-07-08 — slug-neutral nests of `package-test` (pack move engineering-base → meta) + `package-reset`; package-install maintenance. Bare `/package` shows the menu. |
+| `cost` | 4 | `report` · `profile` | new cluster 2026-07-08 — slug-neutral nest of `cost-report` + `profile` replacing `set-cost-profile` (slug reorder, `replaces:` alias). Bare `/cost` shows the menu. |
 
 **Net change:** Phase 1 collapsed 15 atomics → 3 clusters; Phase 2
-collapses 26 atomics → 11 sub-command clusters. Sub-commands use
-colon syntax (`/cluster:sub`) so Claude Code's command palette can
-autocomplete them. The standalone `/review` surface that mirrors
-`judge solo` lives at
-[`commands/review-changes.md`](../../.agent-src.uncondensed/commands/review-changes.md).
+collapses 26 atomics → 11 sub-command clusters. Phase 4 (2026-07-08,
+`road-to-command-structure-optimization`) nests 19 more flat commands
+into 6 new + 4 extended clusters — 15 of them slug-neutral (path
+hyphen-joining keeps the invoked name), 4 slug reorders carried by
+`replaces:` aliases (`fix-quality`, `tests-e2e-plan`, `tests-e2e-heal`,
+`cost-profile`). The five-judge self-review formerly at
+`review-changes` is now the `changes` sub of the `review` cluster.
+
+## Bare invocation — deterministic, never guessed
+
+Locked with Phase 4 (2026-07-08). Every cluster head defines what a
+bare `/<cluster>` (no sub-command, no auto-detect signal) does:
+
+1. **Multi-sub head → numbered menu.** Print the sub-command menu and
+   ask; never guess a sub-command. Heads with `auto_detect: true` run
+   their detection table first, but LOW confidence still ends in the
+   menu (interactive) or `ambiguous_routing` (CI) — never a guess.
+2. **Single-sub head → default-route.** Route to the only sub and say
+   so (e.g. `/chat-history` → `import`).
+3. **Documented default-flow exceptions.** A head whose bare
+   invocation runs a real default flow declares it in its `## Dispatch`
+   section (e.g. `/council` → `default` lens, `/sync gitignore` bare →
+   its own `## Default flow`). The exception lives in the head file —
+   not in tribal knowledge.
+
+`scripts/check_cluster_patterns.ts` enforces the structural side:
+every phase-numbered cluster head carries `## Sub-commands` (with the
+locked table header), `## Dispatch`, and `## Rules`, and every
+`routes_to:` entry must resolve to a real command.
 
 ## Cluster depth and sub-command naming
 

package/docs/contracts/file-ownership-matrix.json

@@ -5012,6 +5012,13 @@
       "via": "body_link",
       "depth": 1
     },
+    {
+      "source": ".agent-src.uncondensed/rules/delegation-policy.md",
+      "target": ".agent-src.uncondensed/contexts/execution/subagent-steering.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncondensed/rules/delegation-policy.md",
       "target": ".agent-src.uncondensed/contexts/execution/verify-budget.md",
@@ -9366,6 +9373,13 @@
       "via": "self",
       "depth": 0
     },
+    {
+      "source": ".agent-src.uncondensed/skills/git-workflow/SKILL.md",
+      "target": ".agent-src.uncondensed/skills/quality-tools/SKILL.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncondensed/skills/github-ci/SKILL.md",
       "target": ".agent-src.uncondensed/skills/github-ci/SKILL.md",
@@ -13034,6 +13048,13 @@
       "via": "self",
       "depth": 0
     },
+    {
+      "source": ".agent-src.uncondensed/skills/subagent-orchestration/prompts/do-in-steps.md",
+      "target": ".agent-src.uncondensed/contexts/execution/subagent-steering.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncondensed/skills/subagent-orchestration/prompts/do-in-steps.md",
       "target": ".agent-src.uncondensed/skills/subagent-orchestration/SKILL.md",

package/docs/contracts/frontmatter-contract.md

@@ -83,7 +83,7 @@ install:
 ---
 ```
 
-### Command — `commands/cost-report.md`
+### Command — `commands/cost/report.md`
 
 ```yaml
 ---

package/docs/contracts/gui-wizard.md

@@ -17,9 +17,21 @@ keep-beta-until: 2026-08-19
 ## Source of truth
 
 The GUI is a Fastify server (`src/server/`) serving a Preact SPA
-(`src/ui/`), booted by the `install` / `setup` / `ui:serve` CLI
-subcommands. The legacy `packages/core/installer/src/gui/*` tree was
-retired; the single real installer is `scripts/install.py`.
+(`src/ui/`), booted by the `install` / `setup` / `config` (alias
+`settings`) / `ui:serve` CLI subcommands. The legacy
+`packages/core/installer/src/gui/*` tree was retired; the single real
+installer is `scripts/install.py`.
+
+Entry-point map (road-to-setup-experience § Phase 1):
+
+- `init` — install front-end; opens the wizard in install mode (start
+  screen: recommended path vs customize). `init --project` never boots
+  the GUI — it writes the minimal project surface via the
+  `refresh --project` writer.
+- `setup` — re-runs the guided onboarding wizard (prefilled).
+- `config` — opens the standalone settings hub (`#/settings`; global
+  scope). `config --project` lands on the project surface
+  (`#/project`). `settings` stays as a compatible alias.
 
 - Server app + security hooks: [`src/server/app.ts`](../../src/server/app.ts) (Host allow-list, Origin allow-list, CSRF token — `onRequest` hooks)
 - Wizard routes (incl. the real-apply bridge): [`src/server/routes/wizard.ts`](../../src/server/routes/wizard.ts)
@@ -63,7 +75,7 @@ Finish drives the **whole** install through `POST /api/v1/wizard/apply` →
 `AGENT_CONFIG_NO_UI` set, stdin/stdout not a TTY, a headless host (SSH / Linux
 without `DISPLAY`), or a CLI-mode flag (`--no-ui` / `--tools` / `--ai` /
 `--yes` / `--quiet` / `--dry-run` / `--minimal` / `--settings-only` /
-`--list-tools`). `install.py`'s own tail-launch (`_wizard_spawn`, matching the
+`--list-tools` / `--project`). `install.py`'s own tail-launch (`_wizard_spawn`, matching the
 `WIZARD_READY <url>` handshake) remains for direct CLI install runs.
 
 ### `WIZARD_READY` stdout contract

package/docs/contracts/iron-law-overrides.txt

@@ -18,6 +18,7 @@
 # Iron-Law fences + non-externalisable enumerations; further condensation
 # would force semantic loss. All sit ≤ 4 000-char override ceiling.
 ask-when-uncertain
+commit-policy
 direct-answers
 language-and-tone
 no-cheap-questions

package/docs/contracts/rule-classification.md

@@ -112,9 +112,9 @@ existing skills under `.agent-src.uncondensed/skills/`.
 | commit-conventions | 1938 | `conventional-commits-writing` | Format procedure |
 | docker-commands | 1830 | `docker` | Stack-specific procedure |
 | docs-sync | 3131 | `agent-docs-writing` | Mechanical sync procedure |
-| e2e-testing | 1807 | `e2e-heal` | Procedural; project-specific |
+| e2e-testing | 1807 | `tests-e2e-heal` | Procedural; project-specific |
 | laravel-translations | 995 | `laravel` | Stack-specific |
-| model-recommendation | 2909 | `set-cost-profile` | Routing procedure |
+| model-recommendation | 2909 | `cost-profile` | Routing procedure |
 | onboarding-gate | 4881 | `onboard` | Mechanical: meta-rule about /onboard |
 | package-ci-checks | 1342 | `lint-skills` | Repo-specific procedure |
 | reviewer-awareness | 3573 | `review-routing` | Skill exists; consolidates former `review-routing-awareness` (2026-05-08, see `agents/settings/contexts/adr-auto-rule-consolidation.md`) |

package/docs/contracts/settings-api.md

@@ -6,7 +6,7 @@ keep-beta-until: 2026-08-18
 # Settings GUI — REST API Contract (v1)
 
 > Local-only HTTP API exposed by `agent-config ui:serve` and reused by
-> `agent-config settings` / `agent-config setup`. Listens on `127.0.0.1`
+> `agent-config config` (alias `settings`) / `agent-config setup`. Listens on `127.0.0.1`
 > only; no auth, no cross-origin. The browser SPA is the sole client —
 > the legacy `/onboard` chat skill has been retired.
 >
@@ -72,10 +72,16 @@ Response (200):
     "values":       { "rule_loading_tier": "balanced", "...": "..." },
     "lastModified": 1747749791842,
     "path":         "settings/.agent-settings.yml",
-    "legacyHints":  { "user_name": "Matze" }
+    "legacyHints":  { "user_name": "Matze" },
+    "sources":      { "global": ["rule_loading_tier", "personal.ide"], "project": [] }
 }
 ```
 
+`sources` (road-to-setup-experience § Phase 5.4) carries the dotted
+leaf paths present in each layer FILE (not the merged tree) so the
+settings hub can badge which layer supplies a value — a `project`
+entry overrides a `global` one per the merge order above.
+
 `legacyHints` is an out-of-band sidecar carrying values that have moved
 out of `settingsSchema` but still live in a pre-v2 file on disk. Keys
 are omitted when empty, never `null`. Current hints:
@@ -125,6 +131,56 @@ Errors: **412 Precondition Required** when the header is absent;
 **422 Unprocessable Entity** with per-field errors on validation
 failure; **500** with `code=ATOMIC_WRITE` if the temp-rename loop fails.
 
+### `GET /api/v1/settings/changes`
+
+Pending upgrade-time settings-surface delta
+(road-to-settings-change-review). The installer persists the flattened
+settings surface (`state/settings-surface.json`: per dotted leaf its
+type / default / enum / description + package version) on every global
+install; when a previous snapshot from a different version exists it
+computes the semantic delta and writes `state/settings-delta.json` —
+that file is what this route serves. Classification against the user's
+current values happens client-side via the shared
+`src/shared/settingsSurface.ts` module (`must_fix` / `adopt` /
+`review` / `info`).
+
+Response (200):
+
+```json
+{
+    "delta": {
+        "oldVersion": "8.3.0",
+        "newVersion": "8.4.0",
+        "changes": [
+            { "key": "personal.autonomy", "kind": "default_changed", "old": { "...": "..." }, "new": { "...": "..." } },
+            { "key": "discipline_profile", "kind": "added", "new": { "...": "..." } }
+        ]
+    },
+    "source": "writeRoot"
+}
+```
+
+`kind` ∈ `added | removed | default_changed | enum_added |
+enum_removed | type_changed`. `source` is `userGlobal` when the delta
+was found via the package-sandbox read fallback.
+
+Errors: **404** with `code=NO_PENDING_CHANGES` when no (parseable)
+delta file exists.
+
+### `POST /api/v1/settings/changes/ack`
+
+Clears the pending delta after the review form is resolved (or
+dismissed). Deletes only `<writeRoot>/state/settings-delta.json` —
+never the real machine's file when running in a sandbox. Idempotent.
+
+Response (200): `{ "ok": true, "cleared": true }` (`cleared: false`
+when nothing was pending; `dryRun: true` and no deletion in dry-run
+mode).
+
+A matching `settings-review-pending` doctor check warns while the
+delta file exists; the settings hub renders a review banner linking to
+`#/settings/changes`.
+
 ### `GET /api/v1/user-md`
 
 Reads `<projectRoot>/.agent-user.md`. Returns `{ body: '', exists: false, lastModified: null }`

package/docs/contracts/surface-matrix.md

@@ -1,3 +1,8 @@
+---
+stability: beta
+keep-beta-until: 2026-10-06
+---
+
 # Surface Matrix — per-tool canonical-surface contract
 
 > Machine-checked inventory of which install surface is canonical per tool,

package/docs/cookbook.md

@@ -11,7 +11,7 @@ Each recipe is a short command sequence. Run the commands in order; the listed s
 
 *You have a diff and want a real review, not a rubber-stamp.*
 
-- **Commands:** `/review-changes` → `/judge` → `/quality-fix`
+- **Commands:** `/review:changes` → `/judge` → `/fix:quality`
 - **Skills:** `code-review`, `adversarial-review`
 
 ### Fix a red CI run
@@ -60,7 +60,7 @@ Each recipe is a short command sequence. Run the commands in order; the listed s
 
 *Something is broken and you want root cause before the patch.*
 
-- **Commands:** `/bug-investigate` → `/bug-fix`
+- **Commands:** `/bug:investigate` → `/bug:fix`
 - **Skills:** `systematic-debugging`, `bug-analyzer`
 
 ### Get a second opinion from the AI council
@@ -81,7 +81,7 @@ Each recipe is a short command sequence. Run the commands in order; the listed s
 
 *You want to restructure code without changing behaviour.*
 
-- **Commands:** `/feature:refactor` → `/review-changes` → `/judge`
+- **Commands:** `/feature:refactor` → `/review:changes` → `/judge`
 - **Skills:** `code-refactoring`, `test-driven-development`
 
 ### Commit in logical chunks
@@ -95,7 +95,7 @@ Each recipe is a short command sequence. Run the commands in order; the listed s
 
 *You just opened a repo and want a fast structural read.*
 
-- **Commands:** `/project-analyze` → `/project-health`
+- **Commands:** `/project:analyze` → `/project:health`
 - **Skills:** `project-analyzer`
 
 ### Estimate a ticket
@@ -134,14 +134,14 @@ Explore, plan, estimate, refine, and investigate before building. The "what shou
 
 Build it. The core "make the change" front — drive a prompt, ticket, or feature end-to-end through plan → implement → verify.
 
-- **Path:** `/work` → `/review-changes` → `/quality-fix` → `/commit`
+- **Path:** `/work` → `/review:changes` → `/fix:quality` → `/commit`
 - **Skills:** `test-driven-development`, `code-review`, `systematic-debugging`, `git-workflow`
 
 ### Review flow
 
-Check it. Self-review, judge, quality-fix, and threat-model a change before it ships.
+Check it. Self-review, judge, fix/quality, and threat-model a change before it ships.
 
-- **Path:** `/review-changes` → `/judge` → `/quality-fix` → `/threat-model`
+- **Path:** `/review:changes` → `/judge` → `/fix:quality` → `/threat-model`
 - **Skills:** `code-review`, `adversarial-review`, `quality-tools`, `threat-modeling`, `receiving-code-review`
 
 ### Delivery flow

package/docs/decisions/ADR-114-commit-policy-iron-law-override.md

@@ -0,0 +1,74 @@
+# ADR-114 — commit-policy Iron-Law Override (per-rule cap 2.5k → ceiling 4.0k)
+
+- **Status:** Accepted (2026-07-08)
+- **Supersedes:** none — extends the override set locked by
+  [ADR-002](ADR-002-kernel-bucket-overrides.md) under
+  `docs/contracts/kernel-membership.md` § 5.1.
+- **Related:** ADR-002 (kernel-bucket cap raise + the original 6 overrides).
+
+## Context
+
+Commit 259bb1b24 (*feat(commit-policy): one-shot authorization is not a
+standing license*, merged to main 2026-07-07) added a second Iron-Law fence
+to `commit-policy`:
+
+```
+A ONE-OFF AUTHORIZATION IS SPENT ON EXACTLY THAT OPERATION, ONCE.
+IT NEVER BECOMES A STANDING LICENSE FOR LATER COMMITS OR PUSHES.
+EACH FURTHER COMMIT / PUSH NEEDS ITS OWN FRESH, EXPLICIT GO-AHEAD.
+```
+
+plus the prose enumerating which phrasings spend the authorization and the
+canonical failure it prevents. That grew the rule from 2 354 chars (the
+post-ADR-002 trimmed size) to **3 194 chars** — over the 2 500 per-rule hard
+cap, without an entry in `docs/contracts/iron-law-overrides.txt`, so
+`lint-rule-budget` hard-fails on every branch that carries main.
+
+Kernel-bucket state at decision time: **25 393 / 26 000 chars** (9 rules) —
+the bucket cap from ADR-002 still holds with ~600 chars headroom; only the
+per-rule cap is exceeded.
+
+## Decision
+
+1. Add `commit-policy` (3 194 chars) to
+   `docs/contracts/iron-law-overrides.txt` with this ADR as justification.
+   It sits between 2.5k and the 4.0k override ceiling.
+2. The kernel bucket cap (26 000) and the override ceiling (4 000) stay
+   unchanged.
+
+## Rationale
+
+`commit-policy` now carries **three non-externalisable structural
+elements** — the same test ADR-002 applied to the original 6 overrides:
+
+- The primary Iron-Law fence (`NEVER COMMIT. NEVER ASK ABOUT COMMITTING.`)
+  plus the closed 4-exception enumeration — the rule's contract.
+- The new one-shot-authorization fence plus the phrasing enumeration
+  ("commit this", "push it", "open the PR" are spent on exactly that
+  operation). Externalising the enumeration would force a context load on
+  every commit-adjacent turn — i.e. always — defeating the kernel-vs-auto
+  split.
+- The split-into-chunks fence (`COMMIT AUTHORIZED → SPLIT INTO LOGICAL
+  CHUNKS BY DEFAULT`) with its never-ask clauses.
+
+ADR-002 noted commit-policy was trimmable *because* it carried no
+enumeration; 259bb1b24 changed exactly that premise by adding one whose
+misreading (a one-off "commit this" read as standing license) is the
+canonical failure the fence exists to stop.
+
+## Consequences
+
+- **Pro:** `lint-rule-budget` is green again on every branch tracking main;
+  the Iron-Law fences stay byte-preserved in one rule.
+- **Con:** 7 of 9 kernel rules now carry overrides; the 2.5k hard cap
+  disciplines only new/small rules. The 26k bucket (98%+ utilisation
+  headroom per ADR-002) remains the effective backstop.
+- Future commit-policy growth past 4 000 chars is not covered — that would
+  require condensation or an externalisation decision, not another ADR.
+
+## Rollback
+
+Trim the one-shot-authorization prose into
+`contexts/authority/commit-mechanics.md` (keeping only the fence in the
+rule) and remove the allowlist entry — reversible; this ADR does not lock
+that out.

package/docs/decisions/ADR-115-command-cluster-consolidation-phase-4.md

@@ -0,0 +1,91 @@
+---
+adr: 115
+status: accepted
+date: 2026-07-08
+decision: command-cluster-consolidation-phase-4
+supersedes: —
+superseded_by: —
+phase: road-to-command-structure-optimization · Phase 0
+---
+
+# ADR-115 — Command-cluster consolidation Phase 4 (flat dash commands → nested clusters)
+
+- **Deciders:** maintainer + AI council (anthropic/claude-sonnet-4-5 + openai/gpt-4o, 2-round debate, 2026-07-08)
+
+## Context
+
+After the Phase 1–3 cluster collapses, ~27 flat dash-separated commands
+remained (`bug-fix`, `project-analyze`, `optimize-project`, `quality-fix`, …).
+ADR-044 derives the invoked slug from the physical path by hyphen-joining
+(`fix/ci` → `fix-ci`), which creates a cost asymmetry the earlier phases did
+not exploit: **nesting `bug-fix` as `bug/fix` keeps the invoked slug
+`bug-fix`** — invocation-neutral — while only reorder-moves
+(`quality-fix` → `fix/quality` = `fix-quality`) change the typed name.
+
+## Decision
+
+1. **Nest the remaining coherent families** (council-adopted set):
+   - Extended clusters: `optimize` (+`project`, `prompt`), `fix` (+`quality`),
+     `tests` (+`e2e-plan`, `e2e-heal`), `analyze` (+`reference-repo`).
+   - New clusters: `bug` (fix · investigate), `project` (analyze · health),
+     `review` (changes · routing), `package` (test · reset),
+     `cost` (report · profile), `sync` (agent-settings · gitignore ·
+     gitignore-fix — absorbs the single-sub `sync-gitignore` cluster).
+   - Slug reorders carry `replaces:` aliases: `fix-quality`,
+     `tests-e2e-plan`, `tests-e2e-heal`, `cost-profile`.
+2. **Cluster heads are dispatch menus, not verbs.** ADR-041's controlled-verb
+   allowlist governs the leading token of visible *command slugs* (and the
+   `sub:` head for nested commands). A cluster head named after a noun/scope
+   (`bug`, `project`, `cost`) is a navigation surface — the same shape as the
+   pre-existing `agents`, `memory`, `brand`, `video` heads — and does not add
+   a verb to the allowlist. (Council round 2 explicitly overturned the
+   verb-policy objection on this ground.)
+3. **Co-location rule.** All subs of a cluster live in the same pack directory
+   as the head — slug derivation implies it. Cross-pack members move packs
+   (`optimize-project` eng → meta, `review-routing` meta → eng,
+   `package-test` eng → meta, `sync-gitignore` eng → meta,
+   `analyze-reference-repo` eng → analysis-workbench).
+4. **Bare invocation is deterministic.** Multi-sub head → numbered menu;
+   single-sub head → default-route; documented default-flow exceptions live in
+   the head's `## Dispatch`. Enforced structurally by
+   `scripts/check_cluster_patterns.ts`, which now also resolves every
+   `routes_to:` entry to a real command.
+5. **Tier-0 slugs never change.** Deferred/rejected per council:
+   - `ticket` cluster (implement/estimate/refine/jira) — tier-0
+     `implement-ticket` rename + cross-pack move; revisit with usage
+     telemetry.
+   - `security` cluster — weak cohesion; `security-audit-config` and
+     `threat-model` stay flat.
+   - `prepare-for-review` → `review/prepare` — pre-commit muscle memory.
+   - Demotions (`check-current-md`, `update-form-request-messages`) — need a
+     skill-coverage / pack-boundary audit first.
+
+## Consequences
+
+- 19 commands nested; 15 keep their invoked slug, 4 gain `replaces:` aliases.
+- `review-changes` becomes internal; the advanced surface is the `review`
+  head (eval key moves `review-changes.json` → `review.json`).
+- `lint_no_new_atomic_commands.ts` is repointed from the removed
+  `.agent-src.uncondensed/commands` dir to `src/domains` so the atomic-surface
+  gate has teeth again; the new clusters are registered in the locked table.
+- Consumers invoking old reordered slugs are migrated via `replaces:` +
+  the `migrate` flow; slug-neutral nests need no migration.
+
+## Alternatives considered
+
+- **Colon-namespaced subcommands** — rejected long ago (ADR-044): Claude Code
+  cannot resolve them.
+- **`ticket` cluster now** — rejected by both council members (highest-risk
+  item: tier-0 rename + pack move with unclear ownership).
+- **Keeping `/optimize` agent-layer-only** — council split; maintainer
+  directive adopted the widened scope; the head menu + scope-check rule
+  disambiguates the three scopes.
+
+## References
+
+- `docs/contracts/command-clusters.md` — locked table (Phase 4 rows) + the
+  new "Bare invocation" section.
+- `agents/roadmaps/road-to-command-structure-optimization.md` — inventory,
+  council verdicts, phases.
+- ADR-003 (flat clusters), ADR-041 (controlled verbs), ADR-044 (path-derived
+  hyphen slugs).

package/docs/decisions/ADR-116-memory-tripwire-activation-path.md

@@ -0,0 +1,125 @@
+---
+adr: 116
+status: accepted
+date: 2026-07-08
+decision: memory-tripwire-activation-path
+supersedes: —
+superseded_by: —
+phase: road-to-memory-retrieval-economy · Phase 6
+---
+
+# ADR-116 — Memory scale-tripwire activation path: one engine, measured at fire time
+
+- **Deciders:** maintainer + AI council (anthropic/claude-sonnet-4-5 +
+  openai/gpt-4o; disposition debate 2 rounds + engine tie-break 2 rounds,
+  2026-07-08 — tie-break converged after the in-repo `node:sqlite`
+  precedent was surfaced)
+
+## Context
+
+An external second-opinion review (round 2 of the Obsidian-reference
+comparison) surfaced a real documentation conflict: the memory-scale
+tripwire (>200 files in one memory/knowledge type, or >500 files total —
+guarded by `lint_knowledge_scale.ts`) had **three different pre-decided
+activation paths** across three artifacts, written by two councils one day
+apart:
+
+1. `agents/settings/contexts/second-brain-delta-verdict.md` Q4
+   (2026-07-07): "file-first in-memory BM25 (minisearch-class, re-index at
+   session-start, no persistence)".
+2. `agents/roadmaps/road-to-memory-retrieval-economy.md` Phase 6
+   (2026-07-07/08): "SQLite FTS5 over the memory files … replacing
+   `_score()`'s substring pass".
+3. `docs/decisions/ADR-061-corpus-grounding-layer.md`: "a new domain ships
+   a manifest + data + a named owner — **not a forked engine**", with a
+   tested in-house BM25 (`src/skills/corpus-grounding/scripts/bm25_search.ts`,
+   generic `class BM25` over `Row[]`) as the implied reuse candidate.
+
+The whole point of a pre-decided path is that the tripwire firing needs no
+new debate; in this state, firing would have required one.
+
+## Decision
+
+1. **One engine: SQLite FTS5 via Node's built-in `node:sqlite`.**
+   - Zero npm dependency — the repo already uses `node:sqlite` in
+     production code (`src/scripts/mcp_telemetry_store.ts` /
+     `mcp_telemetry_query.ts`) with the established pattern: lazy import +
+     runtime guard for Node < 22.5 (`src/scripts/_lib/node_sqlite.d.ts`).
+     `better-sqlite3` and a minisearch dependency are both rejected.
+   - **Persistence economics** decided the tie-break: at tripwire scale the
+     in-memory re-index per session-start is a startup tax that grows with
+     the corpus; FTS5 gives a persisted index plus incremental updates.
+     The in-house `class BM25` lacks a persistence layer; building one
+     (serialization, incremental updates, corruption handling) recreates
+     what SQLite ships.
+   - Index location: `agents/runtime/state/` (gitignored, never tracked).
+   - **Re-index is batch/lazy** — post-session or on first lookup, never
+     inline per write: during active sessions files churn (drafts,
+     rollbacks), and inline indexing would put fsync latency and lock
+     contention inside the write path (council round-2 caveat).
+   - FTS5 availability in the bundled SQLite is verified at implementation
+     time; on absence or Node < 22.5 the runtime guard falls back to the
+     current grep/substring path.
+
+2. **Measurement at activation, no speculative harness.** At today's
+   corpus (~85 auto-memory files / 412 KB) the ranked-retrieval lift over
+   grep is zero by construction — the honest-zero is already recorded in
+   the verdict. No grep-vs-ranked benchmark harness is built now. Instead,
+   the pre-decided path carries a clause: when the tripwire fires, reuse
+   the retrieval-economy Phase-0 replay set to measure the grep baseline
+   vs the FTS5 candidate on the then-current corpus BEFORE building; ship
+   only on measured retrieval lift, else record the honest-null and keep
+   grep.
+
+3. **ADR-061 boundary restated.** Memory lookup is a **Reference**
+   operation in ADR-061's four-operation model — memory is never
+   registered as a grounding corpus ("grounding theater"), and
+   `corpus-grounding`'s engine is not forked per domain. This ADR does not
+   amend ADR-061; it confirms the tripwire path lives outside the
+   grounding layer.
+
+4. **Wording migration.** The verdict Q4 "minisearch-class" sentence and
+   the tripwire-table row are amended in the same change; a grep sweep for
+   `minisearch` / "pre-decided BM25" catches stragglers in stable
+   artifacts.
+
+## Consequences
+
+- Firing the tripwire is now a wiring-plus-measurement task, not a design
+  debate: guard fires → replay-set comparison → on lift, ~30-line
+  `node:sqlite` FTS5 schema + query wrapper replacing `_score()`'s
+  substring pass.
+- No new npm dependency at any point on this path; Layer-2 sunset stands
+  (no vectors, no services, no always-on workers).
+- The rejected review items are recorded here so they are not relitigated:
+  a pre-built grep-vs-ranked harness (speculative — measures a known
+  zero), and a deterministic "next step" hot-context field (feature envy
+  absent a real resume-context gap; the LLM-summary ban from the verdict's
+  REJECT-list is untouched).
+
+## Alternatives
+
+- **In-house `bm25_search.ts` as a library** — rejected in the tie-break:
+  no persistence layer; the "zero new deps" advantage evaporated once
+  `node:sqlite` (also zero-dep) was on the table; retrofitting
+  persistence ≈ 200 LOC of database-shaped code SQLite already provides.
+- **minisearch dependency** (verdict Q4's original wording) — rejected:
+  new npm dependency for a problem the built-in module covers; same
+  missing-persistence shape.
+- **Two-step (in-house now, FTS5 escalation later)** — rejected: a
+  pre-decided path must be single and unambiguous; a conditional two-step
+  re-imports the debate the tripwire exists to avoid.
+- **Pre-building the measurement harness now** — rejected: honest expected
+  lift at the current corpus is zero; the replay set from Phase 0 will
+  exist independently and is reused at fire time.
+
+## References
+
+- `agents/roadmaps/road-to-memory-retrieval-economy.md` § Phase 6 (engine
+  note + measurement-at-activation clause).
+- `agents/settings/contexts/second-brain-delta-verdict.md` Q4 (amended
+  wording + tripwire table).
+- `docs/decisions/ADR-061-corpus-grounding-layer.md` (four-operation
+  model; engine-fork ban).
+- `src/scripts/mcp_telemetry_store.ts`, `src/scripts/_lib/node_sqlite.d.ts`
+  (in-repo `node:sqlite` precedent).