@event4u/agent-config 6.0.0 → 7.0.0

package/docs/command-flows.md

@@ -7,7 +7,7 @@
 
 > Every command is classified in `src/flows/surface-map.yaml` (coverage enforced by `scripts/lint_command_flow_coverage.py`). The four user-work flows carry rich definitions in `src/flows/<flow>.yaml`.
 
-**150 commands** across **10 surfaces** (4 user-work flows + 6 platform/domain surfaces).
+**148 commands** across **10 surfaces** (4 user-work flows + 6 platform/domain surfaces).
 
 ## User-work flows
 
@@ -25,10 +25,10 @@ _Explore, plan, estimate, refine, and investigate before building. The "what sho
 - `bug-investigate` — Investigate a bug — auto-detect ticket from branch, gather Jira/Sentry/description context, trace root cause
 - `estimate-ticket` — Estimate a Jira/Linear ticket before sprint planning — size + risk + split recommendation + uncertainty, si…
 - `feature` — Feature orchestrator — routes to explore, plan, refactor, roadmap, dev
-- `feature:explore` — Brainstorm and explore a feature idea before committing to a full plan
-- `feature:plan` — Interactively plan a feature — research, discuss, and create a structured feature document
-- `feature:refactor` — Refine and update an existing feature plan through interactive discussion
-- `feature:roadmap` — Generate implementation roadmap(s) from a feature plan and link them
+- `feature-explore` — Brainstorm and explore a feature idea before committing to a full plan
+- `feature-plan` — Interactively plan a feature — research, discuss, and create a structured feature document
+- `feature-refactor` — Refine and update an existing feature plan through interactive discussion
+- `feature-roadmap` — Generate implementation roadmap(s) from a feature plan and link them
 - `project-analyze` — Full project analysis — detect stack, inventory modules, audit docs, create missing contexts
 - `project-health` — Quick project health check — show status of docs, modules, contexts, and roadmaps without creating anything
 - `refine-ticket` — Refine a Jira/Linear ticket before planning — rewritten ticket + Top-5 risks + persona voices, orchestrates…
@@ -44,13 +44,13 @@ _Build it. The core "make the change" front — drive a prompt, ticket, or featu
 - `bug-fix` — Plan and implement a bug fix — based on investigation, with quality checks and test verification
 - `e2e-heal` — Find, debug, and fix failing Playwright E2E tests
 - `e2e-plan` — Explore the application and create a structured E2E test plan in Markdown
-- `feature:dev` — Full 7-phase feature development workflow for complex features.
+- `feature-dev` — Full 7-phase feature development workflow for complex features.
 - `implement-ticket` — Drive a ticket end-to-end through refine → memory → analyze → plan → implement → test → verify → report — O…
 - `jira-ticket` — Read Jira ticket from branch name, analyze linked Sentry issues, implement feature or fix bug
-- `module:create` — Create a new module from .module-template with interactive setup
+- `module-create` — Create a new module from .module-template with interactive setup
 - `tests` — Tests orchestrator — routes to create, execute
-- `tests:create` — Write meaningful tests for the current branch — stack-adaptive (pest / phpunit / vitest / jest / pytest / …)
-- `tests:execute` — Run the project's test suite — stack-adaptive (pest / phpunit / vitest / jest / pytest / …)
+- `tests-create` — Write meaningful tests for the current branch — stack-adaptive (pest / phpunit / vitest / jest / pytest / …)
+- `tests-execute` — Run the project's test suite — stack-adaptive (pest / phpunit / vitest / jest / pytest / …)
 - `update-form-request-messages` — Sync the messages() method of a FormRequest class — add missing entries, link them to language keys, and cl…
 - `work` — Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Op…
 
@@ -62,11 +62,11 @@ _Check it. Self-review, judge, quality-fix, and threat-model a change before it
 
 **Default path:** `review-changes` → `judge` → `quality-fix` → `threat-model`
 
-- `fix:ci` — Fetch CI errors from GitHub Actions and fix them
+- `fix-ci` — Fetch CI errors from GitHub Actions and fix them
 - `judge` — Judge orchestrator — routes to solo, steps, on-diff
-- `judge:on-diff` — Run a single change through an implementer→judge loop with a two-revision ceiling, then hand back to the user
-- `judge:solo` — Run a standalone judge on an existing diff or code change — no implementer, no revision loop, verdict only
-- `judge:steps` — Execute an ordered plan step by step with a judge gate between steps — stops on first failed verdict
+- `judge-on-diff` — Run a single change through an implementer→judge loop with a two-revision ceiling, then hand back to the user
+- `judge-solo` — Run a standalone judge on an existing diff or code change — no implementer, no revision loop, verdict only
+- `judge-steps` — Execute an ordered plan step by step with a judge gate between steps — stops on first failed verdict
 - `quality-fix` — Run quality pipeline (PHP and/or JS/TS) and fix all errors — auto-detects language from changed files
 - `review-changes` — Self-review local changes before creating a PR — dispatches to five specialized judges (bug, security, test…
 - `threat-model` — Run a pre-implementation threat model on a proposed change — enumerates abuse cases, trust boundaries, and…
@@ -81,13 +81,13 @@ _Ship it. Commit in logical chunks, open the PR, answer review comments, and pre
 
 - `git-commit` — Stage and commit all uncommitted changes — splits into logical commits following Conventional Commits
 - `git-commit-in-chunks` — Stage and commit all uncommitted changes in logical chunks WITHOUT confirmation — sibling of /commit for au…
-- `fix` — Fix orchestrator — routes to ci, references, portability, seeder, pr-comments, pr-bot-comments, pr-develope…
-- `fix:portability` — Find and fix project-specific references in shared .augment/ package files
-- `fix:pr-bot-comments` — Fix and reply to bot review comments (Copilot, Augment, Greptile, etc.) on a GitHub PR
-- `fix:pr-comments` — Fix and reply to all open review comments (bots + human reviewers) on a GitHub PR
-- `fix:pr-developer-comments` — Fix and reply to human reviewer comments on a GitHub PR
-- `fix:refs` — Find and fix broken cross-references in .augment/ and agents/ files
-- `fix:seeder` — Scan seeder data files for broken foreign key references — find constants used without getReference() and f…
+- `fix` — Fix orchestrator — routes to ci, references, portability, seeder, pr-comments
+- `fix-portability` — Find and fix project-specific references in shared .augment/ package files
+- `fix/pr-bot-comments`
+- `fix-pr-comments` — Fix and reply to all open review comments (bots + human reviewers) on a GitHub PR
+- `fix/pr-developer-comments`
+- `fix-refs` — Find and fix broken cross-references in .augment/ and agents/ files
+- `fix-seeder` — Scan seeder data files for broken foreign key references — find constants used without getReference() and f…
 - `git-pr-create` — Create a GitHub PR with structured description from Jira ticket and code changes
 - `git-pr-create-description-only` — Generate a PR description as a copyable markdown block — used standalone or by create-pr
 - `prepare-for-review` — Prepare a PR branch for local review — updates main and merges the full branch chain so the branch is up to…
@@ -99,93 +99,91 @@ _Ship it. Commit in logical chunks, open the PR, answer review comments, and pre
 _Deliberately-started features — not daily flow members, never buried as skills._
 
 - `challenge-me` — Challenge-me orchestrator — routes to vision, with-docs
-- `challenge-me:vision` — Stress-test a plan or idea by one-question-at-a-time interview until 95% confidence — emits a copyable Mark…
-- `challenge-me:with-docs` — Doc-aware /challenge-me — 95%-confidence interview with session glossary vs CONTEXT.md, load-bearing claim-…
+- `challenge-me-vision` — Stress-test a plan or idea by one-question-at-a-time interview until 95% confidence — emits a copyable Mark…
+- `challenge-me-with-docs` — Doc-aware /challenge-me — 95%-confidence interview with session glossary vs CONTEXT.md, load-bearing claim-…
 - `council` — Council orchestrator — routes to default, pr, design, optimize, analysis, debate
-- `council:analysis` — Run the council on a local analysis output (project-analyze, audit script, codebase scan) — critiques the a…
-- `council:debate` — Multi-round council debate with progressive cost disclosure — each member produces a position, then rebuts…
-- `council:default` — Default council lens — neutral framing, redacted context, advisory output only. Run `/council default <inpu…
-- `council:design` — Run the council on a design document, ADR, or architecture proposal — surfaces hidden coupling, missing rol…
-- `council:optimize` — Run the council on an optimization target — perf hot path, memory pattern, query, or an /optimize-* output…
-- `council:pr` — Pull a GitHub PR via gh CLI and run the council on the diff with a PR-specific neutrality preamble — read-o…
+- `council-analysis` — Run the council on a local analysis output (project-analyze, audit script, codebase scan) — critiques the a…
+- `council-debate` — Multi-round council debate with progressive cost disclosure — each member produces a position, then rebuts…
+- `council-default` — Default council lens — neutral framing, redacted context, advisory output only. Run `/council default <inpu…
+- `council-design` — Run the council on a design document, ADR, or architecture proposal — surfaces hidden coupling, missing rol…
+- `council-optimize` — Run the council on an optimization target — perf hot path, memory pattern, query, or an /optimize-* output…
+- `council-pr` — Pull a GitHub PR via gh CLI and run the council on the diff with a PR-specific neutrality preamble — read-o…
 - `grill-me` — Alias for /challenge-me — interactive grill-style interview that sharpens a fuzzy plan/idea into a copyable…
 - `research` — Preliminary research scaffolder — pick objects, define fields, emit `outline.yaml` + `fields.yaml` for down…
-- `research:deep` — Read `outline.yaml`, research each item in batches, write per-item JSON validated against the project-local…
-- `research:report` — Summarise per-item JSON results from `/research:deep` into `report.md`. Agent renders directly + emits an o…
+- `research-deep` — Read `outline.yaml`, research each item in batches, write per-item JSON validated against the project-local…
+- `research-report` — Summarise per-item JSON results from `/research:deep` into `report.md`. Agent renders directly + emits an o…
 - `roadmap` — Roadmap orchestrator — routes to create (authoring) and process-step / process-phase / process-full (autono…
-- `roadmap:ai-council` — Challenge a roadmap with the AI council (deep tier) and refactor from convergence findings. Wraps `/council…
-- `roadmap:create` — Interactively create a new roadmap file in agents/roadmaps/
-- `roadmap:process-full` — Autonomously process every open step across every phase of a roadmap until the file is fully closed. Larges…
-- `roadmap:process-phase` — Autonomously process every open step in the next or current phase of a roadmap, then stop. Default executio…
-- `roadmap:process-step` — Autonomously process the single next open step of a roadmap and stop. Smallest execution scope of the /road…
+- `roadmap-ai-council` — Challenge a roadmap with the AI council (deep tier) and refactor from convergence findings. Wraps `/council…
+- `roadmap-create` — Interactively create a new roadmap file in agents/roadmaps/
+- `roadmap-process-full` — Autonomously process every open step across every phase of a roadmap until the file is fully closed. Larges…
+- `roadmap-process-phase` — Autonomously process every open step in the next or current phase of a roadmap, then stop. Default executio…
+- `roadmap-process-step` — Autonomously process the single next open step of a roadmap and stop. Smallest execution scope of the /road…
 
 ### Platform surface — `agent-admin`
 
 _The system/admin surface (NOT a flow): memory · analytics · governance · config · introspection, reached on demand._
 
 - `agents` — Agent-layer orchestrator — routes to init, optimize, audit. Covers AGENTS.md and its multi-tool stubs (CLAU…
-- `agents:audit` — Audit agent infrastructure — token overhead, rule triggers, AGENTS.md health, Capability-over-Structure adh…
-- `agents:init` — Initialize the agent layer for a consumer project — creates AGENTS.md and .github/copilot-instructions.md f…
-- `agents:optimize` — Refactor AGENTS.md to the Thin-Root contract (caps, pointer ratio, capability bullets, emergency-triage) an…
-- `agents:user` — User-persona file (.agent-user.md) — interview, render, and maintain who the user is and how they want to b…
-- `agents:user-accept` — Apply a buffered observation to .agent-user.md after explicit user confirmation; bumps last_updated and dro…
-- `agents:user-init` — Interactive interview that creates the project-root .agent-user.md from the locked v1 schema (name, languag…
-- `agents:user-review` — List buffered observations from .agent-user.observations.jsonl with numbered options to inspect or accept i…
-- `agents:user-show` — Read-only render of .agent-user.md — prints the persona summary the host agent loads at session start.
-- `agents:user-update` — Open .agent-user.md in the user's IDE for manual edit; validates schema and 100-line cap on save.
+- `agents-audit` — Audit agent infrastructure — token overhead, rule triggers, AGENTS.md health, Capability-over-Structure adh…
+- `agents-init` — Initialize the agent layer for a consumer project — creates AGENTS.md and .github/copilot-instructions.md f…
+- `agents-optimize` — Refactor AGENTS.md to the Thin-Root contract (caps, pointer ratio, capability bullets, emergency-triage) an…
+- `agents-user` — User-persona file (.agent-user.md) — interview, render, and maintain who the user is and how they want to b…
+- `agents-user-accept` — Apply a buffered observation to .agent-user.md after explicit user confirmation; bumps last_updated and dro…
+- `agents-user-init` — Interactive interview that creates the project-root .agent-user.md from the locked v1 schema (name, languag…
+- `agents-user-review` — List buffered observations from .agent-user.observations.jsonl with numbered options to inspect or accept i…
+- `agents-user-show` — Read-only render of .agent-user.md — prints the persona summary the host agent loads at session start.
+- `agents-user-update` — Open .agent-user.md in the user's IDE for manual edit; validates schema and 100-line cap on save.
 - `analytics` — Analytics orchestrator — routes to show, prune. Local-only workspace event log under `~/.event4u/agent-conf…
-- `analytics:prune` — Drop events older than the 90-day retention window from the local analytics log. Atomic and idempotent.
-- `analytics:show` — Render top prompts, launcher → completion rate per role, average session length, and knowledge-source usage…
-- `chat-history` — Chat-history orchestrator — routes to show, import, learn
-- `chat-history:import` — Surface prior chat-history sessions as a numbered table, let the user pick one, read it silently, and emit…
-- `chat-history:learn` — Pick a prior chat-history session and mine it for project-improving learnings — runs learning-to-rule-or-sk…
-- `chat-history:show` — Show the status of the persistent chat-history log — file size, entry count, header fingerprint, age, and t…
-- `check-current-md`
-- `condense` — Condense .md files from .agent-src.uncondensed/ into telegraph format and write to dist/agent-src/
+- `analytics-prune` — Drop events older than the 90-day retention window from the local analytics log. Atomic and idempotent.
+- `analytics-show` — Render top prompts, launcher → completion rate per role, average session length, and knowledge-source usage…
+- `chat-history` — Chat-history orchestrator — routes to import (selective cross-session resume). Mining moved to /memory mine…
+- `chat-history-import` — Surface prior chat-history sessions as a numbered table, let the user pick one, read it silently, and emit…
+- `check-current-md` — Check the open .md file (or a passed path) for German outside DE:/EN: anchor blocks — umlauts, function wor…
+- `condense` — Condense .md files from src/ into telegraph format and write to dist/agent-src/
 - `context` — Context orchestrator — routes to create, refactor
-- `context:create` — Analyze a codebase area and create a structured context document
-- `context:refactor` — Analyze, update, and extend an existing context document
+- `context-create` — Analyze a codebase area and create a structured context document
+- `context-refactor` — Analyze, update, and extend an existing context document
 - `cost-report` — Capture token cost from the active Claude Code session, append to the local sessions store, and surface the…
 - `knowledge` — Knowledge orchestrator — routes to ingest, list, forget. Local-only file ingestion into the agent memory na…
-- `knowledge:cross-repo` — Targeted, read-only retrieval over opted-in linked-project siblings (ADR-032 Option A). Pulls a shared type…
-- `knowledge:forget` — Drop a knowledge ingest from `agents/memory/knowledge/` by id prefix. Atomic, no partial state. Pinning pro…
-- `knowledge:ingest` — Walk a local path (folder, .zip, single file), redact PII + secrets, chunk to 2 KB markdown, and persist in…
-- `knowledge:list` — List existing knowledge ingests in `agents/memory/knowledge/` (table or JSON); pin / unpin by id prefix to…
+- `knowledge-cross-repo` — Targeted, read-only retrieval over opted-in linked-project siblings (ADR-032 Option A). Pulls a shared type…
+- `knowledge-forget` — Drop a knowledge ingest from `agents/memory/knowledge/` by id prefix. Atomic, no partial state. Pinning pro…
+- `knowledge-ingest` — Walk a local path (folder, .zip, single file), redact PII + secrets, chunk to 2 KB markdown, and persist in…
+- `knowledge-list` — List existing knowledge ingests in `agents/memory/knowledge/` (table or JSON); pin / unpin by id prefix to…
 - `memory` — Memory orchestrator — routes to add, load, mine-session, promote, propose
-- `memory:add` — Interactively add a validated entry to an engineering-memory file (domain-invariants, architecture-decision…
-- `memory:learn-low-impact` — Preview validated low-impact entries that would be upstreamed to the package seed (default `--preview`); `-…
-- `memory:load` — Load ALL curated entries of a given memory type into the current context — opt-in full load for deep analys…
-- `memory:mine-session` — Mine the active session transcript for memory signals (corrections, preferences, decisions, recurring patte…
-- `memory:promote` — Promote an intake signal (or provisional proposal) into a curated memory entry — opens a PR and runs the ad…
-- `memory:propose` — Append a provisional memory signal to the intake stream — the universal fallback for any producer (human or…
+- `memory-add` — Interactively add a validated entry to an engineering-memory file (domain-invariants, incident-learnings, p…
+- `memory-learn-low-impact` — Preview validated low-impact entries that would be upstreamed to the package seed (default `--preview`); `-…
+- `memory-load` — Load ALL curated entries of a given memory type into the current context — opt-in full load for deep analys…
+- `memory-mine-session` — Mine a session (cross-host chat-history log) for memory signals and/or rule/skill proposal seeds via --mode…
+- `memory-promote` — Promote an intake signal (or provisional proposal) into a curated memory entry — opens a PR and runs the ad…
+- `memory-propose` — Append a provisional memory signal to the intake stream — the universal fallback for any producer (human or…
 - `module` — Module orchestrator — routes to create, explore
-- `module:explore` — Explore a module — load its structure, docs, and context into the current conversation
+- `module-explore` — Explore a module — load its structure, docs, and context into the current conversation
 - `optimize` — Optimize orchestrator — routes to skills, agents-dir, augmentignore, rtk-filters
 - `optimize-prompt` — Optimize a raw prompt for ChatGPT, Claude, Gemini, or another AI via the 4-D methodology — BASIC vs DETAIL…
-- `optimize:agents-dir` — Manage the agents/ directory — scaffold, folder-audit, fix. Single command with three modes (--scaffold / -…
-- `optimize:augmentignore` — Creates or updates .augmentignore based on the project's actual tech stack, large files, generated artifact…
-- `optimize:rtk` — Create or optimize project-local rtk filters based on the actual toolchain
-- `optimize:skills` — Audits skills — measures baseline, finds duplicates/merge candidates, runs linter. Suggest only, never auto…
+- `optimize-agents-dir` — Manage the agents/ directory — scaffold, folder-audit, fix. Single command with three modes (--scaffold / -…
+- `optimize-augmentignore` — Creates or updates .augmentignore based on the project's actual tech stack, large files, generated artifact…
+- `optimize-rtk` — Create or optimize project-local rtk filters based on the actual toolchain
+- `optimize-skills` — Audits skills — measures baseline, finds duplicates/merge candidates, runs linter. Suggest only, never auto…
 - `orchestrate` — Run a YAML pipeline defined under `.agent-config/orchestrations/` — chains personas / skills / commands / s…
 - `override` — Override orchestrator — routes to create, manage
-- `override:create` — Creates a project-level override for a shared skill, rule, or command.
-- `override:manage` — Reviews, updates, and refactors existing project-level overrides.
+- `override-create` — Creates a project-level override for a shared skill, rule, or command.
+- `override-manage` — Reviews, updates, and refactors existing project-level overrides.
 - `package-reset` — /package-reset
 - `package-test` — /package-test
 - `profile` — Session-profile orchestrator — activate / deactivate / show the active packs for this session (recommendati…
-- `profile:activate` — Activate a session profile — surface only the named profile/pack closure plus core artefacts, no persistence
-- `profile:deactivate` — Deactivate the session profile — clear the overlay (or drop named packs) so the full surface returns
-- `profile:show` — Show the active session profile — active packs and surfaced/hidden command+skill counts (observability surf…
+- `profile-activate` — Activate a session profile — surface only the named profile/pack closure plus core artefacts, no persistence
+- `profile-deactivate` — Deactivate the session profile — clear the overlay (or drop named packs) so the full surface returns
+- `profile-show` — Show the active session profile — active packs and surfaced/hidden command+skill counts (observability surf…
 - `review-routing` — Compute reviewer roles and matched historical bug patterns for the current diff, using project-local owners…
 - `rule-compliance-audit` — Audit rule trigger quality, simulate activation, detect overlaps, and find never-activating rules
 - `set-cost-profile` — Change the rule_loading_tier in .agent-settings.yml — shows each profile's meaning and applies the selection
 - `skill` — Single-skill orchestrator — routes to preview. Non-destructive "what will this skill do?" before you run it.
-- `skill:preview` — Non-destructive preview of a skill — its declared steps, execution type, allowed tools, and file/command ta…
+- `skill-preview` — Non-destructive preview of a skill — its declared steps, execution type, allowed tools, and file/command ta…
 - `skills` — Skill discovery orchestrator — routes to discover. Local, explained skill recommendations over the catalog…
-- `skills:discover` — Recommend skills for a role — ranked by four explained classes (most-useful-for-role, related-to-current-ta…
+- `skills-discover` — Recommend skills for a role — ranked by four explained classes (most-useful-for-role, related-to-current-ta…
 - `sync-agent-settings` — Sync `.agent-settings.yml` against the current template + profile — adds new sections/keys, preserves user…
 - `sync-gitignore` — Sync the `event4u/agent-config` block in the consumer project's .gitignore — adds missing entries, preserve…
-- `sync-gitignore:fix` — Scrub legacy pre-`/agents/` patterns from the consumer's .gitignore (inside or outside the managed block) a…
+- `sync-gitignore-fix` — Scrub legacy pre-`/agents/` patterns from the consumer's .gitignore (inside or outside the managed block) a…
 - `upstream-contribute` — Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package
 
 ### Domain flow — media
@@ -193,29 +191,29 @@ _The system/admin surface (NOT a flow): memory · analytics · governance · con
 _AI image + video pipeline._
 
 - `image` — Character-image fidelity orchestrator — analyse, create, and verify a character image against its canon. Ro…
-- `image:analyse` — Analyse a character image down to the smallest mole and diff it against a canon — per-feature spec, OCR tat…
-- `image:create` — Generate a character image to spec — assemble a max-fidelity, anchors-first prompt from a Canon Spec; gover…
-- `image:verify` — Verify a candidate render against its canon — run the analyser in loop mode, emit the gate verdict + remain…
+- `image-analyse` — Analyse a character image down to the smallest mole and diff it against a canon — per-feature spec, OCR tat…
+- `image-create` — Generate a character image to spec — assemble a max-fidelity, anchors-first prompt from a Canon Spec; gover…
+- `image-verify` — Verify a candidate render against its canon — run the analyser in loop mode, emit the gate verdict + remain…
 - `video` — Video-creation orchestrator — Hollywood-level AI video pipeline. Routes to from-script, from-song, scene, s…
-- `video:from-script` — Drive a script end-to-end through the AI video pipeline — scenes → blueprint → image → operator pick → moti…
-- `video:from-song` — Music-video from a song + reference images — accept or derive a timed scene script, optional character-lock…
-- `video:scene` — Render a single scene from a one-line idea — scene-expander → blueprint → image → operator pick → motion →…
-- `video:stitch` — Re-stitch existing clips in `<project>/scenes/*/` after operator edits — no re-render. ffmpeg concat driven…
-- `video:storyboard` — Image-only storyboard — script → scenes → blueprint → image render → contact-sheet PNG via ffmpeg montage.…
+- `video-from-script` — Drive a script end-to-end through the AI video pipeline — scenes → blueprint → image → operator pick → moti…
+- `video-from-song` — Music-video from a song + reference images — accept or derive a timed scene script, optional character-lock…
+- `video-scene` — Render a single scene from a one-line idea — scene-expander → blueprint → image → operator pick → motion →…
+- `video-stitch` — Re-stitch existing clips in `<project>/scenes/*/` after operator edits — no re-render. ffmpeg concat driven…
+- `video-storyboard` — Image-only storyboard — script → scenes → blueprint → image render → contact-sheet PNG via ffmpeg montage.…
 
 ### Domain flow — marketing
 
 _Ghostwriter + post-as voice pipeline._
 
 - `ghostwriter` — Ghostwriter cluster — fetch, write, list, show, and delete public-figure voice profiles (the third voice pr…
-- `ghostwriter:delete` — Hard-delete a ghostwriter profile at agents/reference/ghostwriter/<slug>.md after a two-step confirmation.…
-- `ghostwriter:fetch` — Build or refresh a public-figure voice profile under agents/reference/ghostwriter/ from a URL or bare name;…
-- `ghostwriter:list` — List captured ghostwriter profiles under agents/reference/ghostwriter/ as a numbered table with confidence,…
-- `ghostwriter:show` — Render a single ghostwriter profile in full — identity, style fingerprint, voice samples, taboos, source UR…
-- `ghostwriter:write` — Draft a markdown post in the voice of a captured public-figure ghostwriter profile; appends the mandatory n…
+- `ghostwriter-delete` — Hard-delete a ghostwriter profile at agents/reference/ghostwriter/<slug>.md after a two-step confirmation.…
+- `ghostwriter-fetch` — Build or refresh a public-figure voice profile under agents/reference/ghostwriter/ from a URL or bare name;…
+- `ghostwriter-list` — List captured ghostwriter profiles under agents/reference/ghostwriter/ as a numbered table with confidence,…
+- `ghostwriter-show` — Render a single ghostwriter profile in full — identity, style fingerprint, voice samples, taboos, source UR…
+- `ghostwriter-write` — Draft a markdown post in the voice of a captured public-figure ghostwriter profile; appends the mandatory n…
 - `post-as` — Consumer-facing write entry points — :me drafts in the maintainer's own voice from .agent-user.md (no discl…
-- `post-as:ghostwriter` — Thin alias for /ghostwriter:write — drafts a copyable markdown post in a captured public-figure voice with…
-- `post-as:me` — Draft a copyable markdown post in the maintainer's own voice (style source = .agent-user.md.voice_sample).…
+- `post-as-ghostwriter` — Thin alias for /ghostwriter:write — drafts a copyable markdown post in a captured public-figure voice with…
+- `post-as-me` — Draft a copyable markdown post in the maintainer's own voice (style source = .agent-user.md.voice_sample).…
 
 ### Domain flow — fun
 

package/docs/command-naming-audit.md

@@ -0,0 +1,60 @@
+# Command-naming audit (road-to-contract-integrity F5)
+
+External review flagged inconsistent command naming across the docs
+(`/pr:create` vs `/create-pr`, `/feature/plan` vs `/feature:plan`). Two
+names for one command is two sources of truth — a discoverability failure,
+not cosmetic polish. This audit fixes the user-facing inconsistencies and
+records the canonical rule + the alias registry that already exists.
+
+## The canonical form
+
+Per [ADR-003](decisions/ADR-003-flat-cluster-subs-and-colon-syntax.md) and
+[`command-clusters.md`](contracts/command-clusters.md) §"Colon-canonical
+invocation": **`/<cluster>:<sub>` is the canonical invocation form
+everywhere** — catalog, docs, cookbook. The frontmatter `name:` field is
+always the hyphen slug (`feature-plan`); the slash form (`/feature/plan`)
+is never an invocation syntax.
+
+## The alias registry already exists — do not add a parallel field
+
+The roadmap step proposed adding an `aliases:` field to the command
+schema. That would **duplicate** the mechanism that already ships:
+
+- **`replaces:`** (on the new/canonical command) — the prior name(s) or
+  alias(es) it absorbs. Colon forms are allowed here on purpose (historical
+  aliases like `commit:in-chunks`). Enforced by `lint_command_routing.py`.
+- **`superseded_by:`** (on the old shim) — points forward to the successor.
+
+Adding a second `aliases:` field would re-create the exact two-sources-of-
+truth problem this audit fixes. **Decision: `replaces:` is the canonical
+alias registry; no new field is introduced.** (This deviates from the
+literal Phase-1 roadmap text by intent — see the roadmap step note.)
+
+## Clashes resolved in this change
+
+Everything resolves **toward** the colon-canonical form. The PR command
+only ships as `dist/agent-src/commands/pr/create.md` (invoked `/pr:create`);
+there is no `commands/create-pr.md` projection, so `/create-pr` is a legacy
+*alias name* recorded in `replaces:`, not a directly-invocable command.
+
+| Surface | Was | Now | Basis |
+|---|---|---|---|
+| `README.md` Delivery flow + 2 prose refs | `/pr:create` (1) + `/create-pr` (2) | `/pr:create` (all) | Colon-canonical (ADR-003); `/pr:create` is the only projected command. |
+| `docs/featured-commands.md` | `/create-pr` (→ stale `commands/create-pr.md` link) | `/pr:create` (→ `commands/pr/create.md`) | The legacy link target no longer exists; point at the real projection. |
+| `docs/cookbook.md` (generated) | `/feature/explore`, `/feature/plan`, … (slash) | `/feature:explore`, `/feature:plan`, … (colon) | Fixed at the **generator** (`_invocation()` renders `cluster/sub` → `/cluster:sub`); all clustered refs now colon. The file is generated — the slash form was a generator bug, not a hand-edit. |
+
+## Known debt — deferred (own change)
+
+The PR command's frontmatter still carries `cluster: git-pr-create` and its
+body prose still self-documents the `/create-pr` family (and
+`/create-pr:description-only`). The user-facing invocation and all docs are
+now `/pr:create`; retiring the `/create-pr` alias name entirely — frontmatter
+`cluster`, the body prose, and the `:description-only` sub-family wording —
+is a command-body refactor out of scope for this audit and is tracked as
+command-surface debt.
+
+## See also
+
+- [`contracts/command-clusters.md`](contracts/command-clusters.md) — cluster + colon-syntax rules.
+- [`decisions/ADR-003-flat-cluster-subs-and-colon-syntax.md`](decisions/ADR-003-flat-cluster-subs-and-colon-syntax.md).
+- [`contracts/STABILITY.md`](contracts/STABILITY.md) — command stability policy.

package/docs/contracts/STABILITY.md

@@ -150,6 +150,38 @@ for the contract and the transitional allowlist.
   shipped `dist/agent-src/` (condensed) directory; the uncondensed
   source size is informational only.
 
+## Schema versioning and structural breaking changes
+
+The breaking-change gate is **two-layered** so it does not depend on
+author discipline alone:
+
+1. **Commit-annotation layer (`release.py`).** `infer_bump` reads the
+   Conventional-Commits annotation (`<type>!:` bang or a
+   `BREAKING CHANGE` line) and returns a major bump when present.
+2. **Structural layer (`check_structural_breaking.py`, run in
+   `task ci-fast`).** Independently of the commit message, the detector
+   inspects the diff against the trunk and FAILS when a structural break
+   is present *without* an annotation — forcing the annotation to exist.
+
+A change is **structurally breaking** when either:
+
+- a tracked artifact *source* file is **deleted or renamed** — a skill
+  `SKILL.md`, a rule, a command `command.md`, a pack manifest, or a
+  contract schema; or
+- a contract schema under `src/scripts/schemas/` is **modified without
+  bumping its `x-schemaVersion`**. The four contract schemas (`pack`,
+  `skill`, `rule`, `command`) carry an `x-schemaVersion`. Bump it when an
+  enum value is added or removed, a field type changes, or a validation
+  rule tightens — these are breaking-for-consumers yet invisible to a
+  name-status diff. Purely *additive* schema changes (a new optional
+  field) do not require a bump.
+
+Escape for an intentional break (e.g. a deprecation cycle completing):
+add `ci-override: structural-breaking-ok` to a commit body. The detector
+accepts ~20% false-negatives on purely *semantic* breaks (behaviour
+change with no artifact/schema delta); the structural + schema + commit
+cross-check reaches ~95% coverage (2026-06-16 council).
+
 ## See also
 
 - [`docs/architecture.md`](../architecture.md) — package architecture overview

package/docs/contracts/adr-layout.md

@@ -4,7 +4,7 @@ stability: stable
 
 # ADR Layout — Per-area Directories
 
-> Status: accepted · 2026-05-16 · Roadmap: `step-11-ruflo-parity` Phase 4
+> Status: accepted · 2026-05-16 · Roadmap: an internal parity roadmap (local-only) Phase 4
 
 ## Scope
 
@@ -42,7 +42,6 @@ Reserved areas (bootstrap pass — step-11 Phase 4 Step 3):
 | `schema` | Frontmatter schemas, v2 rigor, lint behaviour | [`schema-versioning.md`](schema-versioning.md) (when published) |
 | `router` | `router.json` shape, tier semantics, dispatch precedence | [`rule-router.md`](rule-router.md) |
 | `smoke` | Per-tier smoke contracts, baseline locks | [`smoke-contracts.md`](smoke-contracts.md) |
-| `memory` | Memory MCP, propose / promote / poison flow | [`agent-memory-contract.md`](agent-memory-contract.md) |
 
 ## Frontmatter
 
@@ -105,4 +104,4 @@ The skill's template, numbering logic, and validation hooks are identical for bo
 - [`docs/decisions/INDEX.md`](../decisions/INDEX.md) — flat surface index.
 - [`scripts/audit_adr_coverage.py`](../../src/scripts/audit_adr_coverage.py) — coverage gate.
 - [`scripts/adr/regenerate_index.py`](../../src/scripts/adr/regenerate_index.py) — index regenerator (works on both surfaces; pass `--dir`).
-- `step-11-ruflo-parity` Phase 4 — origin.
+- an internal parity roadmap (local-only) Phase 4 — origin.

package/docs/contracts/adr-level-6-productization.md

@@ -63,7 +63,7 @@ stability: stable
 - Rule-Interaction matrix marked rule-only by design;
   [`rule-interactions.md`](rule-interactions.md) § "Out of scope —
   orchestration surfaces" points at `decision-engine-gates`,
-  `decision-trace-v1`, `agent-memory-contract`, `memory-visibility-v1`,
+  `decision-trace-v1`, `memory-visibility-v1`,
   and the `ai-council` skill for Council × Memory × Work-Engine
   interactions (P5.2).
 - `type: orchestrator` frontmatter tag exempts cluster routers from

package/docs/contracts/agents-md-tech-stack.md

@@ -30,7 +30,7 @@ package). The skill ships the four-layer security defense:
 Calibrated token claim: 3-5× comprehension on text-heavy formats
 (PDF, DOCX), 10-50× on image-heavy formats (scanned PDF, PPTX with
 diagrams). Measure locally with
-`python3 scripts/measure_markitdown_lift.py` against
+`./scripts-run src/scripts/measure_markitdown_lift` against
 `tests/fixtures/markitdown-corpus/`.
 
 ## Cognition-only floor for Wings 2–4

package/docs/contracts/ai-council-config.md

@@ -3,16 +3,16 @@ stability: beta
 keep-beta-until: 2026-08-12
 ---
 
-# AI-Council Config (`agents/settings/.ai-council.yml`)
+# AI-Council Config (`.ai-council.yml`)
 
 **Purpose.** Lock the schema, validation, and precedence rules for the
 centralized council config file. Every phase of the AI-Council
 consolidation work reads from this file; the contract here is the
 boundary that prevents drift across the loader, the CLI, the
-orchestrator, and the `agents/settings/.ai-council.yml` file itself.
+orchestrator, and the `.ai-council.yml` file itself.
 
 **Audience.** Authors of `scripts/ai_council/config.py`, `council_cli.py`,
-`scripts/ai_council/orchestrator.py`, and the `agents/settings/.ai-council.yml`
+`scripts/ai_council/orchestrator.py`, and the `.ai-council.yml`
 starter. Also reviewers checking that new providers / advisors / debate
 features keep the schema intact.
 
@@ -21,10 +21,45 @@ a revision entry in the consuming roadmap.
 
 ## File location
 
-The single source of truth is **`agents/settings/.ai-council.yml`** at the
-project root. The legacy `ai_council.*` block under `.agent-settings.yml`
-is removed by Phase 0 Step 5 and replaced by a one-line breadcrumb
-pointing at this contract.
+The council is configured **once per user**, not per project. The config
+lives in the user-global namespace:
+
+```
+~/.event4u/agent-config/settings/.ai-council.yml
+```
+
+(with the legacy `~/.config/agent-config/settings/.ai-council.yml` read as a
+fallback during the v2.4 namespace transition). This is where a single
+developer enables members, pins models, and sets caps once — and the
+council then works in **every** project they open, with no per-project
+file to check in or accidentally commit. See
+[ADR-093](../decisions/ADR-093-ai-council-config-user-global.md).
+
+`scripts/ai_council/config.py:resolve_config_path` resolves the active
+file with this precedence (first match wins):
+
+1. **`$AI_COUNCIL_CONFIG`** — an explicit absolute path. Honoured even
+   when the target is absent (so a typo surfaces as "create it here"
+   rather than silently falling back). Primarily for tests / power users.
+2. **Project-local** `<project_root>/agents/settings/.ai-council.yml` —
+   only when a consumer project deliberately checks in its own council
+   config. This **overrides** the user-global file for that project.
+3. **User-global** `~/.event4u/agent-config/settings/.ai-council.yml` — the
+   canonical default described above.
+
+When none exists, the loader reports the user-global path as the place to
+create it. `agents/templates/.ai-council.yml.example` ships the documented
+shape to copy from. The legacy `ai_council.*` block under
+`.agent-settings.yml` remains removed (Phase 0 Step 5); a one-line
+breadcrumb there points at this contract.
+
+> **Why user-global, not project-tracked.** A council config checked into
+> the project tree (the pre-ADR-093 layout) (a) re-applied per-project
+> instead of per-developer, (b) risked being committed to a public repo,
+> and (c) was silently *not found* on cloud / headless / fresh-checkout
+> surfaces with no project copy — the council then refused with
+> "ai_council.enabled is false" even though the user had set it up. The
+> user-global location fixes all three.
 
 ## Top-level schema
 
@@ -227,7 +262,7 @@ is invoked.
   tier. The two-tier split reconciles "Council always active when
   enabled" with "skip trivial agent-side requests": user-typed
   `/council` calls proceed by default, agent-initiated dispatches keep
-  `educate` behaviour. Override via `.agent-settings.yml`.
+  `educate` behaviour. Override via the resolved `.ai-council.yml`.
 - `lens_overrides.necessity_classifier_mode.<lens>` — per-lens override.
   Wins over the global `mode` for the matching invocation tier (agent
   vs user_explicit follow the same lens map). Typical use: leave the
@@ -398,26 +433,26 @@ Worked example — opt the Anthropic and OpenAI members in, leave the
 others off, and switch the `low_impact` class to `council`:
 
 ```yaml
-ai_council:
-  members:
-    anthropic:
-      enabled: true
-      model: claude-sonnet-4-5
-      api_key_ref: file:anthropic.key
-      participate_low_impact: true   # eligible for fast-path
-    openai:
-      enabled: true
-      model: gpt-4o
-      api_key_ref: file:openai.key
-      participate_low_impact: true   # eligible for fast-path
-    gemini:
-      enabled: false                  # disabled — opt-in ignored even if set
-
-  fast_path:
-    max_members: 2          # 1 or 2 only
-    max_rounds: 1           # LOCKED
-    max_tokens: 2500
-    max_cost_usd: 0.05
+# In the resolved .ai-council.yml — keys are top-level (no `ai_council:` wrapper).
+members:
+  anthropic:
+    enabled: true
+    model: claude-sonnet-4-5
+    api_key_ref: file:anthropic.key
+    participate_low_impact: true   # eligible for fast-path
+  openai:
+    enabled: true
+    model: gpt-4o
+    api_key_ref: file:openai.key
+    participate_low_impact: true   # eligible for fast-path
+  gemini:
+    enabled: false                  # disabled — opt-in ignored even if set
+
+fast_path:
+  max_members: 2          # 1 or 2 only
+  max_rounds: 1           # LOCKED
+  max_tokens: 2500
+  max_cost_usd: 0.05
 
 decision_resolution:
   classes:
@@ -606,7 +641,7 @@ as comments and the loader enforces them.
   whose projected spend would breach a cap and asks the user to continue.
   Each `0` value disables that single cap; other caps still apply.
   Prices come from [`agents/runtime/.agent-prices.md`](../../agents/runtime/.agent-prices.md)
-  (gitignored, refreshed weekly by `python3 scripts/update_prices.py`;
+  (gitignored, refreshed weekly by `./scripts-run src/scripts/update_prices`;
   bootstrapped from `scripts/ai_council/_default_prices.py` on first run).
 
 ## Validation rules