@event4u/agent-config 9.8.0 → 9.9.0

package/docs/command-flows.md

@@ -1,272 +0,0 @@
-<!-- GENERATED by scripts/generate_command_flows.py — do not edit by hand. -->
-<!-- Source: src/flows/surface-map.yaml + src/flows/<flow>.yaml. Re-run: task generate-command-flows. -->
-
-# Command flows — the primary view
-
-> road-to-6.1.0 Step 9. Commands are **flow members**, not a flat list. The layered model is `Profile → Pack → Flow → Command → Skill → Rule`; this view answers *"what am I trying to do?"* before *"which command do I type?"*.
-
-> 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`.
-
-**190 commands** across **10 surfaces** (4 user-work flows + 6 platform/domain surfaces).
-
-## User-work flows
-
-The developer story: **discovery → implementation → review → delivery**.
-
-### Discovery
-
-_Explore, plan, estimate, refine, and investigate before building. The "what should we build and how" front of the developer journey._
-
-**Entry points:** `feature/plan` · `bug/investigate` · `research`
-
-**Default path:** `feature/explore` → `feature/plan` → `estimate-ticket` → `refine-ticket`
-
-- `analyze` — Analysis orchestrator — confidence-weighted suggester that routes to postmortem, premortem, decision-review…
-- `analyze-decision` — Audit a past architectural decision — restate what was chosen and why, compare original assumptions against…
-- `analyze-incident` — Full incident flow — incident-commander coordination, then RCA via root-cause-frameworks, then a blame-free…
-- `analyze-near-miss` — Blame-free near-miss analysis — same post-mortem flow as analyze:postmortem but framed around a close call…
-- `analyze-postmortem` — Blame-free post-mortem after a resolved incident — consume the incident-commander skeleton, derive root cau…
-- `analyze-premortem` — Forward-looking imagined-failure analysis before committing to a heavy or irreversible plan — enumerate fai…
-- `analyze-reference-repo` — Analyze an external reference repository (competitor, inspiration, peer) and produce a structured compariso…
-- `bug` — Bug orchestrator — routes to investigate (root cause) and fix (plan + implement)
-- `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
-- `optimize-project` — Project-wide optimization sweep — inventory roadmaps, ADRs, agent folders (incl. modules), challenge stale…
-- `project` — Project orchestrator — routes to analyze (full audit) and health (read-only status check)
-- `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…
-
-### Implementation
-
-_Build it. The core "make the change" front — drive a prompt, ticket, or feature end-to-end through plan → implement → verify._
-
-**Entry points:** `work` · `implement-ticket` · `feature/dev` · `bug/fix`
-
-**Default path:** `work` → `review/changes` → `fix/quality` → `commit`
-
-- `bug-fix` — Plan and implement a bug fix — based on investigation, with quality checks and test verification
-- `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
-- `mission-upgrade` — Gated Laravel major-version upgrade mission — provisional branch, breaking-change catalog, size-tier surfac…
-- `module-create` — Create a new module from .module-template with interactive setup
-- `tdd` — TDD orchestrator — routes to red (failing test), green (minimum code), refactor (clean while green)
-- `tdd-green` — TDD green phase — write the minimum production code to make the failing test pass; no test edits
-- `tdd-red` — TDD red phase — enumerate cases, write ONE failing test, watch it fail at an assertion (not an import error)
-- `tdd-refactor` — TDD refactor phase — clean up (rename, deduplicate) while keeping the test green
-- `tests` — Tests orchestrator — routes to create, execute, e2e-plan, e2e-heal
-- `tests-create` — Write meaningful tests for the current branch — stack-adaptive (pest / phpunit / vitest / jest / pytest / …)
-- `tests-e2e-heal` — Find, debug, and fix failing Playwright E2E tests
-- `tests-e2e-plan` — Explore the application and create a structured E2E test plan in Markdown
-- `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…
-- `worktree` — Worktree orchestrator — routes to create, status, verify, cleanup
-- `worktree-cleanup` — Safe worktree removal gate — refuses while the branch holds commits on no other ref; never force-deletes
-- `worktree-create` — Create a governed worktree and write its scope-lock note — propose-once branch naming, host-native primitiv…
-- `worktree-status` — List active worktrees — ownership (scope lock), dirty state, ahead/behind, merge-readiness incl. verificati…
-- `worktree-verify` — Run the scoped verification for a worktree's declared change — narrow probes matched to the diff, never the…
-
-### Review
-
-_Check it. Self-review, judge, fix/quality, and threat-model a change before it ships._
-
-**Entry points:** `review/changes` · `judge`
-
-**Default path:** `review/changes` → `judge` → `fix/quality` → `threat-model`
-
-- `fix-ci` — Fetch CI errors from GitHub Actions and fix them
-- `fix-quality` — Run quality pipeline (PHP and/or JS/TS) and fix all errors — auto-detects language from changed files
-- `fix-route` — Classify a vaguely-described problem and dispatch to the right fix sub-command (or name the specialist skil…
-- `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
-- `review` — Review orchestrator — routes to changes (five-judge self-review of the local diff) and routing (compute rev…
-- `review-changes` — Self-review local changes before creating a PR — dispatches to five specialized judges (bug, security, test…
-- `security-audit-config` — Audit an assembled agent config (CLAUDE.md, .cursor/rules, settings, MCP, hooks, skills) for prompt-injecti…
-- `threat-model` — Run a pre-implementation threat model on a proposed change — enumerates abuse cases, trust boundaries, and…
-
-### Delivery
-
-_Ship it. Commit in logical chunks, open the PR, answer review comments, and prepare the branch for review._
-
-**Entry points:** `commit` · `pr/create` · `prepare-for-review`
-
-**Default path:** `commit` → `pr/create` → `fix/pr-comments`
-
-- `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, comments, quality
-- `fix-comments` — Review the code comments touched by the current branch and simplify, shorten, or remove each one
-- `fix-portability` — Find and fix project-specific references in shared .augment/ package files
-- `fix-pr-comments` — Fix, commit+push, reply to, then resolve all open review comments (bots + human reviewers) 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…
-- `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…
-
-## Platform & domain surfaces
-
-### Product-surface features
-
-_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-…
-- `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…
-- `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…
-- `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-materialize` — Materialise a roadmap into a self-contained, importable ticket bundle under agents/tickets/
-- `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…
-- `team` — Team orchestrator — governed cross-model access layer (a second strong model reviews the real diff; read-on…
-- `team-adversarial` — Thin wrapper — adversarial cross-model review on a named focus via the official plugin (/codex:adversarial-…
-- `team-delegate` — Thin wrapper — hand a task to the second model as a native worker via the official plugin (/codex:rescue).…
-- `team-review` — Thin wrapper — cross-model review of the current diff via the official plugin (/codex:review). Gated on ai_…
-- `team-status` — Thin wrapper — plugin job status via /codex:status plus a quota block (shared openai counter vs team + coun…
-
-### 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.
-- `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 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
-- `contribution-precheck` — Contributor self-service precheck — run the PR-relevant lint subset (skill linter, originality gate, frontm…
-- `cost` — Cost orchestrator — routes to report (session token cost + budget ladder) and profile (change the rule_load…
-- `cost-profile` — Change the rule_loading_tier in .agent-settings.yml — shows each profile's meaning and applies the selection
-- `cost-report` — Capture token cost from the active Claude Code session, append to the local sessions store, and surface the…
-- `explain-run` — Read-only 'why did that happen' run report — resolved rule set, rules fired, artefact engagement, subagent…
-- `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…
-- `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, 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
-- `optimize` — Optimize orchestrator — routes to skills, agents-dir, augmentignore, rtk-filters, project (project-wide swe…
-- `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-prompt` — Optimize a raw prompt for ChatGPT, Claude, Gemini, or another AI via the 4-D methodology — BASIC vs DETAIL…
-- `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.
-- `package` — Package orchestrator — routes to test (verify the package install) and reset (restore installed state)
-- `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…
-- `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
-- `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…
-- `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…
-- `sync` — Sync orchestrator — routes to agent-settings (template sync) and gitignore (managed block sync, plus legacy…
-- `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…
-- `team-knowledge` — Team-knowledge orchestrator — routes to consolidate and bootstrap
-- `team-knowledge-bootstrap` — One-shot deterministic seed for a fresh project's knowledge layer — stages template pages from real config/…
-- `team-knowledge-consolidate` — Review pending typed knowledge-observation events and file them into agents/knowledge/ pages as a human-rev…
-- `upstream-contribute` — Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package
-
-### Domain flow — media
-
-_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…
-- `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.…
-
-### Domain flow — marketing
-
-_Ghostwriter + post-as voice pipeline._
-
-- `brand` — Brand-as-UX orchestrator — strategy, identity, tokens, review, voice. Routes to the brand-grounding skills…
-- `brand-identity` — Define the brand identity — logo direction, colour story, type story, imagery direction — and the token con…
-- `brand-review` — Audit emitted UI, copy, and assets against the active brand tokens and voice profile — flag any value not t…
-- `brand-strategy` — Define brand positioning, archetype, voice, tone, and messaging over the brand-grounding corpus — the strat…
-- `brand-tokens` — Derive a DTCG .tokens.json source of truth from brand decisions, then emit CSS vars + Tailwind via the no-N…
-- `brand-voice` — Define the brand voice-and-tone profile — register, do/don't lexicon, and tone shifts by context — the prof…
-- `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…
-- `humanize` — Remove AI-writing tells from pasted text or a file — runs the humanizer skill's draft→audit→final loop and…
-- `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).…
-
-### Domain flow — fun
-
-_Recreational packs._
-
-- `prediction-pool` — Fill a prediction pool (kicktipp, football/basketball WM): optimize expected points under the rules, enter…
-
-### Session surface
-
-_Handoff / status / mode — conversation lifecycle._
-
-- `agent-handoff` — Generate a context summary for continuing work in a fresh chat. Replaces the session system.
-- `agent-status` — Show current conversation stats — message count, token costs, task progress, next freshness check.
-- `mode` — Set the active role mode — prints the contract, lists default skills, and refuses work outside the contract…

package/docs/command-naming-audit.md

@@ -1,60 +0,0 @@
-# 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/comparison.yaml

@@ -1,87 +0,0 @@
-# B7 — comparison-honesty rows for the proof page.
-#
-# The point is the `checkable` column, not a takedown. For each dimension we
-# cite OUR evidence as a resolvable pointer (file / file#substring / ledger id),
-# and state what is PUBLICLY OBSERVABLE about the wider category — never a named
-# competitor (source-confidentiality), never a counter-claim to their headline
-# number. A category headline figure (e.g. an "84.8%" score) is cited ONLY as
-# uncheckable: no reproducible methodology is published, so it cannot be verified
-# either way — that is the whole point.
-#
-# check_comparison.ts enforces: every `our_evidence` resolves (reuses the
-# check_claims pointer resolver); every `checkable: true` row's `our_evidence`
-# resolves. build_proof renders these rows. check_no_external_sources guarantees
-# no named source leaks in.
-#
-# `failure_mode` (optional) — what this row's claim prevents, in adopter-facing
-# voice. A populated row ALSO renders in the "What each one prevents" view on the
-# proof page; an empty field is the honest signal that the row is comparative
-# only. Membership in that view is therefore a data property, never a curated
-# short-list that can drift from this table.
-#
-# THE PIN SHAPE IS REFUSED HERE, DELIBERATELY. A number in these rows is bound by
-# a resolving pointer — never by a test asserting that a literal string appears in
-# a doc. A comparable suite pinned a marketing figure with an
-# `assertIn("<number> tokens", …)` test; its own published formula yields a value
-# ~4x larger, and the pin turned the wrong number into a protected invariant that
-# CI actively defended. A pointer can go stale and be re-derived; a pin makes
-# staleness the passing condition.
-
-rows:
-  - claim: "No resident runtime — no background daemon, no state database or service, no auto-write memory; deterministic, rebuildable file indexes only."
-    our_evidence: "docs/contracts/no-runtime-boundary.md#file-first"
-    their_evidence: "Swarm-runtime tools in this category ship a background process and/or a resident state store by design; that is an architectural fact of the runtime approach, not a defect."
-    checkable: true
-    failure_mode: >-
-      A background process keeps running after you stop using it, holds state you did not write, and has to be kept alive and upgraded.
-
-  - claim: "Capability/benchmark results are published — including the runs where the package changed nothing."
-    our_evidence: "docs/benchmark.md"
-    their_evidence: "A category headline figure (e.g. an '84.8%' score) appears across marketing surfaces with no reproducible methodology published — so it cannot be verified either way."
-    checkable: true
-    failure_mode: >-
-      You adopt on a headline number nobody can re-run, and never learn which of its measurements changed nothing.
-
-  - claim: "Every public claim binds to machine-checked evidence."
-    our_evidence: "docs/CLAIMS.md"
-    their_evidence: "Marketing claims in this category are not bound to a machine-checked ledger a reader can reproduce."
-    checkable: true
-    failure_mode: >-
-      A shipped number drifts from the artefact it came from and stays published, because nothing re-checks the claim against its source.
-
-  - claim: "Skills publish their own known limits, each with a witness test."
-    our_evidence: "tests/scripts/witness/check_refs_relative_gap.test.ts"
-    their_evidence: "Published known-limitation surfaces backed by reproducing tests are not a standard artifact in this category."
-    checkable: true
-    failure_mode: >-
-      A limitation is discovered by you, in your repo, at the moment it costs you something — instead of being stated up front and held by a test.
-
-  - claim: "A 30-second single-file wedge exists — one read-only subagent, one command, verdict with file:line — and its promise is a scoped, published eval, not a feature list."
-    our_evidence: "internal/bench/orchestration/pv-a3-results.md#token_delta_provenance: measured"
-    their_evidence: "Category entry points typically install the full platform (profiles, packs, runtime) before the first felt win; single-artifact entries with a published eval behind the promise are not a standard artifact."
-    checkable: true
-    failure_mode: >-
-      Evaluating the tool means installing the whole platform first, so the first thing you learn is the setup cost rather than whether it works.
-
-  - claim: "The persona-identity question was tested and published as an honest null (identity swap ~zero effect, provider choice ~15x larger) instead of being shipped as theater."
-    our_evidence: "internal/bench/reports/persona-placebo.json#honest-null"
-    their_evidence: "Named-persona prompts are shipped as a feature across the category without a published A/B separating identity from method."
-    checkable: true
-    failure_mode: >-
-      You pay tokens for prompt theater that was never measured against the method text it wraps.
-
-  - claim: "Every upstream-tool install prescription the package ships is version-pinned, intake-recorded, and enforced offline in CI — an unpinned version, a branch/archive install source, or a pipe-remote-to-shell instruction fails the build."
-    our_evidence: "src/scripts/validate_reach_prescriptions.ts"
-    their_evidence: "Capability layers in this category commonly install themselves and their upstream dependencies from a moving target (a branch archive or an unpinned package) via a piped remote installer; whether any given one pins is observable per repo, but a CI gate that fails the build on an unpinned prescription is not a standard artifact."
-    checkable: true
-    failure_mode: >-
-      An install instruction silently follows a moving target — an unpinned package or a piped remote script — so what lands in your repo is whatever the source held that day.
-
-  - claim: "Platform reads that the host's own web tools cannot perform at all (a refused domain, an HTTP 402) are shipped as credential-free prescriptions whose reliability was measured per channel against a native control, with the thresholds frozen before the run and the narrowing caveat published alongside the pass."
-    our_evidence: "docs/benchmark.md#ship-gated-reach"
-    their_evidence: "Reaching gated platforms is commonly solved in this category by asking for an API key or a session cookie, and the capability is asserted from a feature list rather than a per-channel reliability measurement with a native-arm control; publishing the case where the native tools already suffice, next to the pass, is not a standard artifact."
-    checkable: true
-    failure_mode: >-
-      You hand over a credential — or your account — for a read the tools could
-      already do, and you cannot tell which channels actually work because the
-      capability was claimed rather than measured.

package/docs/contracts/CHANGELOG-conventions.md

@@ -1,149 +0,0 @@
----
-stability: stable
----
-
-# Changelog Conventions
-
-> **Status:** Active · governs the shape of [`CHANGELOG.md`](../../CHANGELOG.md)
-> and the per-era archive files under [`docs/archive/`](../archive/).
-> Cited from the CHANGELOG header and enforced by
-> `tests/test_changelog_eras.py`.
-
-## Purpose
-
-Locks the entry shape, the breaking-change rules, and the era-split
-discipline for `event4u/agent-config`. Auto-generated entries (e.g.
-release-please) and hand-written entries follow the same shape so the
-file remains uniform across automated and manual releases.
-
-## Entry shape
-
-Each released version is a level-2 heading with a compare link and a
-release date:
-
-```md
-## [X.Y.Z](https://github.com/event4u-app/agent-config/compare/PREV...X.Y.Z) (YYYY-MM-DD)
-```
-
-Inside the version block, group changes under level-3 headings using
-the Conventional Commits family the entry came from:
-
-- `### Features` — `feat:` commits.
-- `### Bug Fixes` — `fix:` commits.
-- `### Chores` — `chore:`, `build:`, `ci:` commits a user might want
-  to see (silent infra-only chores stay out).
-- `### Docs` — `docs:` commits that change user-facing behaviour or
-  surface (otherwise drop them).
-- `### BREAKING CHANGES` — see [What counts as breaking](#what-counts-as-breaking).
-- `### Reverts` — `revert:` commits, with the SHA of the original commit.
-
-Each bullet is one line, scope-prefixed, with the short SHA linked:
-
-```md
-* **scope:** imperative-mood summary ([abc1234](https://github.com/event4u-app/agent-config/commit/abc1234...))
-```
-
-Optional trailers — a free-form paragraph for the release narrative
-(only for non-trivial releases), followed by a single-line test count
-delta:
-
-```md
-Tests: NNNN (+M since X.Y.(Z-1))
-```
-
-The test-count line is enforced for any release that ships changes to
-`scripts/`, `internal/workers/`, or `dist/agent-src/` content; it can be omitted for
-pure-docs releases.
-
-Minor / major sections (`## [X.Y.0]`) additionally carry a `Rollback:` line for
-every introduced or substantially reworked subsystem — required by
-[`release-sizing.md`](release-sizing.md) and enforced by
-`src/scripts/lint_changelog_rollback.ts` for versions above the current
-`package.json` version (historical sections never retro-fail).
-
-## What counts as breaking
-
-A change is **breaking** (and MUST appear under `### BREAKING CHANGES`
-**and** bump the major version) when it changes:
-
-1. **Public CLI surface** — `agent-config <cmd>` flags / subcommands at
-   Tier-0 or Tier-1 (Tier-2 is internal per
-   [`command-surface-tiers.md`](command-surface-tiers.md) and may shift
-   without a major bump).
-2. **Install scopes** — adding / removing a scope (`global`, `project`,
-   `mcp_scope: lite|full`) or changing its default discovery path per
-   [`ADR-007`](../decisions/ADR-007-agent-discovery-scopes.md).
-3. **MCP Worker contracts** — anything that breaks
-   [`mcp-cloud-scope.md`](mcp-cloud-scope.md) or
-   [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md) (tool shape, prompt
-   ids, resource URIs).
-4. **Generated tree shape** — removing or renaming top-level
-   directories under `dist/agent-src/`, `.augment/`, `.claude/`,
-   `.cursor/`, `.clinerules/`, or `.windsurfrules`.
-5. **Settings keys** — removing / renaming a key in
-   `.agent-settings.yml` that consumer projects may rely on. Adding a
-   new key with a default is **not** breaking.
-6. **AGENTS.md / kernel rules** — removing or renaming an Iron-Law
-   rule, or changing the kernel-membership contract per
-   [`kernel-membership.md`](kernel-membership.md).
-
-Internal refactors, doc rewrites, test changes, and any change to
-files under `.agent-src.uncondensed/` that round-trip through
-`task sync` unchanged are **not** breaking.
-
-## Era splits
-
-`CHANGELOG.md` keeps only the **current era** inline; prior eras live
-under [`docs/archive/`](../archive/) and are read-only.
-
-Drift gate — `tests/test_changelog_eras.py` fails when the current
-era's body (lines between `# Era: X.Y.x — current` and the next era
-header) exceeds **250 lines**. When that happens:
-
-1. Pick the next major or significant minor boundary at the bottom of
-   the current era (typically the last `X.Y.0` release).
-2. Move every entry at or below that boundary into
-   `docs/archive/CHANGELOG-pre-<boundary>.md`, prepending the standard
-   archive header.
-3. Replace the moved entries in `CHANGELOG.md` with a single collapsed
-   `# Era: pre-<boundary> — archived` section that links to the
-   archive file.
-4. Rename the active era header to `# Era: <new-current>.x — current`.
-5. Update the `## [Unreleased]` placeholder unchanged.
-
-Each era split lands as its own `chore(changelog): split era X.Y.x →
-pre-X.Y.x` commit — never bundled with a feature release.
-
-### Gate-vs-script contract
-
-- **Canonical splitter** — `src/scripts/release.ts`, run via `task release`
-  or the `release`-labeled-PR CI path
-  (`.github/workflows/release.yml`, see
-  [`ADR-113`](../decisions/ADR-113-ci-native-release-label-trigger.md)).
-  When a release crosses a minor/major boundary and the current era body
-  is at or over the 250-line cap, the release pipeline writes the
-  `chore(changelog): split era …` commit **first**, then the
-  `release: X.Y.Z` commit. The maintainer does not run the split by
-  hand for the release path.
-- **Backstop** — `tests/lib/changelog_eras.test.ts` (`test_current_era_body_under_cap`)
-  catches entries written **outside** the release script (hand-edited
-  Unreleased section, agent-authored hotfix entries, doc patches). The
-  failure message names `task release` as the auto-split path.
-- **Shared cap constant** — `src/scripts/_lib/changelog_eras.ts` owns
-  `CURRENT_ERA_BODY_CAP` and the era-header regex. Both the test and
-  the release script import from there; no parallel copies.
-- **Patch-release overflow** — a `patch` bump cannot cross an era
-  boundary by definition, so the release script refuses to auto-split
-  on a patch and surfaces the manual-intervention message instead.
-
-## Cross-references
-
-- [`../../CHANGELOG.md`](../../CHANGELOG.md) — active era + Unreleased.
-- [`../archive/CHANGELOG-pre-2.2.0.md`](../archive/CHANGELOG-pre-2.2.0.md) —
-  frozen pre-2.2.0 entries.
-- [`command-surface-tiers.md`](command-surface-tiers.md) — Tier-0/1/2
-  split that governs CLI-surface breaking-change classification.
-- [`mcp-cloud-scope.md`](mcp-cloud-scope.md) ·
-  [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md) — MCP contract bounds.
-- [`../decisions/ADR-007-agent-discovery-scopes.md`](../decisions/ADR-007-agent-discovery-scopes.md) —
-  install scope discovery.