@event4u/agent-config 2.11.0 → 2.13.0

package/docs/catalog.md

@@ -1,13 +1,13 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **442 public artefacts** shipped by
+Consumer-facing catalog of all **452 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
 > **Regenerate:** `python3 scripts/generate_index.py`
 > Auto-generated — do not edit manually.
 
-## Skills (206)
+## Skills (210)
 
 | kind | name | extra | description |
 |---|---|---|---|
@@ -32,6 +32,7 @@ are excluded.
 | skill | [`blast-radius-analyzer`](../.agent-src/skills/blast-radius-analyzer/SKILL.md) |  | Use BEFORE editing shared code — enumerates every call site, event consumer, queue worker, API client, migration, and test that a planned change will touch, with a file:line citation per dependency. |
 | skill | [`bug-analyzer`](../.agent-src/skills/bug-analyzer/SKILL.md) |  | Use when the user shares a Sentry error, Jira bug ticket, or error description and wants root cause analysis. Also for proactive bug hunting and code audits for hidden bugs. |
 | skill | [`build-buy-partner`](../.agent-src/skills/build-buy-partner/SKILL.md) |  | Use when deciding insource vs outsource vs acquire — integration-cost analysis, dependency-risk, optionality preservation. Triggers on 'should we build', 'buy vs partner'. |
+| skill | [`canvas-design`](../.agent-src/skills/canvas-design/SKILL.md) |  | Use when creating static visual art — posters, marketing visuals, brand assets, PDF/PNG design pieces — even if the user just says 'design a poster' or 'mach uns ein Visual'. |
 | skill | [`check-refs`](../.agent-src/skills/check-refs/SKILL.md) |  | Use when verifying cross-references between skills, rules, commands, guidelines, and context documents are not broken after edits, renames, or deletions. |
 | skill | [`churn-prevention`](../.agent-src/skills/churn-prevention/SKILL.md) |  | Use when designing churn defence — health-score signals, churn-cause split (involuntary / value / relationship / fit), early-warning loop. Triggers on 'why are accounts leaving'. |
 | skill | [`code-refactoring`](../.agent-src/skills/code-refactoring/SKILL.md) |  | Use when the user says "refactor this", "rename class", or "move method". Safely refactors PHP code — finds all callers, updates downstream dependencies, and verifies with quality tools. |
@@ -48,7 +49,7 @@ are excluded.
 | skill | [`contracts-cognition`](../.agent-src/skills/contracts-cognition/SKILL.md) |  | Use when reading a contract for risk and constraint — clause shape, redline priority, what the contract actually binds. Triggers on 'review this contract', 'what does this MSA constrain'. |
 | skill | [`conventional-commits-writing`](../.agent-src/skills/conventional-commits-writing/SKILL.md) |  | Use when writing commit messages or squash-merge titles — `feat:`, `fix:`, `chore:`, scopes, breaking changes — even when the user just says 'commit this' without naming Conventional Commits. |
 | skill | [`copilot-agents-optimization`](../.agent-src/skills/copilot-agents-optimization/SKILL.md) |  | Use when optimizing AGENTS.md or copilot-instructions.md — deduplicates against .augment/ content, enforces line budgets, and focuses each file on its audience. |
-| skill | [`copilot-config`](../.agent-src/skills/copilot-config/SKILL.md) |  | Use when configuring GitHub Copilot — copilot-instructions.md, PR review patterns, output optimization — even when the user just says 'tune Copilot' or 'why is Copilot commenting on X'. |
+| skill | [`copilot-config`](../.agent-src/skills/copilot-config/SKILL.md) |  | Tune the GitHub Copilot AI — `copilot-instructions.md`, PR-review patterns, suggestion behavior, output verbosity. NOT for dev-environment setup (use `devcontainer`). |
 | skill | [`customer-research`](../.agent-src/skills/customer-research/SKILL.md) |  | Use when shaping a discovery slice — JTBD-framed interview guide, switch-event focus, verbatim quotes not summaries. Triggers on 'talk to users', 'why did they cancel', 'before we build X'. |
 | skill | [`dashboard-design`](../.agent-src/skills/dashboard-design/SKILL.md) |  | Use when designing monitoring dashboards — visualization selection, layout principles, observability strategies (RED/USE/Golden Signals), and data storytelling. |
 | skill | [`data-flow-mapper`](../.agent-src/skills/data-flow-mapper/SKILL.md) |  | Use BEFORE editing code that touches user data — traces the value from entry → validation → transformation → storage → egress, every hop cited with file:line. |
@@ -62,9 +63,10 @@ are excluded.
 | skill | [`dependency-upgrade`](../.agent-src/skills/dependency-upgrade/SKILL.md) |  | Use when upgrading dependencies — "update Laravel", "bump PHP version", or "upgrade packages". Covers changelog review, breaking change detection, and verification. |
 | skill | [`description-assist`](../.agent-src/skills/description-assist/SKILL.md) |  | Use when polishing a skill/rule/command/guideline frontmatter description — pushier phrasing, trigger coverage, undertrigger audit — even if the user just says 'make this pushier'. |
 | skill | [`design-review`](../.agent-src/skills/design-review/SKILL.md) |  | Use when the user says "review the design", "check the UI", or wants a comprehensive UI/UX review. Uses a 7-phase methodology covering interaction, responsiveness, accessibility, and more. |
-| skill | [`devcontainer`](../.agent-src/skills/devcontainer/SKILL.md) |  | Use when configuring DevContainers or GitHub Codespaces — devcontainer.json, custom images, secrets, VS Code features — even when the user just says 'why does my Codespace not start'. |
+| skill | [`devcontainer`](../.agent-src/skills/devcontainer/SKILL.md) |  | Wire up DevContainers / GitHub Codespaces — `devcontainer.json`, container images, secrets, VS Code features, port forwarding. NOT for tuning Copilot itself (use `copilot-config`). |
 | skill | [`developer-like-execution`](../.agent-src/skills/developer-like-execution/SKILL.md) |  | Use when implementing, debugging, refactoring, or reviewing code — enforces the think → analyze → verify → execute workflow — even when the user just says 'implement X' without naming it. |
 | skill | [`discovery-interview`](../.agent-src/skills/discovery-interview/SKILL.md) |  | Use when running discovery interviews — question-bank build, bias audit, insight extraction. Triggers on 'audit my guide', 'extract insights from transcript', 'is my hypothesis falsifiable'. |
+| skill | [`doc-coauthoring`](../.agent-src/skills/doc-coauthoring/SKILL.md) |  | Use when co-authoring a PRD, design doc, RFC, decision doc, or technical spec — 3-stage flow (context → section-by-section → reader-test) — even if the user just says 'help me write this spec'. |
 | skill | [`docker`](../.agent-src/skills/docker/SKILL.md) |  | Use when working with Docker — Dockerfile edits, docker-compose services, containers, or the dual-container (fast + Xdebug) setup — even when the user just says 'my container won't start'. |
 | skill | [`dto-creator`](../.agent-src/skills/dto-creator/SKILL.md) |  | Use when the user says "create a DTO", "new data transfer object", or needs to convert request/response data into a typed PHP class. Creates DTOs with SimpleDto base class and attribute mapping. |
 | skill | [`editorial-calendar`](../.agent-src/skills/editorial-calendar/SKILL.md) |  | Use when shaping cadence — evergreen / campaign / reactive split, beat-mapping across channel stages, content-debt management. Triggers on 'plan our content cadence', 'what should we publish'. |
@@ -96,7 +98,7 @@ are excluded.
 | skill | [`judge-code-quality`](../.agent-src/skills/judge-code-quality/SKILL.md) |  | Use when a diff needs a readability review — naming, single-responsibility, DRY, dead code, mismatch with codebase conventions — dispatched by /review-changes, /do-and-judge, /judge. |
 | skill | [`judge-security-auditor`](../.agent-src/skills/judge-security-auditor/SKILL.md) |  | Use when a diff may introduce security risk — authZ, injection, secrets, unsafe deserialization, SSRF, XSS, mass assignment — dispatched by /review-changes, /do-and-judge, /judge. |
 | skill | [`judge-test-coverage`](../.agent-src/skills/judge-test-coverage/SKILL.md) |  | Use when a diff may lack tests — missing assertions, uncovered branches, over-mocking, no regression test for a bug fix — dispatched by /review-changes, /do-and-judge, /judge, even without 'tests'. |
-| skill | [`laravel`](../.agent-src/skills/laravel/SKILL.md) |  | Writes Laravel code following framework conventions, project architecture, and modern best practices for controllers, requests, services, jobs, events, policies, and application structure. |
+| skill | [`laravel`](../.agent-src/skills/laravel/SKILL.md) |  | Writes Laravel PHP — Eloquent, Artisan controllers, FormRequests, jobs, events, policies, providers. For Symfony / Doctrine use `symfony-workflow`. For framework-free PHP use `php-coder`. |
 | skill | [`laravel-horizon`](../.agent-src/skills/laravel-horizon/SKILL.md) |  | Use when working with Laravel queues in production — Horizon dashboard, worker supervision, job metrics, balancing strategies — even when the user just says 'my jobs are piling up'. |
 | skill | [`laravel-mail`](../.agent-src/skills/laravel-mail/SKILL.md) |  | Use when building Laravel emails — Mailables, Markdown templates, queued sending, attachments, previews — even when the user says 'send this as an email' without naming Mailables. |
 | skill | [`laravel-middleware`](../.agent-src/skills/laravel-middleware/SKILL.md) |  | Use when creating or modifying Laravel middleware — request/response filtering, groups, priority, terminable middleware, or route-level assignment. |
@@ -125,6 +127,7 @@ are excluded.
 | skill | [`mobile-e2e-strategy`](../.agent-src/skills/mobile-e2e-strategy/SKILL.md) |  | Use when picking a mobile E2E framework — Detox / Appium / Maestro / XCUITest / Espresso — or planning iOS Simulator / Android Emulator coverage in CI for RN, Expo, or native apps. |
 | skill | [`module-management`](../.agent-src/skills/module-management/SKILL.md) |  | Use when the user says "create module", "explore module", or works within app/Modules/. Understands module structure, auto-loading, route registration, and namespace conventions. |
 | skill | [`multi-tenancy`](../.agent-src/skills/multi-tenancy/SKILL.md) |  | Use when working with the multi-tenant architecture — customer DB switching, FQDN routing, tenant isolation, or cross-tenant operations. |
+| skill | [`nextjs-patterns`](../.agent-src/skills/nextjs-patterns/SKILL.md) |  | Writes Next.js App Router code — Server Components, Server Actions, RSC boundaries, route handlers, caching, and streaming — matching framework conventions and project architecture. |
 | skill | [`okr-tree-modeling`](../.agent-src/skills/okr-tree-modeling/SKILL.md) |  | Use when decomposing a company objective into team OKRs, auditing a draft OKR tree, or stress-testing an existing one for measurability and laddering. |
 | skill | [`onboarding-design`](../.agent-src/skills/onboarding-design/SKILL.md) |  | Use when designing customer onboarding — time-to-first-value, milestone design, friction audit, drop-off diagnosis. Triggers on 'fix onboarding', 'why do new accounts churn fast'. |
 | skill | [`onboarding-program`](../.agent-src/skills/onboarding-program/SKILL.md) |  | Use when shaping employee onboarding — time-to-productivity, role-by-role program, mentor pairing, 30/60/90 milestones. Triggers on 'design our onboarding', 'why are new hires ramping slow'. |
@@ -146,7 +149,7 @@ are excluded.
 | skill | [`po-discovery`](../.agent-src/skills/po-discovery/SKILL.md) |  | Use when shaping a fuzzy product ask into a refined backlog item — problem framing, user-story rewrite, AC tightening — even if the user just says 'help me write this ticket'. |
 | skill | [`positioning-strategy`](../.agent-src/skills/positioning-strategy/SKILL.md) |  | Use when locking the market frame — category, segment, alternative, point-of-view — before messaging, launch, or pricing rides on it. Triggers on 'who are we for', 'opposable audit'. |
 | skill | [`privacy-review`](../.agent-src/skills/privacy-review/SKILL.md) |  | Use when reviewing data flows for GDPR / CCPA / HIPAA fit — regulatory-regime delta, consent shape, breach-impact triage. Triggers on 'is this GDPR-safe', 'do we need a DPA'. |
-| skill | [`project-analysis-core`](../.agent-src/skills/project-analysis-core/SKILL.md) |  | Use for the universal deep-analysis workflow: project discovery, version resolution, docs loading, architecture mapping, execution flow, and package research. |
+| skill | [`project-analysis-core`](../.agent-src/skills/project-analysis-core/SKILL.md) |  | Raw discovery primitives — project discovery, version resolution, docs loading, architecture mapping, execution flow. Called by `universal-project-analysis`. Single-pass scan → `project-analyzer`. |
 | skill | [`project-analysis-hypothesis-driven`](../.agent-src/skills/project-analysis-hypothesis-driven/SKILL.md) |  | Use when a bug has multiple plausible causes across layers — competing hypotheses, validation loops, evidence-based conclusions — even when the user just says 'why is this happening?'. |
 | skill | [`project-analysis-laravel`](../.agent-src/skills/project-analysis-laravel/SKILL.md) |  | Use for deep Laravel project analysis: boot flow, request lifecycle, container usage, Eloquent/data flow, async systems, and Laravel-specific failure patterns. |
 | skill | [`project-analysis-nextjs`](../.agent-src/skills/project-analysis-nextjs/SKILL.md) |  | Use for deep Next.js analysis: server vs client boundaries, routing, data fetching, caching, rendering modes, and hydration/runtime issues. |
@@ -154,7 +157,7 @@ are excluded.
 | skill | [`project-analysis-react`](../.agent-src/skills/project-analysis-react/SKILL.md) |  | Use for deep React analysis: component tree, state flow, props flow, hooks usage, rendering behavior, and React-specific failure patterns. |
 | skill | [`project-analysis-symfony`](../.agent-src/skills/project-analysis-symfony/SKILL.md) |  | Use for deep Symfony project analysis: kernel/bootstrap, container wiring, routing/request flow, Doctrine, security, Messenger, and Symfony-specific failure patterns. |
 | skill | [`project-analysis-zend-laminas`](../.agent-src/skills/project-analysis-zend-laminas/SKILL.md) |  | Use for deep Zend Framework or Laminas project analysis: bootstrap, config merge order, service manager, MVC flow, data layer, and migration-specific risks. |
-| skill | [`project-analyzer`](../.agent-src/skills/project-analyzer/SKILL.md) |  | ONLY when user explicitly requests: full project analysis, tech stack detection, or structured analysis documents for agents/analysis/. NOT for regular feature work. |
+| skill | [`project-analyzer`](../.agent-src/skills/project-analyzer/SKILL.md) |  | ONLY when user asks for single-pass tech-stack detection or `agents/analysis/` write-up. Deep multi-pass audit → `universal-project-analysis`. Raw primitives → `project-analysis-core`. |
 | skill | [`project-docs`](../.agent-src/skills/project-docs/SKILL.md) |  | Use when looking for project-specific documentation. Knows which docs exist in agents/docs/ and agents/contexts/ and maps work areas to relevant docs. |
 | skill | [`prompt-engineering-patterns`](../.agent-src/skills/prompt-engineering-patterns/SKILL.md) |  | Use when designing production-LLM prompts — few-shot, chain-of-thought, system prompts, templates, self-verification — distinct from prompt-optimizer and refine-prompt. |
 | skill | [`prompt-optimizer`](../.agent-src/skills/prompt-optimizer/SKILL.md) |  | Use when the user wants a prompt optimized for ChatGPT, Claude, Gemini, or another AI — 'make this prompt better', 'optimize for ChatGPT', 'rewrite my prompt' — even without saying 'optimize'. |
@@ -193,6 +196,7 @@ are excluded.
 | skill | [`sql-writing`](../.agent-src/skills/sql-writing/SKILL.md) |  | Use when writing raw SQL — MariaDB/MySQL syntax, parameterization, raw migrations, seeders with `DB::statement` — even when the user just pastes a query and asks 'why is this slow' without naming SQL. |
 | skill | [`stakeholder-tradeoff`](../.agent-src/skills/stakeholder-tradeoff/SKILL.md) |  | Use when stakeholders pull a decision in different directions — frames each lens, builds a trade-off matrix, surfaces the cost of every choice — even if the user just says 'PO and ops disagree'. |
 | skill | [`subagent-orchestration`](../.agent-src/skills/subagent-orchestration/SKILL.md) |  | Use when orchestrating implementer/judge subagents — seven modes (do-and-judge ±two-stage, do-in-steps/parallel/worktrees, do-competitively, judge-with-debate) — models from .agent-settings.yml. |
+| skill | [`symfony-workflow`](../.agent-src/skills/symfony-workflow/SKILL.md) |  | Writes Symfony PHP — DI container, bundles, Doctrine, Messenger, Security voters, console commands. For Laravel / Eloquent / Artisan use `laravel`. For framework-free PHP use `php-coder`. |
 | skill | [`systematic-debugging`](../.agent-src/skills/systematic-debugging/SKILL.md) |  | Use when hitting a bug, test failure, crash, or unexpected behavior — enforces reproduce → isolate → hypothesize → verify before any fix — even when the user just says 'this is broken' or 'quick fix'. |
 | skill | [`tailwind-engineer`](../.agent-src/skills/tailwind-engineer/SKILL.md) |  | Use when writing or reviewing Tailwind CSS — utility-first, design-token discipline, no inline-style drift, responsive variants, dark mode — even on 'style this' or 'mach das hübsch'. |
 | skill | [`tech-debt-tracker`](../.agent-src/skills/tech-debt-tracker/SKILL.md) |  | Use when surfacing tech debt as trackable items — interest-vs-principal framing, prioritisation by carrying cost, repayment plan — even if the user just says 'this codebase is a mess'. |
@@ -208,7 +212,7 @@ are excluded.
 | skill | [`traefik`](../.agent-src/skills/traefik/SKILL.md) |  | Use when setting up Traefik as a local reverse proxy — real domains on 127.0.0.1, trusted HTTPS via mkcert, automatic service discovery, and multi-project routing. |
 | skill | [`ui-component-architect`](../.agent-src/skills/ui-component-architect/SKILL.md) |  | Use when shaping a UI component tree — composition vs inheritance, slot patterns, prop API design, controlled vs uncontrolled, polymorphic — even on 'split this component'. |
 | skill | [`unit-economics-modeling`](../.agent-src/skills/unit-economics-modeling/SKILL.md) |  | Use when modeling CAC, LTV, payback, contribution margin, or burn-multiple per customer — SaaS, marketplace, or transactional. Triggers on 'are we unit-economic', 'what is our LTV/CAC'. |
-| skill | [`universal-project-analysis`](../.agent-src/skills/universal-project-analysis/SKILL.md) |  | ONLY when user explicitly requests: full project analysis, deep codebase audit, or comprehensive architecture review. Routes to core and framework-specific analysis skills. |
+| skill | [`universal-project-analysis`](../.agent-src/skills/universal-project-analysis/SKILL.md) |  | ONLY when user asks for deep multi-pass codebase audit — orchestrator routing to `project-analysis-core` + framework-specific `project-analysis-*`. Single-pass scan → `project-analyzer`. |
 | skill | [`upstream-contribute`](../.agent-src/skills/upstream-contribute/SKILL.md) |  | Use when a learning, new skill, rule improvement, or bug fix from a consumer project should be contributed back to the shared agent-config package. |
 | skill | [`using-git-worktrees`](../.agent-src/skills/using-git-worktrees/SKILL.md) |  | Use when starting parallel work in isolation from the current branch — spawn a git worktree with ignore-safety checks and a clean test baseline — even when the user says 'try this on the side'. |
 | skill | [`validate-feature-fit`](../.agent-src/skills/validate-feature-fit/SKILL.md) |  | Validate whether a feature request fits the existing codebase — check for duplicates, contradictions, scope creep, and architectural misfit |
@@ -218,7 +222,7 @@ are excluded.
 | skill | [`voice-and-tone-design`](../.agent-src/skills/voice-and-tone-design/SKILL.md) |  | Use when shaping brand voice — voice attributes, tone-by-context matrix, consistency review. Triggers on 'define our voice', 'why does our copy sound different on every surface'. |
 | skill | [`websocket`](../.agent-src/skills/websocket/SKILL.md) |  | Use when building real-time features — WebSocket broadcasting, live updates, presence channels, connection state — even when the user just says 'push this to the client live'. |
 
-## Rules (58)
+## Rules (62)
 
 | kind | name | type | description |
 |---|---|---|---|
@@ -237,6 +241,8 @@ are excluded.
 | rule | [`commit-conventions`](../.agent-src/rules/commit-conventions.md) | auto | Git commit message format, branch naming, conventional commits, committing, pushing, or creating pull requests |
 | rule | [`commit-policy`](../.agent-src/rules/commit-policy.md) | always | Commit policy — never commit and never ask about committing unless the user said so this turn, the roadmap authorizes it, or a commit command is invoked |
 | rule | [`context-hygiene`](../.agent-src/rules/context-hygiene.md) | auto | When debugging, fixing errors, or running long conversations — 3-failure stop rule, tool-loop detection, fresh-chat triggers |
+| rule | [`copilot-routing`](../.agent-src/rules/copilot-routing.md) | auto | When configuring the GitHub Copilot AI assistant — copilot-instructions.md, PR-review comment patterns, suggestion behavior — route to the copilot-config skill |
+| rule | [`devcontainer-routing`](../.agent-src/rules/devcontainer-routing.md) | auto | When wiring DevContainers or GitHub Codespaces — devcontainer.json, container images, VS Code features, port forwarding — route to the devcontainer skill |
 | rule | [`direct-answers`](../.agent-src/rules/direct-answers.md) | always | Always — direct, unembellished answers. No flattery, no invented facts (verify load-bearing claims, otherwise ask). Emojis only as functional markers. Brevity is the default. |
 | rule | [`docker-commands`](../.agent-src/rules/docker-commands.md) | auto | Running PHP commands inside Docker containers — artisan, composer, phpstan, rector, ecs, phpunit, tests, migrations, and any CLI tool execution |
 | rule | [`domain-adoption-policy`](../.agent-src/rules/domain-adoption-policy.md) | auto | Adopting a new domain track (mobile, ML, blockchain, IoT, gaming) — gates import on demand, ownership, CI fit, Sunset compatibility BEFORE harvest |
@@ -247,6 +253,7 @@ are excluded.
 | rule | [`improve-before-implement`](../.agent-src/rules/improve-before-implement.md) | auto | Before implementing features or architectural changes — validate the request against existing code, challenge weak requirements, suggest improvements |
 | rule | [`invite-challenge`](../.agent-src/rules/invite-challenge.md) | auto | Before executing a complex plan or non-trivial design — ask 'am I solving the right problem?' and pause for user confirmation, even when no ambiguity |
 | rule | [`language-and-tone`](../.agent-src/rules/language-and-tone.md) | always | Language and tone — informal German Du, English code comments, .md files always English |
+| rule | [`laravel-routing`](../.agent-src/rules/laravel-routing.md) | auto | When writing or reviewing Laravel code — controllers, Eloquent, Artisan, jobs, events, policies — route to the laravel skill |
 | rule | [`laravel-translations`](../.agent-src/rules/laravel-translations.md) | auto | Laravel language files, translations, i18n, lang/de, lang/en, __() helper, localization, multilingual text |
 | rule | [`markdown-safe-codeblocks`](../.agent-src/rules/markdown-safe-codeblocks.md) | auto | Generating markdown output that contains code blocks — prevent broken nesting |
 | rule | [`minimal-safe-diff`](../.agent-src/rules/minimal-safe-diff.md) | auto | When writing or reviewing a diff — the smallest change that solves the stated problem; no drive-by edits, opportunistic refactors, or reformatting |
@@ -272,6 +279,7 @@ are excluded.
 | rule | [`skill-improvement-trigger`](../.agent-src/rules/skill-improvement-trigger.md) | auto | After completing a meaningful task — trigger post-task learning capture if pipelines.skill_improvement is enabled |
 | rule | [`skill-quality`](../.agent-src/rules/skill-quality.md) | auto | Creating, editing, or reviewing skills — minimum quality standard, every skill must be executable, validated, and self-contained |
 | rule | [`slash-command-routing-policy`](../.agent-src/rules/slash-command-routing-policy.md) | auto | When user types a slash command like /create-pr, /commit, or pastes command file content |
+| rule | [`symfony-routing`](../.agent-src/rules/symfony-routing.md) | auto | When writing or reviewing Symfony code — DI container, bundles, Doctrine, Messenger, Security voters, console commands — route to the symfony-workflow skill |
 | rule | [`think-before-action`](../.agent-src/rules/think-before-action.md) | auto | Before coding, modifying, or debugging — analyze first, verify with real tools, never guess or trial-and-error |
 | rule | [`token-efficiency`](../.agent-src/rules/token-efficiency.md) | auto | When running CLI tools, fetching logs, or producing replies — redirect verbose output, minimize tool calls, keep replies concise |
 | rule | [`token-optimizer-maintenance`](../.agent-src/rules/token-optimizer-maintenance.md) | auto | Editing a token-optimizer-cited asset (cli-output-handling, rtk-output-filtering, token-efficiency, markitdown) — sync catalog same commit |
@@ -281,7 +289,7 @@ are excluded.
 | rule | [`user-interaction`](../.agent-src/rules/user-interaction.md) | auto | Asking the user a question, presenting options, or summarizing progress — numbered-options Iron Law, single-recommendation rule, progress indicators |
 | rule | [`verify-before-complete`](../.agent-src/rules/verify-before-complete.md) | always | Verify before completion — run tests and quality tools before claiming done |
 
-## Commands (106)
+## Commands (108)
 
 | kind | name | cluster | description |
 |---|---|---|---|
@@ -309,11 +317,13 @@ are excluded.
 | command | [`context:refactor`](../.agent-src/commands/context/refactor.md) | cluster: context | Analyze, update, and extend an existing context document |
 | command | [`context`](../.agent-src/commands/context.md) | cluster: context | Context orchestrator — routes to create, refactor |
 | command | [`cost-report`](../.agent-src/commands/cost-report.md) |  | Capture token cost from the active Claude Code session, append to the local sessions store, and surface the 50/75/90/100% budget alert ladder with cost-profile suggestions. |
+| command | [`council:analysis`](../.agent-src/commands/council/analysis.md) | cluster: council | Run the council on a local analysis output (project-analyze, audit script, codebase scan) — critiques the analysis itself for dedup, evidence quality, and roadmap-readiness. |
+| command | [`council:debate`](../.agent-src/commands/council/debate.md) | cluster: council | Multi-round council debate with progressive cost disclosure — each member produces a position, then rebuts the strongest opposing position in subsequent rounds. User confirms spend between rounds. |
 | command | [`council:default`](../.agent-src/commands/council/default.md) | cluster: council | Default council lens — neutral framing, redacted context, advisory output only. Run `/council default <input>` for prompt/roadmap/diff/files; the cluster shows a menu when invoked bare. |
 | command | [`council:design`](../.agent-src/commands/council/design.md) | cluster: council | Run the council on a design document, ADR, or architecture proposal — surfaces hidden coupling, missing rollback, and sequencing risk before commitment. |
 | command | [`council:optimize`](../.agent-src/commands/council/optimize.md) | cluster: council | Run the council on an optimization target — perf hot path, memory pattern, query, or an /optimize-* output — for ranked, evidence-based suggestions instead of generic advice. |
 | command | [`council:pr`](../.agent-src/commands/council/pr.md) | cluster: council | Pull a GitHub PR via gh CLI and run the council on the diff with a PR-specific neutrality preamble — read-only by default; comment posting is opt-in. |
-| command | [`council`](../.agent-src/commands/council.md) | cluster: council | Council orchestrator — routes to default, pr, design, optimize |
+| command | [`council`](../.agent-src/commands/council.md) | cluster: council | Council orchestrator — routes to default, pr, design, optimize, analysis, debate |
 | command | [`create-pr:description-only`](../.agent-src/commands/create-pr/description-only.md) | cluster: create-pr | Generate a PR description as a copyable markdown block — used standalone or by create-pr |
 | command | [`create-pr`](../.agent-src/commands/create-pr.md) | cluster: create-pr | Create a GitHub PR with structured description from Jira ticket and code changes |
 | command | [`e2e-heal`](../.agent-src/commands/e2e-heal.md) |  | Find, debug, and fix failing Playwright E2E tests |

package/docs/contracts/adr-architectural-consensus-mechanism.md

@@ -0,0 +1,67 @@
+---
+stability: beta
+keep-beta-until: 2026-08-12
+---
+
+# ADR — Architectural Consensus Mechanism (bus-factor / multi-author readiness)
+
+> **Status:** Decided · 2026-05-14
+> **Context:** v2 council finding C1 (file [01-bus-factor-and-consensus.md](../../agents/council-sessions/2026-05-14-v2-analysis/feedback/01-bus-factor-and-consensus.md)) flagged that a single-author skill suite cannot detect ontology drift (two skills with overlapping triggers, drift between description and body, generic best-practice patterns repeated across clusters). The package needs a **mechanical consensus signal** that does not depend on the original author's judgment.
+> **Roadmap:** Closes Phase 5.2 of [`step-1-v2-feedback-followup`](../../agents/roadmaps/step-1-v2-feedback-followup.md).
+
+## Decision
+
+A **two-tier consensus mechanism**, layered by cost:
+
+1. **Tier A — Automated ontology lint (every PR).** `scripts/skill_collision_clusters.py` produces `agents/reports/skill-collision-clusters.json`. New skills that fall into an existing collision cluster (description-vector similarity ≥ threshold or trigger-keyword overlap ≥ threshold) **break the build** unless paired with one of:
+   - A routing rule (tier-2a path-prefix or tier-3 keyword) that declares ownership, OR
+   - An ADR under `docs/contracts/adr-*.md` that names the trade-off.
+2. **Tier B — ADR on first collision (per cluster, not per skill).** When Tier A flags a new collision and the author chooses to keep both skills, they write a one-page ADR naming what each skill owns and where the boundary lives. The ADR is **per cluster**, not per skill — adding a fourth `php-*` skill to an established `php-*` cluster does not require a new ADR; only the cluster's first ADR matters.
+
+Tier C (external review per N skills) is **rejected** as standing process; it is reserved for major-version boundaries (v3, v4) where the host wants a one-shot external sanity pass.
+
+## Why this was a real question
+
+The three options from feedback file 01 were:
+
+| Option | Cost | Detection power | Failure mode |
+|---|---|---|---|
+| (a) ADR per cluster | medium author cost, near-zero CI cost | high once written, zero before | author forgets to write the ADR; drift accumulates silently |
+| (b) Automated ontology lint | low marginal cost per PR, one-time build cost | catches collisions at PR time; no semantic depth | flags noise (similar descriptions that own different surfaces); needs threshold tuning |
+| (c) External review per N skills | high USD + calendar cost | high but lagged | gate fires too late; expensive |
+
+Picking only (a) means the gate fires after the drift has already shipped (review of a written ADR ≠ detection of a missing ADR). Picking only (b) means the lint surfaces a number but the human still has to decide what to do with it. Picking only (c) means the gate fires once per quarter at best and costs real money.
+
+The two-tier choice is the convener-skeptic synthesis: **(b) is the always-on gate, (a) is the high-signal moment (b) creates.** (c) stays reserved for the moments where neither (b) nor (a) can answer — and those moments are rare enough not to warrant standing process.
+
+## Consequences
+
+- **Author cost (steady-state):** zero. The lint runs in CI; the author only writes an ADR when they introduce a new cluster head.
+- **Author cost (when collisions land):** one ADR per cluster, ~150-300 lines.
+- **CI cost:** O(skills²) similarity scan; current 210 skills → ~22k pairs scanned at ms-each. Acceptable for `ci-fast`.
+- **Reviewer cost:** the cluster ADR is the single review surface — reviewers don't have to re-derive the cluster boundary on every PR touching the cluster.
+- **What this does not catch:** drift between a skill's description and its body. That is a different problem, addressed by `audit-descriptions` / `lint-skills` (already in CI).
+- **What this does not replace:** the `skill-quality` Iron-Law rule (every skill must be executable, validated, self-contained) and `description-assist` (push-toward-trigger phrasing). Those remain author-time obligations.
+
+## Rejected alternatives
+
+- **(c) alone — external review per N skills.** Too expensive as standing process; gate fires too late to prevent drift.
+- **Tier A as warn-only forever.** Defeats the purpose — drift accumulates if there is no fail-the-build state.
+- **Persona-prompted self-review** (host runs sibling models). Rejected by `ai-council` skill (council convergence, 2026-05-06): same model, same blind spots, more cost.
+
+## Acceptance test
+
+- [x] `scripts/skill_collision_clusters.py` exists and emits `agents/reports/skill-collision-clusters.json`
+- [x] `scripts/score_skill_selection.py` exists and emits `agents/reports/skill-selection-accuracy.json`
+- [x] Phase 3 routing rules (`laravel-routing`, `symfony-routing`, `copilot-routing`, `devcontainer-routing`) demonstrate the tier-B response to a flagged cluster
+- [ ] Lint promoted to `fail-the-build` once thresholds are confirmed stable across one full release cycle (currently `warn-only`)
+
+The final acceptance gate (lint going from warn-only to fail-the-build) is deferred to the next release window so the threshold has time to settle without breaking PRs on borderline noise. Tracked as a follow-up in the next step-N roadmap.
+
+## Related
+
+- Origin: [`agents/council-sessions/2026-05-14-v2-analysis/feedback/01-bus-factor-and-consensus.md`](../../agents/council-sessions/2026-05-14-v2-analysis/feedback/01-bus-factor-and-consensus.md)
+- Mechanical scripts: [`scripts/skill_collision_clusters.py`](../../scripts/skill_collision_clusters.py), [`scripts/score_skill_selection.py`](../../scripts/score_skill_selection.py)
+- Sibling decision: [`docs/contracts/rule-router.md`](rule-router.md) — the routing layer the ADR feeds
+- Sibling decision: [`docs/contracts/multi-tool-projection-fidelity.md`](multi-tool-projection-fidelity.md) — Phase 4 of the same roadmap
+- Standing skill: [`.augment/skills/ai-council/SKILL.md`](../../.augment/skills/ai-council/SKILL.md) — the explicit-opt-in path for the rare moments tier C is invoked

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

@@ -73,7 +73,7 @@ stability: stable
   § Beta-review markers; `scripts/check_beta_review_markers.py` wired
   into `task ci`; 39 beta contracts back-filled (P5.4).
 - Test-redundancy audit produced
-  [`road-to-test-cleanup.md`](../../agents/roadmaps/road-to-test-cleanup.md)
+  [`step-5-test-cleanup.md`](../../agents/roadmaps/step-5-test-cleanup.md)
   — audit-only, no deletions (P5.5).
 
 ### Release-trunk discipline (Phase 1)
@@ -119,7 +119,7 @@ keep-beta-until dates beyond the window.
 - **Showcase capture** → future `road-to-showcase-capture.md` when a
   hosted-LLM runner is on the table.
 - **Test-suite deletion** →
-  [`road-to-test-cleanup.md`](../../agents/roadmaps/road-to-test-cleanup.md)
+  [`step-5-test-cleanup.md`](../../agents/roadmaps/step-5-test-cleanup.md)
   (audit-only sibling spawned by P5.5; non-destructive by default).
 - **Persona Block B** (Architect / Risk-Officer extension) —
   anti-recommended per the sibling closure decision; not deferred,

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

@@ -0,0 +1,186 @@
+---
+stability: beta
+keep-beta-until: 2026-08-12
+---
+
+# AI-Council Config (`agents/.ai-council.yml`)
+
+**Purpose.** Lock the schema, validation, and precedence rules for the
+centralized council config file. Every later phase of
+[`step-2-ai-council-consolidation.md`](../../agents/roadmaps/step-2-ai-council-consolidation.md)
+reads from this file; the contract here is the boundary that prevents
+drift across the loader, the CLI, the orchestrator, and the
+`agents/.ai-council.yml` file itself.
+
+**Audience.** Authors of `scripts/ai_council/config.py`, `council_cli.py`,
+`scripts/ai_council/orchestrator.py`, and the `agents/.ai-council.yml`
+starter. Also reviewers checking that new providers / advisors / debate
+features keep the schema intact.
+
+**Status.** Internal-locked. Changes require a contract version bump and
+a revision entry in the consuming roadmap.
+
+## File location
+
+The single source of truth is **`agents/.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.
+
+## Top-level schema
+
+```yaml
+enabled: <bool>                 # master switch, required
+defaults:                       # per-invocation defaults, required
+  mode: <"api" | "manual">
+  min_rounds: <int >= 1>
+  deep_min_rounds: <int >= min_rounds>
+  max_output_tokens: <int >= 0>           # 0 widens to provider ceiling
+  session_retention_days: <int >= 0>      # 0 disables pruning
+  debate_max_rounds: <int >= 2>           # reserved by Phase 0, wired in Phase 7
+cost_budget:                    # hard caps per /council invocation, required
+  max_input_tokens: <int >= 0>            # 0 disables this cap
+  max_output_tokens: <int >= 0>           # 0 disables this cap
+  max_calls: <int >= 0>                   # 0 disables this cap
+  max_total_usd: <number >= 0>            # 0 disables the USD ceiling
+members:                        # per-provider blocks, at least one enabled
+  <provider>:
+    enabled: <bool>
+    model: <string>
+    api_key_ref: <string>                 # see `api_key_ref` forms below
+    mode: <"api" | "manual">              # optional override of defaults.mode
+advisors:                       # Thinking-style replace-mode advisors
+  <advisor-key>:
+    enabled: <bool>
+    member: <provider>                    # required; references members.<provider>
+    model: <string>                       # optional; overrides member.model
+    persona: <path>                       # optional; defaults to personas/advisors/<advisor-key>.md
+```
+
+Supported `<provider>` keys: `anthropic`, `openai`, `gemini`, `xai`,
+`perplexity`. Unknown providers fail validation closed.
+
+### Advisor block (Phase 6, replace-mode)
+
+Five built-in advisor keys ship under
+[`.agent-src.uncompressed/personas/advisors/`](../../.agent-src.uncompressed/personas/advisors/):
+`contrarian`, `first-principles`, `expansionist`, `outsider`,
+`executor`. Each entry binds one advisor to one enabled provider. When
+`enabled: true`, the orchestrator REPLACES that provider's plain-member
+call with the advisor-persona call — the run keeps the same total call
+count as a plain run.
+
+- `member` is required and must name a known provider. The validator
+  rejects an enabled advisor whose `member` is missing from the
+  `members` block, OR exists but has `enabled: false` — silent skips
+  on the spend path are not allowed.
+- `model` is optional. When omitted, the advisor inherits its bound
+  member's `model`. When set, it overrides for that advisor call only.
+- `persona` is optional. When omitted, the loader resolves the file at
+  `personas/advisors/<advisor-key>.md` relative to the package root.
+
+### Advisor persona labels in peer-review (preserve-persona)
+
+Phase 5 peer-review anonymisation strips provider/model identity per
+the Iron Law of Neutrality. On an advisor-mode run, the anonymisation
+step preserves the **advisor persona label** as signal — peer-review
+output renders as `Response A (Contrarian)`, never
+`Response A (Anthropic Opus)`. Plain runs strip identity entirely.
+Hard-coded behaviour — no flag, no opt-out.
+
+## `api_key_ref` forms
+
+Exactly two forms. Raw keys in the yml are a hard validation error.
+
+- `file:<path>` — read from a 0600 file. Relative paths resolve under
+  `~/.event4u/agent-config/`; absolute paths are honored as
+  written. The legacy `~/.config/agent-config/` location is still read
+  as a fallback by `scripts/_lib/user_global_paths.py`.
+- `env:<VAR>` — read from the named environment variable at load time.
+  Missing or empty env var is a `KeyGateError`.
+
+## Precedence
+
+Resolution order for every member-level setting (mode, model, key):
+
+```
+invocation flag  >  per-member field  >  defaults block  >  built-in fallback
+```
+
+Same shape applies to round counts (`--rounds N` > `defaults.min_rounds`,
+plus the `deep_min_rounds` floor when `--depth deep` or a consuming
+artefact's `council_depth: deep` frontmatter fires).
+
+## Normative behaviour — migrated verbatim
+
+These rules are part of the contract; the consuming YAML reproduces them
+as comments and the loader enforces them.
+
+- **Iron Law of Neutrality.** Council members never see the host agent's
+  reasoning — only the artefact + a neutral system prompt. Phase 6 Step 3a
+  preserves advisor persona labels in peer-review but strips provider
+  identity.
+- **Autonomy carve-out — no silent spend.** The `/council` command always
+  asks before invoking, even under autonomy: on. Cost is real and paid.
+- **Manual vs API transport.** `api` = direct SDK call against the
+  provider's API (billable). `manual` = copy-paste loop, user is the
+  transport (free). Per-invocation flag > per-member override > defaults.
+- **Tokens never stored in this yml.** Keys live in 0600 files
+  (`~/.event4u/agent-config/<provider>.key`, installed via
+  `bash scripts/install_<provider>_key.sh` for providers that ship an
+  installer) or in env vars. Validation rejects any literal-looking key.
+- **`max_output_tokens: 0` widening.** Internally widened to the safe
+  provider ceiling (16384) because Anthropic rejects `max_tokens=0`. The
+  CLI `--max-tokens` flag overrides this on a single invocation; the
+  cost estimator uses the same value as its worst-case ceiling.
+- **`deep_min_rounds` is monotonic.** Effective rounds =
+  `max(deep_min_rounds, min_rounds)`. Lowering `deep_min_rounds` below
+  `min_rounds` has no effect. Standard tasks keep `min_rounds`; cost
+  rises only when an artefact opts in via `council_depth: deep` in
+  frontmatter or `--depth deep` on the CLI.
+- **Session retention.** `agents/council-sessions/` audit folders older
+  than `defaults.session_retention_days` are pruned automatically on the
+  next `save()`. `0` disables pruning — disk grows unbounded.
+- **`cost_budget` semantics.** The orchestrator pauses before any member
+  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/.agent-prices.md`](../../agents/.agent-prices.md)
+  (gitignored, refreshed weekly by `python3 scripts/update_prices.py`;
+  bootstrapped from `scripts/ai_council/_default_prices.py` on first run).
+
+## Validation rules
+
+A loader call (`scripts/ai_council/config.py:load_council_config()`)
+must reject the file with a clear `KeyGateError` (or equivalent typed
+error) when any of these hold:
+
+1. Required top-level key missing (`enabled`, `defaults`, `cost_budget`,
+   `members`).
+2. `members` block has no provider with `enabled: true`.
+3. Unknown provider key under `members` or `advisors`.
+4. `api_key_ref` missing for an enabled member, or in an unknown form
+   (not `file:` and not `env:`), or pointing at a non-existent file /
+   missing env var.
+5. A value under `api_key_ref` looks like a raw secret (starts with
+   `sk-`, `pk-`, `xai-`, or matches a provider's key prefix).
+6. `defaults.deep_min_rounds < defaults.min_rounds` is allowed (clamped
+   by the monotonic rule at runtime) but logged as a warning.
+7. `defaults.mode` not in `{"api", "manual"}`; per-member `mode` override
+   same constraint.
+8. `advisors.<key>.member` missing, unknown, or pointing at a
+   `members.<provider>` that does not exist or has `enabled: false`
+   (when the advisor itself is `enabled: true`). Silent skips are not
+   allowed — a typo never costs the user money on an unintended call
+   plan.
+9. `advisors.<key>.model` is set but not a string.
+
+## Migration footprint (Phase 0)
+
+- `.agent-settings.yml` → 14-key inventory under `ai_council:` removed
+  after a one-line breadcrumb comment is in place pointing at this
+  contract.
+- `.agent-settings.template.yml` → same removal.
+- New file `agents/.ai-council.yml` checked in with two enabled
+  providers (anthropic + openai) and three disabled
+  (gemini + xai + perplexity). Models pre-filled from the Phase 0
+  default set; comments mirror this contract.

package/docs/contracts/command-clusters.md

@@ -42,7 +42,7 @@ column 1 of this table.
 | `judge` | 2 | `solo` · `on-diff` · `steps` | `judge` (legacy standalone) · `do-and-judge` · `do-in-steps` |
 | `commit` | 2 | `in-chunks` | `commit-in-chunks` |
 | `create-pr` | 2 | `description-only` | `create-pr-description` |
-| `council` | 3 | `default` · `pr` · `design` · `optimize` | `council` (legacy default lens) · `council-pr` · `council-design` · `council-optimize` |
+| `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. |
 | `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. |
@@ -119,6 +119,62 @@ 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.uncompressed/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`](../../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: