@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/ci-green-floor.md

@@ -1,141 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-26
-roadmap_ref: road-to-adoption-proof-and-ci-green.md
----
-
-# CI Green Floor
-
-> **Status** · v0 / beta · 2026-05-26. Phase A Step 4 of
-> the `road-to-adoption-proof-and-ci-green` roadmap (archived).
-> Defines what counts as a **blocking** CI failure (must be green
-> before merge) vs. an **advisory** signal (visible but not
-> merge-blocking), and the freeze rule that fires when main goes
-> red on a required check.
-
-## The Iron Law
-
-```
-ANY REQUIRED-CHECK RED ON `main` FREEZES SUBSEQUENT PR MERGES
-UNTIL THE RED IS CLEARED. ADVISORY REDS NEVER FREEZE.
-PHANTOM 0-JOB RUNS ARE ADVISORY BY CONSTRUCTION.
-```
-
-The required-check set is the source of truth for what blocks. Every
-other workflow is advisory until it earns inclusion.
-
-## Three tiers — blocking · advisory · phantom
-
-| Tier | Definition | Effect on merge | Effect on freeze |
-|---|---|---|---|
-| **Blocking** | Listed in [`branch-protection-policy.md`](branch-protection-policy.md) § Per-PR-shape required-check matrix for the current PR shape. | Red blocks the PR merge. | Red on `main` (post-merge) triggers a freeze tag — see [Freeze rule](#freeze-rule-the-mechanics). |
-| **Advisory** | Workflow ships in `.github/workflows/` but is NOT listed in the required-check matrix (e.g. `bench-drift.yml`, `cloud-release.yml`, `deploy-mcp-worker.yml`). | Red is visible on the PR page but does not block merge. | Red on `main` does not freeze. |
-| **Phantom** | Workflow registers a run with `Jobs: 0` and `Conclusion: failure` — typically `workflow_dispatch`-only workflows that GitHub's check-suite still registers on push. | Filtered out of every status query. | Never. |
-
-`task ci:status` (Phase A Step 6) is the canonical filter: it
-queries `gh run list`, drops Jobs-0 phantoms, then asserts the
-required-check set has zero non-success conclusions for the
-current HEAD SHA.
-
-## Blocking set — anchored to `branch-protection-policy.md`
-
-The blocking set is defined per PR shape (feature / release /
-docs-only) in [`branch-protection-policy.md`](branch-protection-policy.md)
-§ Per-PR-shape required-check matrix. The summary for `main`:
-
-- **Feature PR set** — `Consistency`, `Smoke Contracts`, `Skill Lint`,
-  `Tests` (every matrix entry), `Public Install Smoke`.
-- **Release PR set** — `Consistency`, `Smoke Contracts`, three
-  `Release Validation` jobs.
-- **Docs-only PR set** — `Consistency`, `Smoke Contracts`.
-
-`task ci:status` reads the same set when run with `--strict` (Phase
-A Step 6); the set is single-sourced from `scripts/ci_status.py`.
-
-## Advisory list — explicit non-blockers
-
-These workflows MAY fail without blocking merges. Each carries a
-documented rationale (link to the file header or roadmap step) so
-"advisory" never silently expands.
-
-| Workflow | Rationale | Promotion criterion |
-|---|---|---|
-| `bench-drift.yml` | Performance bench — informational only until the bench-stability roadmap completes. | Three consecutive green weekly runs after the bench is stabilised. |
-| `cloud-release.yml` | Release artefact publish — Hard-Floor adjacent fix pending. See [`02-deployment-failures.md`](../../agents/evidence/audits/2026-05-ci-triage/02-deployment-failures.md) § Finding 1. | Maintainer ships the rate-limit fix; smoke probe stays green for two consecutive releases. |
-| `deploy-mcp-worker.yml` | MCP worker deploy — auth contract regression pending. See [`02-deployment-failures.md`](../../agents/evidence/audits/2026-05-ci-triage/02-deployment-failures.md) § Finding 2. | Maintainer aligns the smoke probe with the Worker auth gate; passes for two consecutive deploys. |
-| `sync-visibility.yml` | `workflow_dispatch`-only mutator. GitHub registers a phantom 0-job failure on every push to main — documented in the workflow header. **Phantom, not advisory** — `task ci:status` filters it. | n/a; the filter is the fix. |
-| `check-visibility-drift.yml` | PR-paths + schedule + dispatch. Same GitHub Actions quirk produces phantom 0-job failures on push to main. **Phantom, not advisory.** | n/a; the filter is the fix. |
-
-Adding a row here is a maintainer-level call: the rationale must
-exist, and the promotion criterion must be writable.
-
-## Phantom 0-job runs — the filter
-
-A "phantom" run is one where:
-
-1. The workflow registers a check-suite entry on the commit, AND
-2. The run has `Jobs: 0` (no job actually executed), AND
-3. The conclusion is `failure`.
-
-This is a documented GitHub Actions quirk for `workflow_dispatch`-only
-workflows and for path-filtered workflows whose paths do not match
-the push diff. Removing the `push:` trigger does NOT eliminate the
-phantom; the check-suite still registers.
-
-`task ci:status` and `scripts/ci_status.py` drop any run with
-`Jobs: 0` from the tally before computing pass/fail. The phantom
-is visible in the GitHub UI but invisible to the gate.
-
-## Freeze rule — the mechanics
-
-When a commit lands on `main` and any required-check workflow turns
-red within ~5 minutes (the standard required-check window):
-
-1. The required-check status remains red on the merge commit.
-2. Subsequent PRs targeting `main` see the same required-check set
-   evaluated against the PR's head SHA. If the same workflow fails
-   again on the PR head, the PR is blocked.
-3. The maintainer either (a) reverts the offending commit, or (b)
-   ships a fix-forward PR that turns the required check green. No
-   PR merges meanwhile.
-
-The freeze is therefore behavioural, not enforced via a separate
-"freeze-mode" workflow — branch protection already does the
-gating. `freeze-guard.yml` ([source](../../.github/workflows/freeze-guard.yml))
-is a **different** mechanism: it locks the behavioural baseline of
-the work-engine via golden-transcript diff, and is a required check
-in the engine-path subset (not the universal floor). Both apply
-together; the names don't conflict.
-
-## What this contract is not
-
-- **Not a list of "all green workflows".** Advisory and phantom
-  reds are routine and do not constitute a violation.
-- **Not a guarantee against false-greens.** A workflow that ran
-  but tested nothing meaningful can still report success; the
-  contract only governs how red signals are routed.
-- **Not a license to add workflows to the blocking set silently.**
-  Promotion to blocking is a `branch-protection-policy.md` edit
-  with a written rationale and a maintainer review.
-
-## Re-audit cadence
-
-Re-audit on each of:
-
-- A new workflow lands in `.github/workflows/`.
-- A workflow is promoted from advisory to blocking (or vice versa)
-  in `branch-protection-policy.md`.
-- A new phantom-failure class is observed (e.g. GitHub Actions ships
-  behaviour the filter doesn't catch).
-- Quarterly review (Phase C of `road-to-ci-budget-and-cost.md` or
-  its successor).
-
-## See also
-
-- [`branch-protection-policy.md`](branch-protection-policy.md) —
-  the required-check matrix per PR shape.
-- [`release-pr-gating.md`](release-pr-gating.md) — release-PR shape
-  detection + cut surface.
-- [`../../agents/evidence/audits/2026-05-ci-triage/01-red-workflows.md`](../../agents/evidence/audits/2026-05-ci-triage/01-red-workflows.md)
-  — current red-workflow inventory.
-- `AGENTS.md` § Emergency triage — root-of-repo pointer for agents.

package/docs/contracts/command-category-governance.md

@@ -1,84 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-17
----
-
-# Command-category governance
-
-> **Status (2026-06-09):** Phase-2b resolved as **Option 1 (light)** — an
-> AI-council tie-break (claude-sonnet-4-5 + gpt-4o) chose light over a
-> full/blocking lint, decisively: no consumer reads `category:` today, so
-> populating all 54 + blocking CI is "supply without demand" (YAGNI), and a
-> blocking gate on a 15%-ambiguous taxonomy enforces *presence, not correctness*
-> — mis-calls made under CI pressure surface later as a re-categorization pass
-> ("pays the cost twice"). What shipped, and the upgrade trigger, are below.
-
-## Shipped (Option 1 — light)
-
-- **`category:` defined** as an OPTIONAL enum in `command.schema.json`
-  (`flow-entry | state-query | product-surface`), **validate-when-present** —
-  a declared value must be a valid enum; absence is fine. (Note: the 150
-  `src/domains/**/command.md` files are not yet full-schema-validated — a
-  pre-existing gap, separate from this field; the enum bites wherever
-  command-schema validation runs / when a consumer reads it.)
-- **Creation-time checklist** in the [`command-writing`](../../src/skills/command-writing/SKILL.md)
-  skill: categorize a NEW top-level command at authoring; fits-none → it's a
-  skill; genuinely ambiguous → omit `category:` and note why (intentionally
-  deferred, not forgotten). Sub-commands inherit the parent cluster's category.
-
-## Deferred — until the upgrade trigger fires
-
-**Full categorization of all 54 top-level commands + a blocking lint + the
-demotion of fits-none commands** are deferred. **Upgrade trigger:** a **merged
-consumer PR** — runnable code that *reads* `category:` (routing, analytics, a
-catalog/discovery grouping, a "daily five" surface). A design doc is not the
-trigger; running code that breaks on miscategorization is. When it lands,
-population + enforcement land together in one focused PR, with the consumer's
-requirements defining the ambiguous categories unambiguously.
-
-## The schema (to introduce in Phase 2)
-
-Every **visible** command (`suggestion.eligible: true`) declares one
-`category:` in its frontmatter, per [`ADR-048`](../decisions/ADR-048-command-justification-rule.md):
-
-```yaml
-category: flow-entry | state-query | product-surface
-```
-
-- **flow-entry** — a daily starting point the user TYPES to begin work
-  (`work`, `git-commit`, `review-changes`, `fix-ci`, …).
-- **state-query** — a read-only check typed many times a day
-  (`agent-status`, `project-health`, `profile-show`, …).
-- **product-surface** — a feature the user starts deliberately
-  (`council`, `challenge-me`, `research`, `roadmap`, `video-storyboard`).
-
-A command that fits **none** is, per ADR-048, a **skill** — so the lint doubles
-as a demotion signal. That demotion is a product-surface change and is exactly
-why this belongs in Phase 2 (own → age → contract), not a Phase-0 guardrail.
-
-## Inventory at hand-off (2026-06-09)
-
-- **150** command files (`find src/domains -name command.md`).
-- **125** are visible (`suggestion.eligible: true`) → the categorization set.
-- **0** currently carry a `category:` field.
-
-So Phase 2 must: (1) add the `category:` schema to the frontmatter contract +
-validator; (2) categorize the 125 visible commands (a per-command judgment under
-ADR-048, ideally after the Phase-2 ownership map assigns owners); (3) decide the
-demotion path for any command that fits none; (4) ship the `category:` lint as a
-blocking gate once the field is populated (start non-blocking/warn to avoid a
-flag-day, then flip).
-
-## Phase-0 closure
-
-Phase 0 closes on **step 7a** (the dead-doc-path CI guardrail —
-`check_references.py` extended to `docs/` + `src/`, with tests) **plus this
-hand-off**. The two guardrails guard orthogonal properties (path integrity vs
-command-surface justification), so shipping 7a without 7b creates no false
-confidence about command categorization.
-
-## See also
-
-- [`ADR-048`](../decisions/ADR-048-command-justification-rule.md) — the three-category contract.
-- [`command-clusters.md`](command-clusters.md) — the command-justification section ADR-048 locks.
-- Positioning roadmap Phase 2 — where the `category:` lint now lands.

package/docs/contracts/command-clusters.md

@@ -1,399 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# Command-cluster contract
-
-> **Status:** beta — Phase 1 locked for `1.15.0` (top-3 clusters);
-> Phase 2 locked for `1.17.0` (the remaining 12 clusters);
-> Phase 3 locked for `1.17.0` (`council` cluster).
-
-The agent-config command surface collapses related atomic commands
-into **verb clusters**. A cluster is a single top-level command
-(e.g. `/fix`) that dispatches to sub-commands (e.g. `/fix ci`,
-`/fix pr-comments`). Old atomic commands stay one release as deprecation
-shims, then disappear.
-
-This file is the **locked source of truth** for which clusters
-exist and which sub-commands belong to each. The atomic-command
-linter (`scripts/lint_no_new_atomic_commands.py`) reads this file;
-new atomic commands without a `cluster:` field pointing to an
-entry below fail CI.
-
-## Locked clusters
-
-The full set, both phases. Linter parses every backticked name in
-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` · `quality` · `route` | `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); `route` added 2026-07-15 (ecosystem-harvest ergonomics U1) — the classify-and-dispatch entry (adapted from the source's `/smart-fix`; folded into the `fix` verb family to satisfy the ADR-041 controlled-verb vocabulary without a new verb) |
-| `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` · `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) |
-| `tdd` | 2 | `red` · `green` · `refactor` | new cluster 2026-07-15 (ecosystem-harvest ergonomics U2) — thin per-phase ergonomic split over the `test-driven-development` skill; each sub drives one TDD phase, no logic duplication. Internal visibility. Bare `/tdd` shows the menu. |
-| `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` |
-| `git-commit` | 2 | `in-chunks` | `commit-in-chunks` · former cluster name `commit` — renamed 2026-06-09 to the path-derived pack-prefixed slug (`src/domains/git/commit/`, ADR-044 amendment; issue #380) |
-| `git-pr-create` | 2 | `description-only` | `create-pr-description` · former cluster `create-pr` — physically merged into the `pr` verb family at `src/domains/git/pr/create/` and renamed 2026-06-09 to the path-derived pack-prefixed slug (ADR-044 amendment; issue #380) |
-| `council` | 3 | `default` · `pr` · `design` · `optimize` · `analysis` | `council` (legacy default lens) · `council-pr` · `council-design` · `council-optimize`; `analysis` added 2026-05-14 — wrapper for local analysis outputs with a Top-N consensus tail block consumed by `/roadmap create` |
-| `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. |
-| `team` | 2 | `review` · `adversarial` · `delegate` · `status` | new 2026-07-12 (road-to-team-mode Phase 2) — cross-model depth review: thin fail-closed delegations to the official codex plugin on Claude-Code hosts under `ai_team` governance ([`ai-team-config`](ai-team-config.md)); default-off (`ai_team.enabled: false`), `delegate` behind the second opt-in `allow_delegate`; internal visibility until the ADR promotion gate |
-| `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` | 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). |
-| `humanize` | — | _(none yet — cluster head only)_ | new cluster 2026-07-11 (`road-to-humanized-writing` Phase 3) — on-demand AI-tell removal for deliverable prose (pasted text or file path) via the [`humanizer`](../../src/skills/humanizer/SKILL.md) skill's draft→audit→final loop + the `detect_ai_tells.ts` detector; `--voice=<slug\|me>` reuses the write-engine style-source resolution (no second voice mechanism). Counterpart to the engine-internal step 4b in [`write-engine`](write-engine.md). Single cluster head; sub-commands deferred until a second verb is needed. |
-| `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. |
-| `knowledge` | — | `ingest` · `list` · `forget` · `cross-repo` | local-knowledge namespace (employee-product Phase 7); `:cross-repo` added 2026-05-30 (`road-to-leaner-core-and-discovery` Phase 4) — read-only targeted retrieval over opted-in `linked_projects` siblings (ADR-032 Option A), per [`cross-repo-retrieval`](cross-repo-retrieval.md). The pre-existing `ingest`/`list`/`forget` sub-commands are recorded in the registry here for the first time. |
-| `skills` | — | `discover` | new cluster 2026-05-30 (`road-to-leaner-core-and-discovery` Phase 3) — local, explained skill-recommendation surface over the catalog + role shortlists + optional local analytics, per [`skill-discovery`](skill-discovery.md). Every result carries a non-empty `why`; no network, honours the analytics opt-out. |
-| `skill` | — | `preview` | new cluster 2026-05-30 (`road-to-leaner-core-and-discovery` Phase 5) — non-destructive skill/command preview: surfaces the declared steps + files/commands a skill would touch before it runs, per [`skill-dry-run`](skill-dry-run.md). Singular `skill` (one target) vs plural `skills` (the catalog) by design. |
-| `image` | — | `analyse` · `create` · `verify` | new cluster 2026-05-31 (`road-to-character-image-fidelity` Phase 4) — character-image fidelity surface mirroring `/video:*`. `:analyse` extracts a per-feature spec from an image and diffs it against a Canon Spec down to the smallest mole (OCR for lettered tattoos, per-section severity scores, canon-breaking hard gate); `:create` assembles a max-fidelity anchors-first generation prompt from the Canon Spec, governance- + provider-gated, `AIV_DRYRUN=true` default; `:verify` runs the analyser in loop mode against a candidate and reports the gate verdict + remaining diff with plateau/oscillation/budget stop conditions. Skills: [`image-analyser`](../../skills/image-analyser/SKILL.md) + [`image-creator`](../../skills/image-creator/SKILL.md); schema/rubric/loop in [`canon-spec.md`](../../skills/image-analyser/canon-spec.md). |
-| `brand` | — | `strategy` · `identity` · `tokens` · `review` · `voice` | new cluster 2026-06-17 (`road-to-image-brand-followups` Phase 3) — brand-as-first-class-UX surface for `pack-brand`, consulted before `design-intelligence` so brand bounds style. `:strategy` (positioning/archetype/voice/messaging over the brand corpus), `:identity` (logo/colour/type/imagery direction — defines the tokens downstream generation consumes), `:tokens` (derive a DTCG `.tokens.json` source of truth → CSS/Tailwind, no Node), `:review` (audit emitted UI/copy/assets against active brand tokens + voice per the `brand-consistency` gate), `:voice` (voice-and-tone profile). Skills: [`brand-strategy`](../../skills/brand-strategy/SKILL.md) · [`brand-identity`](../../skills/brand-identity/SKILL.md) · [`brand-to-tokens`](../../skills/brand-to-tokens/SKILL.md) · [`brand-audit`](../../skills/brand-audit/SKILL.md) · [`voice-and-tone-design`](../../skills/voice-and-tone-design/SKILL.md). The companion `/imagegen:*` generation cluster (pack-ai-image) is deferred until its adapters' live submit/poll/fetch is wired. |
-
-| `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. 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.
-
-## Reserved host names — Claude Code never gets a shadowing `/name`
-
-Locked 2026-07-10 (observed: a user-scope `mcp` skill shadowed Claude
-Code's built-in `/mcp` auth dialog). A cluster head or skill whose name
-equals a Claude Code built-in command or bundled skill (`review`,
-`agents`, `memory`, `mcp`, `code-review`, `bug`, `context`, `cost`,
-`skills`, … — canonical set in `src/scripts/_lib/claude_builtin_names.ts`)
-is **withheld from Claude-facing `/name` projections**: the
-`.claude/skills/` command entry is skipped by `condense.ts`, and the
-user-scope installer deploys neither a skill wrapper nor a flat command
-file. Nested `/cluster:sub` commands are unaffected (hyphen/colon-joined
-slugs cannot collide). Skills that keep a reserved name opt out of slash
-registration with `user-invocable: false` (model-invocation only);
-`lint_agent_skill_names.ts` fails CI otherwise. The suite complements
-the host — it never overlays or degrades a built-in. On such names the
-bare-invocation contract above applies to every tool **except** Claude
-Code, where the built-in owns `/name`.
-
-## Cluster depth and sub-command naming
-
-Locked by [ADR-003](../decisions/ADR-003-flat-cluster-subs-and-colon-syntax.md)
-(2026-05-07). The shape is the default for **every** new cluster and
-every new sub-command added to an existing cluster.
-
-1. **Flat only.** A cluster has exactly one level of sub-commands.
-   No sub-sub-commands. A dispatcher routes `/cluster <sub>` to a
-   single sub-file; sub-files do not dispatch further. Two-level
-   dispatch is a deliberate contract change requiring a new ADR
-   superseding ADR-003.
-
-2. **Composite sub-names for verb+scope.** When a cluster carries
-   multiple verbs (e.g. authoring + execution), encode the verb in
-   the sub-name, joined with `-`:
-
-   - ✅ `/roadmap:create` · `/roadmap:process-step` ·
-     `/roadmap:process-phase` · `/roadmap:process-full`
-   - ❌ `/roadmap:process:phase` (sub-sub — forbidden)
-   - ❌ `/roadmap:step` · `/roadmap:phase` · `/roadmap:full`
-     (verb hidden — breaks symmetry with `create`)
-   - ❌ separate `/roadmap-process` cluster (domain split — forbidden
-     when one cluster can carry both verbs flat)
-
-   Sibling sub-names stay in the same shape: either all bare verbs,
-   all bare nouns/scopes, or all composite. Mixing bare and composite
-   in the same cluster is allowed only when the bare sibling is the
-   cluster's primary verb (e.g. `/roadmap:create` + `process-*`
-   composites).
-
-3. **Sub-name format.** kebab-case (`pr-bot-comments`, `process-phase`),
-   ≤ 24 chars, no leading verb that duplicates the cluster name
-   (use `/fix:ci`, not `/fix:fix-ci`).
-
-4. **Colon-canonical invocation.**
-   `/<cluster>:<sub>` is the canonical form everywhere — catalog,
-   docs, examples, deprecation warnings. The space-separated form
-   `/<cluster> <sub>` is a first-class equivalent and routes to the
-   same dispatcher; it must keep working. Autocompletion-aware UIs
-   surface the colon form because it stays a single token. Full
-   semantics: [`slash-command-routing-policy-mechanics.md`](../../.agent-src.uncondensed/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md)
-   § Routing semantics.
-
-## Command justification — a command must earn a top-level slot
-
-```
-A NEW COMMAND ONLY EARNS A TOP-LEVEL SLOT IN THREE CASES.
-EVERYTHING ELSE IS A SKILL — THE AGENT TRIGGERS IT BY TASK.
-```
-
-Before adding a command, answer: which of these is it?
-
-1. **Flow-entry** — a daily starting point of a flow the user TYPES to begin
-   work (`work`, `git-commit`, `git-pr-create`, `ticket-implement`,
-   `feature-plan`, `review-changes`, `fix-ci`, `test-run`).
-2. **State-query** — a read-only check typed many times a day (`agent-status`,
-   `project-health`, `profile-show`).
-3. **Product-surface** — a FEATURE the user starts deliberately (not daily, but
-   consciously): `council`, `challenge-me`, `research`, `roadmap`,
-   `video-storyboard`. These are products, not implementation helpers — burying
-   them as skills destroys discoverability.
-
-If none of the three, it is a **skill**. Skills already trigger automatically by
-task, so a sub-action, a one-off/setup-once op, a pipeline stage, a destructive
-op (skill + mandatory confirmation gate — destructive ≠ command), or a system /
-admin op (the `agent-admin` platform surface, NOT a flow) does NOT need a
-top-level command. Sibling variants become a flag, never a second command
-(`commit`, not `commit-in-chunks`; `roadmap --step`, not a separate
-`roadmap-process-step` — and `roadmap` with no scope defaults to processing the
-WHOLE roadmap, because that is why you write one). A new verb still needs an ADR
-per [`ADR-041`](../decisions/ADR-041-controlled-command-verbs.md). A genuine
-skill is `code-review` / `git-workflow` / `testing` — never `council` /
-`challenge-me` / `research`.
-
-> The rule that ends "should X be a command?" — a proposed `jira-comment`: not
-> flow-entry, not state-query, not a product-surface feature → skill. Done. The
-> sweet spot is ~40–50 visible commands (workflow + status + product features),
-> not 125 (overwhelms) and not ~29 (buries features). Converged across the
-> 6.0.0-D council passes + feedback (2026-06-03); the dedicated ADR is authored
-> during the 6.0.0-D structural rollout.
-
-## Frontmatter contract
-
-A new command file under `.agent-src.uncondensed/commands/` MUST
-declare `cluster:` in its frontmatter, pointing to one of the locked
-clusters above:
-
-```yaml
----
-name: fix-ci          # legacy slug retained for the shim
-cluster: fix          # required: locked cluster name
-sub: ci               # required: sub-command identifier (kebab-case)
-description: Fetch CI errors from GitHub Actions and fix them
----
-```
-
-The linter only flags **newly-added** files under `commands/`
-(git status `A`). Pre-existing commands without `cluster:` are
-grandfathered indefinitely; modifying them does NOT require adding
-the field. The goal is to stop the atomic surface from growing,
-not to retro-fit every legacy command into a cluster.
-
-## Master / wrapper sub-command shape (`council` cluster)
-
-The `council` cluster uses a **master / wrapper** shape within the flat
-ADR-003 dispatch — the only cluster currently shaped this way. It does
-not break ADR-003 (still one level of sub-commands) and is documented
-here so future lens additions follow the same shape.
-
-- **Master:** `/council default` owns the full orchestration — Step 1
-  (resolve target + capture `original_ask`), Step 2 (configure check +
-  price-table freshness), Step 3 (cost confirmation), Step 4 (run CLI),
-  Step 5 / 5a / 5b (render → critical-evaluation lens → user options),
-  Step 6 (hard floor). See [`commands/council.md` → `## Architecture`](../../.agent-src.uncondensed/commands/council.md).
-- **Wrappers:** `/council pr` · `/council design` · `/council optimize`
-  resolve lens-specific input (PR target / design artefact / optimization
-  target + metric), capture a wrapper-specific `original_ask`, then
-  delegate to `/council default` with `mode_override=<lens>`. They MUST
-  NOT re-implement cost-gate, CLI invocation, render, or host-verdict;
-  those flow through the master verbatim. Wrapper step references anchor
-  to the master (e.g. "cost gate from `/council default` Step 3",
-  "render via Step 5/5a/5b of `/council default`"), not the wrapper.
-- **Single source of lens addendums:** lens-specific neutrality
-  addendums live in [`scripts/ai_council/prompts.py:_MODE_TABLE`](../../src/scripts/ai_council/prompts.py)
-  and are selected by `mode_override`. A new lens = a new `_MODE_TABLE`
-  entry **plus** a new wrapper file mirroring the `pr.md` / `design.md` /
-  `optimize.md` shape (~100–130 lines). No new master.
-- **Behavioural changes** to the orchestration (e.g. a new render step)
-  land in `default.md` + `_MODE_TABLE` only; wrappers inherit
-  automatically. This invariant is what makes the shape safe under the
-  flat ADR-003 contract — the wrapper is text-only delegation.
-
-Cluster-table names are unchanged: `/council default` is the master,
-the other wrappers (`pr`, `design`, `optimize`, `analysis`) follow the
-same shape. The deprecation shims for the four legacy slugs (`/council`,
-`/council-pr`, `/council-design`, `/council-optimize`) continue to
-follow the standard shim contract below.
-
-### Wrapper output shapes (consumer contract)
-
-Each wrapper renders the standard stacked + Convergence/Divergence
-layout from `/council default` Step 5/5a/5b. Wrappers MAY append a
-**lens-specific tail block** when their output is the input to a
-downstream command — locking the tail shape avoids brittle scraping.
-
-| Wrapper | Tail block | Downstream consumer |
-|---|---|---|
-| `pr` | (optional) one-line PR header at top; no structured tail | `gh pr comment` (opt-in single comment) |
-| `design` | (none — open-ended prose) | Human reader; `/feature plan` / `/feature refactor` |
-| `optimize` | (none — open-ended prose) | Human reader |
-| `analysis` | `## Top-N consensus findings (roadmap-ready first)` — numbered list, each finding with `evidence-grade` (confirmed / inferred / speculative), `roadmap-ready` (yes / needs-discovery), `cited by`, `supporting citation` | `/roadmap create` |
-
-The `analysis` Top-N block is the only structured tail shipped today.
-Its fields are normative — `/roadmap create` parses them to draft a
-roadmap; renaming or reordering them is a breaking change for the
-council → roadmap pipeline. Cap at N=10 unless the upstream analysis
-has fewer findings.
-
-## Deprecation shim contract
-
-A shim is a one-file stub that:
-
-1. Keeps the old command slug in `.agent-src.uncondensed/commands/`.
-2. Declares `superseded_by:` in frontmatter pointing to the new
-   cluster command (e.g. `superseded_by: fix ci`).
-3. Declares `deprecated_in:` with the release version (e.g.
-   `deprecated_in: 1.15.0`).
-4. Body contains exactly one warning line in the format:
-   ```
-   ⚠️  /<old-name> is deprecated; use /<cluster> <sub> instead.
-   ```
-5. Otherwise forwards verbatim to the cluster command (no logic).
-
-`scripts/skill_linter.py` enforces the warning-line shape on any
-file with `superseded_by:` set.
-
-## Removal cycle
-
-| State | Phase 1 | Phase 2 |
-|---|---|---|
-| Cluster command shipped, shim active | `1.15.0` | `1.17.0` |
-| Shim emits warning, both work | `1.15.x` / `1.16.x` (≥ one minor cycle) | `1.17.x` (one minor cycle) |
-| Shim removed, only cluster works | `1.17.0` (Phase 1 atomics removed alongside Phase 2 lock-in) | next minor after `1.17.x` |
-
-No permanent aliases. Consumers who pin a 1.17 minor get a full
-release window of warnings; the next-minor release notes call out
-the removal explicitly. The 1.17.0 release ships Phase 2 cluster
-locks **and** drops the seven Phase 1 atomic shims at the end of
-their deprecation cycle.
-
-## Agent-doc consolidation (2026-05-09)
-
-Single-release breaking change folding seven scattered agent-doc
-commands into the `/agents` (file-family) and `/optimize agents-dir`
-surfaces. Frequency-weighted: high-use AGENTS.md operations get the
-short `/agents` namespace; low-use folder ops nest under `/optimize`.
-
-| Old command | New command | Note |
-|---|---|---|
-| `/optimize agents-md` | `/agents optimize` | Thin-Root refactor folded into `/agents` |
-| `/optimize agents` | `/agents audit` | read-only audit folded into `/agents`; `audit` + `check` collapsed |
-| `/agents prepare` | `/optimize agents-dir` | `--scaffold` flag or wizard mode |
-| `/agents audit` (folder) | `/optimize agents-dir` | `--audit` flag |
-| `/agents cleanup` | `/optimize agents-dir` | `--fix` flag |
-
-Cluster `/copilot-agents` is retired; the file-family operations now
-live under `/agents` (`init`, `optimize`).
-
-## Linter behavior
-
-`scripts/lint_no_new_atomic_commands.py`:
-
-- Reads the locked cluster names from this file (parsed from the
-  "Locked clusters" table above — column 1 backticks).
-- Finds every command file **added** since `--baseline`
-  (default: `main`) — modifications to existing files are ignored.
-- For each new file, requires `cluster:` to be set to one of the
-  locked names — OR `superseded_by:` (the file is a shim).
-- Exits non-zero on the first violation; lists every violator.
-
-`--all` mode (manual audit only, not in CI) lints every command
-file and surfaces grandfathered ones — useful when planning a
-future cluster expansion.
-
-`scripts/check_cluster_patterns.py` (Phase 2 onward):
-
-- Compares each cluster dispatcher's structure against the Phase 1
-  reference patterns (`commands/fix.md`, `commands/optimize.md`,
-  `commands/feature.md`).
-- Required sections: top-of-file `# /<cluster>`, `## Sub-commands`
-  table with `Sub-command | Routes to | Purpose` columns, `## Dispatch`
-  steps, `## Migration` notice, `## Rules` block.
-- Fails CI if a new cluster invents a different dispatch shape.
-
-## Tier-usage signal contract
-
-Empirical retiering needs evidence; evidence needs a signal. The minimum signal the package collects to validate command tiering, with **zero new external surface** and the same privacy floor as artefact-engagement telemetry:
-
-| Field | Type | Source | Notes |
-|---|---|---|---|
-| `ts_bucket` | str (ISO-8601 UTC, hour-resolution) | clock at invocation | hour-bucket, not raw timestamp — limits re-identification |
-| `command` | str | dispatcher | the cluster + sub-command (`fix:ci`, `commit`, `work`) — never argv |
-| `tier` | int (0/1/2/3) | `command-surface-tiers.md` lookup at invocation | the tier the command had **at the time of the call** |
-| `outcome` | str | dispatcher exit shape | one of `success` / `error` / `blocked` — no message bodies |
-| `user_hash` | str (sha256 first 16 hex chars) | hash of `$USER` + machine-id salt | distinct-user counting **without** identity recovery — never raw login |
-
-**Forbidden — never recorded, enforced at the four privacy layers:**
-
-- argv, flags, file paths, file contents.
-- error messages, stdout, stderr.
-- tickets, branch names, repo slugs.
-- exact timestamps (only hour-buckets), exact env-var values.
-- the user's name, email, or IP.
-
-**Storage.** Append to `.agent-tier-usage.jsonl` (consumer-project root; configurable via `telemetry.tier_usage.output.path`). Separate file from `.agent-engagement.jsonl` — orthogonal signals, separate retention defaults, separate opt-in.
-
-**Settings gate.** `telemetry.tier_usage.enabled` (default `false`, same opt-in posture as artefact-engagement). When disabled, the dispatcher records nothing and incurs zero file IO — the default-off doctrine carries over.
-
-**Aggregation.** Local-only, hour-bucketed counts: `(command, tier) → invocation_count` and `(command, tier) → distinct_user_count`. No remote upload anywhere in scope.
-
-## Empirical retiering rule
-
-A command **stays at Tier-0** at the next minor release only if **both** floors clear:
-
-- **Frequency floor.** ≥ N invocations across the trailing W-day window — defaults `N = 20`, `W = 30` (tunable via `.agent-settings.yml` `telemetry.tier_usage.retier`).
-- **Distinct-user floor.** ≥ K distinct `user_hash` values across the same window — default `K = 3`.
-
-A command that fails either floor drops to **Tier-1** at the next minor release; the release notes cite the floor that failed. Promotion the other way (Tier-1 → Tier-0) follows the same rule symmetrically and additionally requires explicit listing in `command-surface-tiers.md`.
-
-**Authority.** This is a maintainer decision aid, not an autonomous rule — the dispatcher records, `scripts/telemetry/tier_usage_report.py` reports, the maintainer files the move in the next minor release. No runtime tier-flipping.
-
-**Floor governance.** N / W / K live in `.agent-settings.yml`; bumping them is a contract change (this file), not a settings change.
-
-## See also
-
-- [`docs/migrations/commands-1.15.0.md`](../migrations/commands-1.15.0.md) — user-facing migration notes.
-- [`docs/contracts/STABILITY.md`](STABILITY.md) — `beta` level rules apply.
-- [`docs/contracts/command-surface-tiers.md`](command-surface-tiers.md) — what each tier means and what `--help` surfaces.
-- [`docs/contracts/command-taxonomy.md`](command-taxonomy.md) — profile axis (discoverability) layered on top of this verb axis (invocation).
-- [`.agent-src.uncondensed/contexts/contracts/artifact-engagement-flow.md`](../../.agent-src.uncondensed/contexts/contracts/artifact-engagement-flow.md) — sibling telemetry surface; same privacy floor and four-layer enforcement model.