@event4u/agent-config 2.26.0 → 3.0.0

package/docs/catalog.md

@@ -1,13 +1,13 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **502 public artefacts** shipped by
+Consumer-facing catalog of all **490 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 (217)
+## Skills (218)
 
 | kind | name | extra | description |
 |---|---|---|---|
@@ -163,8 +163,8 @@ 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 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 | [`project-analyzer`](../.agent-src/skills/project-analyzer/SKILL.md) |  | ONLY when user asks for single-pass tech-stack detection or `agents/evidence/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/reference/docs/ and agents/settings/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'. |
 | skill | [`quality-tools`](../.agent-src/skills/quality-tools/SKILL.md) |  | Use when PHPStan, Rector, or ECS output appears — \"phpstan says mixed\", type errors, \"fix code style\", \"run rector\" — even when Eloquent/Laravel/model code is also mentioned. |
@@ -186,6 +186,7 @@ are excluded.
 | skill | [`roadmap-management`](../.agent-src/skills/roadmap-management/SKILL.md) |  | Use when the user says "create roadmap", "show roadmap", or "execute roadmap". Creates, reads, and manages roadmap files with phase tracking. |
 | skill | [`roadmap-writing`](../.agent-src/skills/roadmap-writing/SKILL.md) |  | Use when authoring or rewriting a roadmap in agents/roadmaps/ — phase prose, goal sentence, acceptance criteria, council notes — even when the user just says 'write a plan for X' or 'draft a roadmap'. |
 | skill | [`rtk-output-filtering`](../.agent-src/skills/rtk-output-filtering/SKILL.md) |  | Use when running verbose CLI commands — wraps them with rtk (Rust Token Killer) for 60-90% token savings. Covers installation, configuration, and usage patterns. |
+| skill | [`rule-refactor`](../.agent-src/skills/rule-refactor/SKILL.md) |  | Use when the rule set is over the Augment budget, when a new rule would breach it, or when asked to audit / merge / prune rules — runs the audit pipeline and proposes a verdict per rule. |
 | skill | [`rule-writing`](../.agent-src/skills/rule-writing/SKILL.md) |  | Use when creating or editing a rule in .agent-src.uncompressed/rules/ — trigger wording, always vs auto classification, size budget — even when the user just says 'add a rule for X'. |
 | skill | [`runway-cognition`](../.agent-src/skills/runway-cognition/SKILL.md) |  | Use when reasoning about cash runway — burn shape, fundraise triggers, layoff-vs-cut-vs-grow decisions. Triggers on 'how long do we have', 'should we raise', 'cut or grow'. |
 | skill | [`scenario-modeling`](../.agent-src/skills/scenario-modeling/SKILL.md) |  | Use when constructing base / upside / downside scenarios — three-statement modeling, sensitivity analysis, optionality reasoning. Triggers on 'model the scenarios', 'what if growth halves'. |
@@ -229,95 +230,83 @@ are excluded.
 | skill | [`voc-extract`](../.agent-src/skills/voc-extract/SKILL.md) |  | Use when extracting Voice-of-Customer themes from existing artefacts — GH issues, PR threads, Sentry patterns. Triggers on 'what are users saying', 'recurring complaints', 'top themes'. |
 | 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'. |
 
-## Rules (83)
+## Rules (71)
 
 | kind | name | type | description |
 |---|---|---|---|
 | rule | [`agent-authority`](../.agent-src/rules/agent-authority.md) | always | Priority Index for the four authority rules — Hard Floor → Permission Gate → Commit Default → Trivial-vs-Blocking; read first, route to canonical rule |
-| rule | [`agent-docs`](../.agent-src/rules/agent-docs.md) | auto | Reading, creating, or updating agent documentation, module docs, roadmaps, or AGENTS.md |
 | rule | [`analysis-skill-routing`](../.agent-src/rules/analysis-skill-routing.md) | manual | When choosing an analysis skill, route to the narrowest matching skill instead of defaulting to broad analysis |
-| rule | [`architecture`](../.agent-src/rules/architecture.md) | auto | Architecture rules for creating new files, classes, controllers, modules, or making structural decisions about project organization |
-| rule | [`artifact-drafting-protocol`](../.agent-src/rules/artifact-drafting-protocol.md) | auto | Creating a new skill, rule, command, or guideline, or significantly rewriting one — runs mandatory Understand → Research → Draft before drafting |
-| rule | [`artifact-engagement-recording`](../.agent-src/rules/artifact-engagement-recording.md) | auto | After a /implement-ticket or /work phase-step (refine/memory/analyze/plan/implement/test/verify/report) or full task — emit one telemetry:record call |
+| rule | [`architecture`](../.agent-src/rules/architecture.md) | auto | Architecture rules for new files, classes, controllers, modules, or structural decisions about project organization |
+| rule | [`artifact-drafting-protocol`](../.agent-src/rules/artifact-drafting-protocol.md) | auto | Creating a new skill/rule/command/guideline or significantly rewriting one — runs mandatory Understand → Research → Draft first |
+| rule | [`artifact-engagement-recording`](../.agent-src/rules/artifact-engagement-recording.md) | auto | After a /implement-ticket or /work phase-step or full task — emit one telemetry:record call |
 | rule | [`ask-when-uncertain`](../.agent-src/rules/ask-when-uncertain.md) | always | Ask when uncertain — don't guess, assume, or improvise |
-| rule | [`autonomous-execution`](../.agent-src/rules/autonomous-execution.md) | auto | Whether to ask or act on a workflow step — trivial-vs-blocking, autonomy opt-in, commit default; Hard Floor in non-destructive-by-default |
-| rule | [`capture-learnings`](../.agent-src/rules/capture-learnings.md) | auto | After completing a task where a repeated mistake or successful pattern appeared — capture as rule or skill |
-| rule | [`caveman-speak`](../.agent-src/rules/caveman-speak.md) | auto | When caveman.speak_scope != off — compress reply prose to caveman grammar with carve-outs for numbered options, Iron-Law, code, paths, error markers |
-| rule | [`cli-output-handling`](../.agent-src/rules/cli-output-handling.md) | auto | Running CLI commands that produce verbose output — git, tests, linters, docker, build tools, artisan, npm, composer. Wrap with rtk; tail/grep fallback |
-| rule | [`command-suggestion-policy`](../.agent-src/rules/command-suggestion-policy.md) | auto | User prompt without /command matching an eligible slash command — surface matches as numbered options with as-is escape; never auto-executes |
-| 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 | [`augment-edit-discipline`](../.agent-src/rules/augment-edit-discipline.md) | auto | Editing .augment/ or .agent-src.uncompressed/ — keep files project-agnostic; sync counts and cross-refs on add/rename/delete |
+| rule | [`autonomous-execution`](../.agent-src/rules/autonomous-execution.md) | auto | Whether to ask or act on a workflow step — trivial-vs-blocking, autonomy opt-in, commit default; Hard Floor non-destructive-by-default |
+| rule | [`caveman-speak`](../.agent-src/rules/caveman-speak.md) | auto | When caveman.speak_scope != off — compress prose to caveman grammar with carve-outs for numbered options, Iron-Law, code, paths, error markers |
+| rule | [`cli-output-handling`](../.agent-src/rules/cli-output-handling.md) | auto | Running verbose CLI output — git, tests, linters, docker, build tools, artisan, npm, composer. Wrap with rtk; tail/grep fallback |
+| rule | [`command-suggestion-policy`](../.agent-src/rules/command-suggestion-policy.md) | auto | Prompt without /command matching an eligible slash command — surface matches as numbered options with as-is escape; never auto-executes |
+| rule | [`commit-conventions`](../.agent-src/rules/commit-conventions.md) | auto | Git commit format, branch naming, conventional commits, committing, pushing, creating PRs |
 | 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 | Configuring GitHub Copilot — 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 | Wiring DevContainers or GitHub Codespaces — devcontainer.json, images, VS Code features, port forwarding — route to the devcontainer skill |
+| rule | [`context-hygiene`](../.agent-src/rules/context-hygiene.md) | auto | Debugging, fixing errors, or long conversations — 3-failure stop rule, tool-loop detection, fresh-chat triggers |
+| rule | [`copilot-routing`](../.agent-src/rules/copilot-routing.md) | auto | Configuring GitHub Copilot — copilot-instructions.md, PR-review patterns, suggestion behavior — route to copilot-config |
+| rule | [`devcontainer-routing`](../.agent-src/rules/devcontainer-routing.md) | auto | Wiring DevContainers/Codespaces — devcontainer.json, 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 |
-| rule | [`domain-safety-disclaimer-consulting`](../.agent-src/rules/domain-safety-disclaimer-consulting.md) | auto | Drafting strategic recommendations, executive memos, board decks, or consulting deliverables — cite assumptions; flag low-confidence claims |
-| rule | [`domain-safety-disclaimer-financial`](../.agent-src/rules/domain-safety-disclaimer-financial.md) | auto | Drafting investment memos, valuation models, tax positions, or financial-advice-shaped content — require 'not financial advice' disclaimer |
-| rule | [`domain-safety-disclaimer-legal`](../.agent-src/rules/domain-safety-disclaimer-legal.md) | auto | Drafting legal briefs, contract redlines, ToS, privacy policies, or any legal-shaped content — require 'not legal advice' disclaimer in output |
-| rule | [`domain-safety-disclaimer-medical`](../.agent-src/rules/domain-safety-disclaimer-medical.md) | auto | Drafting health, wellness, medical, or therapeutic content — require 'not medical advice' disclaimer; refuse diagnostic or dosage outputs |
-| rule | [`domain-safety-export-redact`](../.agent-src/rules/domain-safety-export-redact.md) | auto | Generating CSV / Excel / API exports, partner data-shares, or analyst handoffs — redact direct identifiers; flag re-identification on quasi-IDs |
-| rule | [`domain-safety-logging-pii-floor`](../.agent-src/rules/domain-safety-logging-pii-floor.md) | auto | Writing logging code, structured logger config, or log lines — refuse to log raw PII; require redaction or a structured-field allowlist |
-| rule | [`domain-safety-pii-finance`](../.agent-src/rules/domain-safety-pii-finance.md) | auto | Drafting invoices, financial reports, AR/AP statements, or finance memos — redact counterparty PII and account/bank identifiers before output |
-| rule | [`domain-safety-pii-marketing`](../.agent-src/rules/domain-safety-pii-marketing.md) | auto | Drafting testimonials, case studies, social proof, or marketing emails referencing real customers — require consent; redact identifiers if absent |
-| rule | [`domain-safety-pii-recruiting`](../.agent-src/rules/domain-safety-pii-recruiting.md) | auto | Drafting candidate notes, interview scorecards, rejection emails, or hiring memos — redact candidate PII before output |
-| rule | [`domain-safety-pii-support`](../.agent-src/rules/domain-safety-pii-support.md) | auto | Generating support macros, ticket responses, or help-desk drafts — redact customer PII before output (names, emails, phones, account IDs, addresses) |
-| rule | [`domain-safety-retention-finance`](../.agent-src/rules/domain-safety-retention-finance.md) | auto | Finance data retention guidance — flag jurisdiction dependence, default to longest applicable retention, never delete records under audit hold |
-| rule | [`domain-safety-retention-support`](../.agent-src/rules/domain-safety-retention-support.md) | auto | Support / CRM data retention guidance — surface DSR-readiness, consent-window expiry, ticket-body retention vs. analytics aggregate retention |
-| rule | [`downstream-changes`](../.agent-src/rules/downstream-changes.md) | auto | After EVERY code edit, find ALL downstream changes needed to existing files, including callers, tests, imports, types, and documentation |
-| rule | [`e2e-testing`](../.agent-src/rules/e2e-testing.md) | auto | Playwright E2E tests — locators, assertions, Page Objects, fixtures, CI, and flaky test prevention |
-| rule | [`external-reference-deep-dive`](../.agent-src/rules/external-reference-deep-dive.md) | auto | User names an external repo, file, URL, or artifact as reference — fetch the actual tree and inspect, never summarize from README or metadata |
-| rule | [`fast-path-marker-visibility`](../.agent-src/rules/fast-path-marker-visibility.md) | auto | Low-impact council fast-path dispatch — host agent MUST surface the transparency marker verbatim in the reply opening; never swallow or paraphrase it. |
-| rule | [`framework-neutrality-in-generic-skills`](../.agent-src/rules/framework-neutrality-in-generic-skills.md) | auto | When editing a generic skill/rule/command — block single-stack mandates; use language-agnostic procedures with carve-out pointers. |
+| rule | [`docker-commands`](../.agent-src/rules/docker-commands.md) | auto | Running PHP inside Docker — artisan, composer, phpstan, rector, ecs, phpunit, tests, migrations, any CLI tool |
+| rule | [`domain-adoption-policy`](../.agent-src/rules/domain-adoption-policy.md) | auto | Adopting a new domain track (mobile, ML, blockchain, IoT) — gates import on demand, ownership, CI fit, Sunset compat BEFORE harvest |
+| rule | [`domain-safety-disclaimer`](../.agent-src/rules/domain-safety-disclaimer.md) | auto | Advisory content (legal, medical, financial, consulting) — require matching 'not X advice' disclaimer; refuse diagnosis/dosage outright |
+| rule | [`domain-safety-pii`](../.agent-src/rules/domain-safety-pii.md) | auto | Drafts, logs, exports touching real customer/candidate data — redact direct IDs, use placeholders, flag re-identification on quasi-IDs |
+| rule | [`domain-safety-retention`](../.agent-src/rules/domain-safety-retention.md) | auto | Data retention (finance, support/CRM) — name jurisdiction gap, default to longest floor, honor DSR/audit holds, never delete under inquiry |
+| rule | [`downstream-changes`](../.agent-src/rules/downstream-changes.md) | auto | After EVERY code edit, find ALL downstream changes — callers, tests, imports, types, documentation |
+| rule | [`external-reference-deep-dive`](../.agent-src/rules/external-reference-deep-dive.md) | auto | User names external repo/file/URL/artifact as reference — fetch the actual tree and inspect, never summarize from README or metadata |
+| rule | [`fast-path-marker-visibility`](../.agent-src/rules/fast-path-marker-visibility.md) | auto | Low-impact council fast-path dispatch — host MUST surface transparency marker verbatim in reply opening; never paraphrase |
+| rule | [`framework-neutrality-in-generic-skills`](../.agent-src/rules/framework-neutrality-in-generic-skills.md) | auto | Editing a generic skill/rule/command — block single-stack mandates; use language-agnostic procedures with carve-out pointers |
+| rule | [`git-history-discipline`](../.agent-src/rules/git-history-discipline.md) | auto | Git history ops — never rebase/squash/amend without explicit request; once pushed, rewrites must pair with immediate re-push same turn |
 | rule | [`guidelines`](../.agent-src/rules/guidelines.md) | manual | Writing or reviewing code — check relevant guideline before writing or reviewing code |
-| 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 | [`improve-before-implement`](../.agent-src/rules/improve-before-implement.md) | auto | Before implementing features or architectural changes — validate 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 |
 | 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 | [`low-impact-corpus-privacy-floor`](../.agent-src/rules/low-impact-corpus-privacy-floor.md) | auto | Writing, editing, or upstreaming entries in `agents/low-impact-decisions.md` — non-bypassable privacy floor for the learning corpus. |
-| rule | [`markdown-safe-codeblocks`](../.agent-src/rules/markdown-safe-codeblocks.md) | auto | Generating markdown output that contains code blocks — prevent broken nesting |
-| rule | [`media-governance-routing`](../.agent-src/rules/media-governance-routing.md) | auto | When generating AI video/image/voice — surface project-local media policies (likeness, style, public-figures, voice-cloning, disclosure) |
-| 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 |
-| rule | [`missing-tool-handling`](../.agent-src/rules/missing-tool-handling.md) | auto | When a CLI tool needed for the task is not installed — ask before working around it; do NOT install silently |
-| rule | [`model-recommendation`](../.agent-src/rules/model-recommendation.md) | auto | Starting a new task, switching task type, or invoking a command — detect complexity and recommend optimal model (Opus/Sonnet/GPT) before work |
-| rule | [`no-attribution-footers`](../.agent-src/rules/no-attribution-footers.md) | auto | Generating PR/issue/comment/commit-message bodies — forbids 'Generated with', 'Co-authored by', or 'Pull Request opened by' attribution footers |
+| rule | [`laravel-routing`](../.agent-src/rules/laravel-routing.md) | auto | Writing/reviewing Laravel code — controllers, Eloquent, Artisan, jobs, events, policies — route to laravel skill |
+| rule | [`laravel-translations`](../.agent-src/rules/laravel-translations.md) | auto | Laravel language files, translations, i18n, lang/de, lang/en, __() helper, localization |
+| rule | [`low-impact-corpus-privacy-floor`](../.agent-src/rules/low-impact-corpus-privacy-floor.md) | auto | Writing/editing/upstreaming entries in agents/decisions/low-impact-decisions.md — non-bypassable privacy floor for the learning corpus |
+| rule | [`markdown-safe-codeblocks`](../.agent-src/rules/markdown-safe-codeblocks.md) | auto | Generating markdown with code blocks — prevent broken nesting |
+| rule | [`media-governance-routing`](../.agent-src/rules/media-governance-routing.md) | auto | Generating AI video/image/voice — surface project-local media policies (likeness, style, public-figures, voice-cloning, disclosure) |
+| rule | [`minimal-safe-diff`](../.agent-src/rules/minimal-safe-diff.md) | auto | Writing or reviewing a diff — smallest change that solves the problem; no drive-by edits, opportunistic refactors, or reformatting |
+| rule | [`missing-tool-handling`](../.agent-src/rules/missing-tool-handling.md) | auto | CLI tool needed for the task is not installed — ask before working around it; do NOT install silently |
+| rule | [`model-recommendation`](../.agent-src/rules/model-recommendation.md) | auto | Starting a task, switching type, or invoking a command — detect complexity, recommend optimal model (Opus/Sonnet/GPT) |
+| rule | [`no-attribution-footers`](../.agent-src/rules/no-attribution-footers.md) | auto | Generating PR/issue/comment/commit bodies — forbids 'Generated with', 'Co-authored by', 'Pull Request opened by' attribution footers |
 | rule | [`no-cheap-questions`](../.agent-src/rules/no-cheap-questions.md) | always | No cheap questions — never ask what context answers, never offer Iron-Law-violating options, never stage no-trade-off choices; mode-independent (off / auto / on) |
-| rule | [`no-roadmap-references`](../.agent-src/rules/no-roadmap-references.md) | auto | Linking transient files (agents/roadmaps/, agents/council-*/) from a stable artifact — both layers expire; promote findings |
-| rule | [`no-unsolicited-rebase`](../.agent-src/rules/no-unsolicited-rebase.md) | auto | Working with git history — never rewrite, rebase, squash, fixup, or amend without explicit user request; shape is the user's call, not tidiness |
+| rule | [`no-roadmap-references`](../.agent-src/rules/no-roadmap-references.md) | auto | Linking transient files (agents/roadmaps/, agents/runtime/council/*/) from a stable artifact — both layers expire; promote findings |
 | rule | [`non-destructive-by-default`](../.agent-src/rules/non-destructive-by-default.md) | always | Agent is never destructive — Hard Floor always asks for prod-trunk merges, deploys, pushes, prod data/infra, bulk deletions, and bulk-deletion/infra commits; no autonomy or roadmap bypass |
-| rule | [`onboarding-gate`](../.agent-src/rules/onboarding-gate.md) | auto | First turn of a conversation on a project — check onboarding.onboarded in .agent-settings.yml; when false, prompt to run /onboard before any request |
+| rule | [`onboarding-gate`](../.agent-src/rules/onboarding-gate.md) | auto | First turn — if onboarding.onboarded is false in .agent-settings.yml, instruct dev to run `agent-config setup` before any request |
 | rule | [`package-ci-checks`](../.agent-src/rules/package-ci-checks.md) | manual | Before pushing to remote or creating a PR in the agent-config package — run all CI checks locally first |
-| rule | [`persona-governance`](../.agent-src/rules/persona-governance.md) | auto | When creating, editing, or proposing personas — enforce per-domain cap (≤ 2 specialists), ≥ 1 skill citation, and the deprecation path |
-| rule | [`php-coding`](../.agent-src/rules/php-coding.md) | auto | Writing or reviewing PHP code — strict types, naming, comparisons, early returns, Eloquent conventions |
-| rule | [`post-push-rewrite-discipline`](../.agent-src/rules/post-push-rewrite-discipline.md) | auto | Git history after a push — squash/amend/rebase of pushed commits must pair with immediate re-push in same turn; stop on divergent state |
-| rule | [`preservation-guard`](../.agent-src/rules/preservation-guard.md) | auto | When merging, refactoring, compressing, or restructuring skills, rules, commands, or guidelines — prevent quality loss |
-| rule | [`provider-lifecycle-discipline`](../.agent-src/rules/provider-lifecycle-discipline.md) | auto | When editing an AI video/image/audio adapter — declare lifecycle tier (experimental \| stable \| deprecated \| community); never default to non-stable |
-| rule | [`reviewer-awareness`](../.agent-src/rules/reviewer-awareness.md) | auto | When suggesting reviewers or flagging risk hotspots — anchor in paths/risk + ownership-map + bug-patterns; medium/high needs primary + secondary |
-| rule | [`roadmap-ci-steps-policy`](../.agent-src/rules/roadmap-ci-steps-policy.md) | auto | When authoring or executing roadmaps — forbid task ci / make test / npm run check steps when quality.local_auto_run is false; skip inline at execution |
-| rule | [`roadmap-progress-sync`](../.agent-src/rules/roadmap-progress-sync.md) | auto | Any roadmap touch (file move, checkbox flip, phase change) regens dashboard same response; archive at 0 open. Autonomous runs flip checkboxes inline |
-| rule | [`role-mode-adherence`](../.agent-src/rules/role-mode-adherence.md) | auto | When roles.active_role is set in .agent-settings.yml — closing outputs must match the mode's contract and emit the structured mode marker |
-| rule | [`rule-type-governance`](../.agent-src/rules/rule-type-governance.md) | auto | Creating or editing rules, or auditing rule types — decides when a rule should be always vs auto |
-| rule | [`runtime-safety`](../.agent-src/rules/runtime-safety.md) | auto | When a skill declares execution metadata — enforce safety constraints for assisted and automated execution types |
+| rule | [`persona-governance`](../.agent-src/rules/persona-governance.md) | auto | Creating/editing/proposing personas — enforce per-domain cap (≤ 2 specialists), ≥ 1 skill citation, deprecation path |
+| rule | [`php-coding`](../.agent-src/rules/php-coding.md) | auto | Writing/reviewing PHP — strict types, naming, comparisons, early returns, Eloquent conventions |
+| rule | [`preservation-guard`](../.agent-src/rules/preservation-guard.md) | auto | Merging/refactoring/compressing skills, rules, commands, or guidelines — prevent quality loss |
+| rule | [`provider-lifecycle-discipline`](../.agent-src/rules/provider-lifecycle-discipline.md) | auto | Editing an AI video/image/audio adapter — declare lifecycle tier (experimental \| stable \| deprecated \| community); never default to non-stable |
+| rule | [`reviewer-awareness`](../.agent-src/rules/reviewer-awareness.md) | auto | Suggesting reviewers or flagging risk hotspots — anchor in paths/risk + ownership-map + bug-patterns; medium/high needs primary + secondary |
+| rule | [`roadmap-ci-steps-policy`](../.agent-src/rules/roadmap-ci-steps-policy.md) | auto | Authoring or executing roadmaps — forbid task ci / make test / npm run check steps when quality.local_auto_run is false; skip inline |
+| rule | [`roadmap-progress-sync`](../.agent-src/rules/roadmap-progress-sync.md) | auto | Any roadmap touch (file move, checkbox flip, phase change) regens dashboard same response; archive at 0 open |
+| rule | [`role-mode-adherence`](../.agent-src/rules/role-mode-adherence.md) | auto | When roles.active_role is set — closing outputs must match mode contract and emit structured mode marker |
+| rule | [`rule-type-governance`](../.agent-src/rules/rule-type-governance.md) | auto | Creating/editing rules, or auditing rule types — decides when a rule should be always vs auto |
+| rule | [`runtime-safety`](../.agent-src/rules/runtime-safety.md) | auto | Skill declares execution metadata — enforce safety constraints for assisted/automated execution types |
 | rule | [`scope-control`](../.agent-src/rules/scope-control.md) | always | Scope control — no unsolicited architectural changes, refactors, or library replacements |
-| rule | [`security-sensitive-stop`](../.agent-src/rules/security-sensitive-stop.md) | auto | Security-sensitive paths — auth, billing, tenant boundaries, secrets, uploads, integrations, webhooks, public endpoints — threat-model BEFORE editing |
+| rule | [`security-sensitive-stop`](../.agent-src/rules/security-sensitive-stop.md) | auto | Security-sensitive paths — auth, billing, tenants, secrets, uploads, webhooks, public endpoints — threat-model BEFORE editing |
 | rule | [`size-enforcement`](../.agent-src/rules/size-enforcement.md) | manual | Creating or editing rules, skills, commands, guidelines, AGENTS.md, or copilot-instructions.md — enforce size and scope limits |
-| 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 | Writing or reviewing Symfony code — DI, 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 | [`skill-improvement-trigger`](../.agent-src/rules/skill-improvement-trigger.md) | auto | After 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/reviewing skills — minimum quality standard; every skill executable, validated, self-contained |
+| rule | [`slash-command-routing-policy`](../.agent-src/rules/slash-command-routing-policy.md) | auto | User types a slash command like /create-pr, /commit, or pastes command file content |
+| rule | [`symfony-routing`](../.agent-src/rules/symfony-routing.md) | auto | Writing/reviewing Symfony — DI, bundles, Doctrine, Messenger, Security voters, console commands — route to symfony-workflow |
+| rule | [`think-before-action`](../.agent-src/rules/think-before-action.md) | auto | Before coding/modifying/debugging — analyze first, verify with real tools, never guess or trial-and-error |
+| rule | [`token-efficiency`](../.agent-src/rules/token-efficiency.md) | auto | 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 |
-| rule | [`tool-safety`](../.agent-src/rules/tool-safety.md) | auto | When a skill uses external tools — enforce allowlist, deny-by-default, and no hidden credential patterns |
-| rule | [`ui-audit-gate`](../.agent-src/rules/ui-audit-gate.md) | auto | Writing or editing UI — components, screens, partials, layouts, design tokens — require existing-ui-audit findings before non-trivial UI change |
-| rule | [`upstream-proposal`](../.agent-src/rules/upstream-proposal.md) | auto | After creating or significantly improving a skill, rule, guideline, or command — ask if it should be contributed upstream to the shared package |
-| 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 | [`tool-safety`](../.agent-src/rules/tool-safety.md) | auto | Skill uses external tools — enforce allowlist, deny-by-default, no hidden credential patterns |
+| rule | [`ui-audit-gate`](../.agent-src/rules/ui-audit-gate.md) | auto | Writing/editing UI — components, screens, layouts, design tokens — require existing-ui-audit findings first |
+| rule | [`upstream-proposal`](../.agent-src/rules/upstream-proposal.md) | auto | After creating or improving a skill/rule/guideline/command — ask if it should be contributed upstream to the shared package |
+| rule | [`user-interaction`](../.agent-src/rules/user-interaction.md) | auto | Asking a question, presenting options, summarizing progress — numbered-options Iron Law, single-recommendation rule, progress indicators |
 | rule | [`user-interrupt-priority`](../.agent-src/rules/user-interrupt-priority.md) | always | User interrupts override the current task — STOP, complete new task in full, then ASK before resuming; never silently return to prior work |
 | rule | [`verify-before-complete`](../.agent-src/rules/verify-before-complete.md) | always | Verify before completion — run tests and quality tools before claiming done |
 
-## Commands (129)
+## Commands (128)
 
 | kind | name | cluster | description |
 |---|---|---|---|
@@ -377,9 +366,9 @@ are excluded.
 | command | [`fix:refs`](../.agent-src/commands/fix/refs.md) | cluster: fix | Find and fix broken cross-references in .augment/ and agents/ files |
 | command | [`fix:seeder`](../.agent-src/commands/fix/seeder.md) | cluster: fix | Scan seeder data files for broken foreign key references — find constants used without getReference() and fix them |
 | command | [`fix`](../.agent-src/commands/fix.md) | cluster: fix | Fix orchestrator — routes to ci, references, portability, seeder, pr-comments, pr-bot-comments, pr-developer-comments |
-| command | [`ghostwriter:delete`](../.agent-src/commands/ghostwriter/delete.md) | cluster: ghostwriter | Hard-delete a ghostwriter profile at agents/ghostwriter/<slug>.md after a two-step confirmation. No backup, no soft delete — the file is gone after acceptance. |
-| command | [`ghostwriter:fetch`](../.agent-src/commands/ghostwriter/fetch.md) | cluster: ghostwriter | Build or refresh a public-figure voice profile at agents/ghostwriter/<slug>.md from a URL or bare name; runs the public-figure attestation gate; delegates web-fetch / web-search to the host agent. |
-| command | [`ghostwriter:list`](../.agent-src/commands/ghostwriter/list.md) | cluster: ghostwriter | List captured ghostwriter profiles under agents/ghostwriter/ as a numbered table with confidence, last-fetched, and stale-warning flags. Read-only. |
+| command | [`ghostwriter:delete`](../.agent-src/commands/ghostwriter/delete.md) | cluster: ghostwriter | Hard-delete a ghostwriter profile at agents/reference/ghostwriter/<slug>.md after a two-step confirmation. No backup, no soft delete — the file is gone after acceptance. |
+| command | [`ghostwriter:fetch`](../.agent-src/commands/ghostwriter/fetch.md) | cluster: ghostwriter | Build or refresh a public-figure voice profile under agents/reference/ghostwriter/ from a URL or bare name; runs the public-figure attestation gate; delegates web-fetch/web-search to host. |
+| command | [`ghostwriter:list`](../.agent-src/commands/ghostwriter/list.md) | cluster: ghostwriter | List captured ghostwriter profiles under agents/reference/ghostwriter/ as a numbered table with confidence, last-fetched, and stale-warning flags. Read-only. |
 | command | [`ghostwriter:show`](../.agent-src/commands/ghostwriter/show.md) | cluster: ghostwriter | Render a single ghostwriter profile in full — identity, style fingerprint, voice samples, taboos, source URLs. Read-only. |
 | command | [`ghostwriter:write`](../.agent-src/commands/ghostwriter/write.md) | cluster: ghostwriter | Draft a markdown post in the voice of a captured public-figure ghostwriter profile; appends the mandatory non-removable disclosure footer. |
 | command | [`ghostwriter`](../.agent-src/commands/ghostwriter.md) | cluster: ghostwriter | Ghostwriter cluster — fetch, write, list, show, and delete public-figure voice profiles (the third voice primitive alongside personas/ and .agent-user.md). |
@@ -401,7 +390,6 @@ are excluded.
 | command | [`module:create`](../.agent-src/commands/module/create.md) | cluster: module | Create a new module from .module-template with interactive setup |
 | command | [`module:explore`](../.agent-src/commands/module/explore.md) | cluster: module | Explore a module — load its structure, docs, and context into the current conversation |
 | command | [`module`](../.agent-src/commands/module.md) | cluster: module | Module orchestrator — routes to create, explore |
-| command | [`onboard`](../.agent-src/commands/onboard.md) |  | First-run setup for a developer on this project — captures name, IDE, bot-icon preference, rtk, cost_profile, and learning opt-out, then sets onboarding.onboarded=true |
 | command | [`optimize:agents-dir`](../.agent-src/commands/optimize/agents-dir.md) | cluster: optimize | Manage the agents/ directory — scaffold, folder-audit, fix. Single command with three modes (--scaffold / --audit / --fix); default = interactive wizard. |
 | command | [`optimize:augmentignore`](../.agent-src/commands/optimize/augmentignore.md) | cluster: optimize | Creates or updates .augmentignore based on the project's actual tech stack, large files, generated artifacts, and irrelevant agent skills/rules. |
 | command | [`optimize:rtk`](../.agent-src/commands/optimize/rtk.md) | cluster: optimize | Create or optimize project-local rtk filters based on the actual toolchain |

package/docs/contracts/STABILITY.md

@@ -60,7 +60,7 @@ frontmatter and:
 
 - **fails CI** when README / AGENTS.md / `docs/architecture.md` links to
   a contract marked `experimental`, to a missing target, or into
-  `agents/contexts/` (internal surface).
+  `agents/settings/contexts/` (internal surface).
 - **warns** (non-fatal in default mode; fatal under `--strict`) when a
   public-surface link to a `beta` contract has no `(beta)` marker in
   the surrounding text.

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

@@ -6,7 +6,7 @@ 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. <!-- council-ref-allowed: ADR decision trace -->
+> **Context:** v2 council finding C1 (file [01-bus-factor-and-consensus.md](../../agents/runtime/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. <!-- council-ref-allowed: ADR decision trace -->
 > **Roadmap:** Closes Phase 5.2 of the v2 feedback follow-up roadmap
 > (see `agents/roadmaps/`).
 
@@ -14,7 +14,7 @@ keep-beta-until: 2026-08-12
 
 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:
+1. **Tier A — Automated ontology lint (every PR).** `scripts/skill_collision_clusters.py` produces `agents/runtime/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.
@@ -52,8 +52,8 @@ The two-tier choice is the convener-skeptic synthesis: **(b) is the always-on ga
 
 ## 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] `scripts/skill_collision_clusters.py` exists and emits `agents/runtime/reports/skill-collision-clusters.json`
+- [x] `scripts/score_skill_selection.py` exists and emits `agents/runtime/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`)
 
@@ -61,7 +61,7 @@ The final acceptance gate (lint going from warn-only to fail-the-build) is defer
 
 ## 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) <!-- council-ref-allowed: ADR decision trace -->
+- Origin: [`agents/runtime/council/sessions/2026-05-14-v2-analysis/feedback/01-bus-factor-and-consensus.md`](../../agents/runtime/council/sessions/2026-05-14-v2-analysis/feedback/01-bus-factor-and-consensus.md) <!-- council-ref-allowed: ADR decision trace -->
 - 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

package/docs/contracts/adr-chat-history-split.md

@@ -6,7 +6,7 @@ keep-beta-until: 2026-08-12
 # ADR — Chat-history rule split
 
 > **Status:** Superseded · 2026-05-04 · by
-> [`agents/contexts/chat-history-platform-hooks.md`](../../agents/contexts/chat-history-platform-hooks.md).
+> [`agents/settings/contexts/chat-history-platform-hooks.md`](../../agents/settings/contexts/chat-history-platform-hooks.md).
 > The cooperative three-rule split this ADR locked in
 > (`chat-history-ownership` / `-cadence` / `-visibility`) has been
 > reduced to a hook-only structural artifact. The three always-rules,

package/docs/contracts/adr-implement-ticket-runtime.md

@@ -108,7 +108,7 @@ Python is 3 files with shared types.
   handlers onto the dispatcher shape spiked here.
 - `implement-ticket-flow.md` will have its `Runtime: TBD` line replaced
   with `Runtime: Python 3.10+` when Phase 1 lands.
-- Metrics contract (Q38, JSON lines under `agents/logs/implement-ticket/`)
+- Metrics contract (Q38, JSON lines under `agents/runtime/logs/implement-ticket/`)
   is already demonstrated by both prototypes.
 
 ## Follow-ups (not part of this ADR)

package/docs/contracts/adr-install-user-type-axis.md

@@ -83,7 +83,7 @@ Three options were considered:
   [`scripts/audit_user_type_axis.py`](../../scripts/audit_user_type_axis.py)).
   Initial sweep at Phase 4 close: 7 declared / 7 used / 0 orphans / 0
   unused — coverage is clean, no rename or backfill needed. Report:
-  [`agents/reports/user-type-axis-audit.md`](../../agents/reports/user-type-axis-audit.md).
+  [`agents/runtime/reports/user-type-axis-audit.md`](../../agents/runtime/reports/user-type-axis-audit.md).
 - Adding an 8th value is non-trivial by design — it requires a YAML, a
   schema-compatible frontmatter rollout, and a roadmap entry. The
   friction is the feature: a sprawling axis defeats the purpose of

package/docs/contracts/adr-mcp-runtime.md

@@ -68,7 +68,7 @@ hardcoded module-level tuple in
 | Tool | Mode | Source |
 |---|---|---|
 | `lint_skills` | read-only | wraps `scripts.skill_linter.lint_file` |
-| `chat_history_append` | path-scoped write | wraps `scripts.chat_history.append`; writes restricted to `agents/.agent-chat-history` or `.agent-chat-history` under the consumer root |
+| `chat_history_append` | path-scoped write | wraps `scripts.chat_history.append`; writes restricted to `agents/runtime/.agent-chat-history` (current default), `agents/.agent-chat-history`, or `.agent-chat-history` under the consumer root |
 
 No `push`, `merge`, `commit`, or prod-write surface is exposed. The
 unimplemented-tool envelope from
@@ -105,7 +105,7 @@ Writing the global Claude Desktop config from the npx dispatcher without
 an operator pasting JSON is **not** part of this contract — Claude Desktop
 restarts and config-merge semantics make silent rewrites a footgun. The
 copy-paste path stays the canonical install shape until non-dev recruit
-evidence under `agents/eval-findings/` demonstrates the manual step is the
+evidence under `agents/evidence/eval-findings/` demonstrates the manual step is the
 actual adoption blocker.
 
 ## Consequences

package/docs/contracts/agent-user-schema.md

@@ -26,7 +26,9 @@ identity:
   name: "Mathias"          # required — full name or how the user wants to be addressed
   nickname: "Matze"        # optional — preferred shorthand (used by default in chat)
 language: "de"             # required — BCP-47-ish primary language ("de", "en", "fr", ...)
-role: "founder/engineer"   # required — short free-form role label
+role:                      # required — unordered list of role labels; ≥ 1 entry
+  - founder
+  - engineer
 style:
   formality: "informal"    # informal | formal
   pace: "pragmatic"        # pragmatic | thorough | rapid
@@ -36,6 +38,13 @@ last_updated: "2026-05-15" # YYYY-MM-DD — bumped on every accepted change
 ---
 ```
 
+`role` is an **unordered** YAML block-style list. Order carries no meaning
+(no "primary" role). The seeded enum mirrors `SEED_PROFILE_IDS` in
+[`scripts/config/profiles.py`](../../scripts/config/profiles.py):
+`founder`, `developer`, `content_creator`, `agency`, `finance`, `ops`.
+Free-form additions are accepted (forward-compatibility) — closed
+validation lives in the wizard / settings GUI, not in the loader.
+
 After the frontmatter, the body is a single freeform **`# Notes`**
 section. Hard cap: **100 lines** total file size (including
 frontmatter, body, and the Notes section). The 100-line cap is
@@ -49,7 +58,7 @@ enforced by `/agents user accept` and `/agents user update`.
 | `identity.name` | yes | Default address form. |
 | `identity.nickname` | no | Preferred shorthand — agent uses this by default in chat replies when set. |
 | `language` | yes | Primary language; the agent mirrors per [`language-and-tone`](../../.agent-src/rules/language-and-tone.md). |
-| `role` | yes | Short free-form label — drives reviewer voice selection and persona pairing. |
+| `role` | yes | Unordered list of role labels (≥ 1). Drives reviewer-voice selection and persona pairing. Seeded enum mirrors `SEED_PROFILE_IDS`; additional free-form entries accepted. |
 | `style.formality` | yes | `informal` (Du / first-name) or `formal` (Sie / full name). |
 | `style.pace` | yes | `pragmatic` (default), `thorough` (more verification), or `rapid` (shorter replies). |
 | `voice_sample` | yes | One representative paste — anchors mirror-back and tone calibration. |

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

@@ -3,16 +3,16 @@ stability: beta
 keep-beta-until: 2026-08-12
 ---
 
-# AI-Council Config (`agents/.ai-council.yml`)
+# AI-Council Config (`agents/settings/.ai-council.yml`)
 
 **Purpose.** Lock the schema, validation, and precedence rules for the
 centralized council config file. Every phase of the AI-Council
 consolidation work reads from this file; the contract here is the
 boundary that prevents drift across the loader, the CLI, the
-orchestrator, and the `agents/.ai-council.yml` file itself.
+orchestrator, and the `agents/settings/.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`
+`scripts/ai_council/orchestrator.py`, and the `agents/settings/.ai-council.yml`
 starter. Also reviewers checking that new providers / advisors / debate
 features keep the schema intact.
 
@@ -21,7 +21,7 @@ a revision entry in the consuming roadmap.
 
 ## File location
 
-The single source of truth is **`agents/.ai-council.yml`** at the
+The single source of truth is **`agents/settings/.ai-council.yml`** at the
 project root. The legacy `ai_council.*` block under `.agent-settings.yml`
 is removed by Phase 0 Step 5 and replaced by a one-line breadcrumb
 pointing at this contract.
@@ -131,7 +131,7 @@ Implications:
 
 ### Persistent events log (step-8 D3)
 
-The orchestrator appends one JSON line to `agents/council-events.log`
+The orchestrator appends one JSON line to `agents/runtime/council/events.log`
 on every necessity-gate decision (`proceed` / `skip_necessity`) and on
 every `cli_call_budget` block (`block_quota`). The log is gitignored
 by default — it is a local-only audit trail, never part of the
@@ -155,7 +155,7 @@ Schema v1:
 - `action` ∈ `proceed | skip_necessity | block_quota`.
 - `original_ask_hash` is `sha256(original_ask)[:12]`. The raw prompt
   is **never** written — privacy floor per
-  [`agents/low-impact-decisions.md`](../../agents/low-impact-decisions.md).
+  [`agents/decisions/low-impact-decisions.md`](../../agents/decisions/low-impact-decisions.md).
 - Diagnostic fields outside the reserved set (`category`, `mode`,
   `cli_calls_used`, …) pass through verbatim. Consumers MUST treat
   unknown keys as forward-compatible.
@@ -514,20 +514,20 @@ when the gate flags the response.
 
 ### Low-impact corpus build pipeline (step-10)
 
-[`agents/low-impact-decisions.md`](../../agents/low-impact-decisions.md)
+[`agents/decisions/low-impact-decisions.md`](../../agents/decisions/low-impact-decisions.md)
 remains the **human-editable source of truth** — Validated, Probation,
 and Anti-Example phrases stay in Markdown so PR-reviewers diff prose,
 not YAML. A build step compiles it into a generated YAML lockfile
-[`agents/low-impact-decisions.lock.yaml`](../../agents/low-impact-decisions.lock.yaml)
+[`agents/decisions/low-impact-decisions.lock.yaml`](../../agents/decisions/low-impact-decisions.lock.yaml)
 that is the **runtime source of truth**: the necessity classifier and
 the solo-dispatch fuzzy matcher load phrases from the lockfile, with
 Markdown parsing reserved as fallback.
 
 | Component | File | Role |
 |---|---|---|
-| Source | `agents/low-impact-decisions.md` | Hand-edited Markdown. Strict parser (step-9 P4) catches drift. |
+| Source | `agents/decisions/low-impact-decisions.md` | Hand-edited Markdown. Strict parser (step-9 P4) catches drift. |
 | Build tool | `scripts/ai_council/compile_corpus.py` | `parse_corpus_strict()` → schema-v1 YAML. Deterministic output. |
-| Lockfile | `agents/low-impact-decisions.lock.yaml` | Generated, **committed**. Schema `{schema_version: 1, provenance: {…}, validated, probation, anti_examples}`. |
+| Lockfile | `agents/decisions/low-impact-decisions.lock.yaml` | Generated, **committed**. Schema `{schema_version: 1, provenance: {…}, validated, probation, anti_examples}`. |
 | Runtime loader | `low_impact_corpus.load_corpus_lock()` + lenient `load_*` shims | YAML preferred; Markdown fallback when the lockfile is missing or schema-mismatched. |
 | CI gate | `task check-corpus` (used by `task consistency`) | Fails on drift between source and lockfile. |
 
@@ -599,13 +599,13 @@ as comments and the loader enforces them.
   `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
+- **Session retention.** `agents/runtime/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)
+  Prices come from [`agents/runtime/.agent-prices.md`](../../agents/runtime/.agent-prices.md)
   (gitignored, refreshed weekly by `python3 scripts/update_prices.py`;
   bootstrapped from `scripts/ai_council/_default_prices.py` on first run).
 
@@ -652,7 +652,7 @@ error) when any of these hold:
   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
+- New file `agents/settings/.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/audit-log-v1.md

@@ -28,7 +28,7 @@ Last refreshed: 2026-05-11.
 ## File location
 
 ```
-agents/state/audit/<YYYY-MM>.jsonl
+agents/runtime/state/audit/<YYYY-MM>.jsonl
 ```
 
 One file per UTC month. Files are append-only — `merge=union` via
@@ -95,7 +95,7 @@ Lines MUST NOT contain:
 - Memory entry bodies, ids, or content. Only **counts** travel here —
   ids stay in `decision-trace-*.json` per [`memory-visibility-v1.md`](memory-visibility-v1.md).
 - Secrets, tokens, environment values, file contents.
-- Paths outside the package's `agents/state/` and `tests/` allowlist.
+- Paths outside the package's `agents/runtime/state/` and `tests/` allowlist.
 
 The floor is enforced by
 `tests/contracts/test_audit_log_redaction.py` — any new producer-side

package/docs/contracts/command-clusters.md

@@ -33,7 +33,7 @@ column 1 of this table.
 | `feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` · `dev` | `feature-explore` · `feature-plan` · `feature-refactor` · `feature-roadmap` · `feature-dev` |
 | `chat-history` | 2 | `show` · `import` · `learn` | `chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only` (auto-adopt + structural hooks); `import` (verbatim cross-session render) and `learn` (project-improving learning extraction) added in the v4 stateless schema |
 | `agents` | 2 | `init` · `optimize` · `audit` · `user` | AGENTS.md file family (high-frequency) — repurposed 2026-05-09: `init` (was `/copilot-agents init`) · `optimize` (merger of `/optimize agents-md` + `/copilot-agents optimize`) · `audit` (was `/optimize agents`, collapses old `audit` + `check` verbs); legacy folder ops (`prepare` / `cleanup` / folder-`audit`) moved to `/optimize agents-dir`; `user` sub-cluster added 2026-05-15 — manages the project-root `.agent-user.md` persona file (sub-sub-commands: `init` · `show` · `review` · `accept` · `update`) per [`agent-user-schema`](agent-user-schema.md) |
-| `memory` | 2 | `add` · `load` · `promote` · `propose` · `mine-session` · `learn-low-impact` | `memory-add` · `memory-full` · `memory-promote` · `propose-memory`; `mine-session` added 2026-05-10 — manual transcript-mining sub-command from `road-to-dream-skill-adoption.md`, opt-in via `--confirm-transcript-access` per invocation; `learn-low-impact` added 2026-05-15 — upstreams `## Validated` entries from `agents/low-impact-decisions.md` to the package seed via a DRAFT PR (re-runs the privacy-floor redactor as a second gate per `low-impact-corpus-privacy-floor`) |
+| `memory` | 2 | `add` · `load` · `promote` · `propose` · `mine-session` · `learn-low-impact` | `memory-add` · `memory-full` · `memory-promote` · `propose-memory`; `mine-session` added 2026-05-10 — manual transcript-mining sub-command from `road-to-dream-skill-adoption.md`, opt-in via `--confirm-transcript-access` per invocation; `learn-low-impact` added 2026-05-15 — upstreams `## Validated` entries from `agents/decisions/low-impact-decisions.md` to the package seed via a DRAFT PR (re-runs the privacy-floor redactor as a second gate per `low-impact-corpus-privacy-floor`) |
 | `roadmap` | 2 | `create` · `ai-council` · `process-step` · `process-phase` · `process-full` | `roadmap-create` · `roadmap-execute` (replaced — autonomous, no per-step gate; `process-phase` is the default execution scope); `ai-council` added 2026-05-07 — wraps `/council default` with `--input-mode roadmap --depth deep` |
 | `module` | 2 | `create` · `explore` | `module-create` · `module-explore` |
 | `tests` | 2 | `create` · `execute` | `tests-create` · `tests-execute` |
@@ -47,7 +47,7 @@ column 1 of this table.
 | `research` | 2 | `deep` · `report` | preliminary-research scaffolder ported from `Weizhena/Deep-Research-skills` (cluster head emits `outline.yaml` + `fields.yaml` against the `research-schema` contract). `:deep` populates per-item JSON in batches with native web-search + JSON-Schema self-validation (no Python runtime); `:report` renders `report.md` directly + optionally emits a `jq` template for deterministic regeneration. `add-items` / `add-fields` intentionally **not** ported — re-run `/research <topic>` to extend the field framework. |
 | `orchestrate` | — | _(none yet — cluster head only)_ | new — runtime executor for YAML pipelines under `.agent-config/orchestrations/` per the [`orchestration-dsl-v1`](orchestration-dsl-v1.md) contract; chains personas / skills / commands / sub-agents deterministically. Single cluster head; sub-commands deferred until a second verb is needed. |
 | `sync-gitignore` | — | `fix` | new sub-command 2026-05-11 — cluster head retains the existing append-only sync as its default flow; `:fix` adds `--cleanup-legacy` semantics, scrubbing pre-`/agents/` runtime patterns wherever they appear in the consumer's `.gitignore` (inside or outside the managed block) and re-syncing the canonical entries. |
-| `ghostwriter` | — | `fetch` · `write` · `list` · `show` · `delete` | new cluster 2026-05-15 — third voice primitive for AI-assisted writing in the public voice of a public figure. Hybrid storage: real-person profiles live consumer-side under `agents/ghostwriter/<slug>.md` (gitignored by default); package source ships only `fictional: true` fixtures. Zero network code in the package — `:fetch` delegates web-fetch / web-search to the host agent. Mandatory disclosure footer on every `:write` output (no opt-out). Schema: [`ghostwriter-schema`](ghostwriter-schema.md). |
+| `ghostwriter` | — | `fetch` · `write` · `list` · `show` · `delete` | new cluster 2026-05-15 — third voice primitive for AI-assisted writing in the public voice of a public figure. Hybrid storage: real-person profiles live consumer-side under `agents/reference/ghostwriter/<slug>.md` (gitignored by default); package source ships only `fictional: true` fixtures. Zero network code in the package — `:fetch` delegates web-fetch / web-search to the host agent. Mandatory disclosure footer on every `:write` output (no opt-out). Schema: [`ghostwriter-schema`](ghostwriter-schema.md). |
 | `post-as` | — | `me` · `ghostwriter` | new cluster 2026-05-15 — consumer-facing write entry points. `:me` reads `.agent-user.md.voice_sample` and drafts in the maintainer's own voice (no disclosure footer — the user is the author); `:ghostwriter` is a thin alias for `/ghostwriter:write` with the mandatory disclosure footer. Both share the procedural [`write-engine`](write-engine.md) contract — style source and footer are the only axes of variation. |
 | `video` | — | `from-script` · `scene` · `storyboard` · `stitch` | new cluster 2026-05-17 — AI video generation pipeline. Cluster head orchestrates the full flow; `:scene` runs a single scene end-to-end (script → blueprint → still → motion → clip); `:storyboard` expands a script into per-scene blueprints + reference stills with character-lock JSON; `:from-script` walks a multi-scene script through storyboard + per-scene generation; `:stitch` concatenates scene clips with `ffmpeg` against a scene manifest. Provider-agnostic via the adapter contract under `scripts/ai-video/lib/adapter-contract.md`; cost-gated with mandatory `AIV_DRYRUN=true` default and explicit confirmation before live provider calls. |
 

package/docs/contracts/compression-default-kill-criterion.md

@@ -7,8 +7,8 @@ keep-beta-until: 2026-08-14
 
 > **Status:** v1-measured · criterion not met · default stays `off` · **Owner:** `step-16-caveman-substance.md`
 > Phase 1 closeout · **Sources:** [`bench/reports/caveman-v1.md`](../../bench/reports/caveman-v1.md) ·
-> [`council-synthesis.md` § 7](../../agents/council-sessions/audit-2026-05-14-north-star/council-synthesis.md) <!-- council-ref-allowed: ADR decision trace for v1 kill-criterion verdict --> ·
-> [`caveman-v1-kc-verdict.json`](../../agents/council-responses/caveman-v1-kc-verdict.json) <!-- council-ref-allowed: ADR decision trace for v1 kill-criterion verdict -->
+> [`council-synthesis.md` § 7](../../agents/evidence/audits/2026-05-14-north-star/council-synthesis.md) <!-- council-ref-allowed: ADR decision trace for v1 kill-criterion verdict --> ·
+> [`caveman-v1-kc-verdict.json`](../../agents/runtime/council/responses/caveman-v1-kc-verdict.json) <!-- council-ref-allowed: ADR decision trace for v1 kill-criterion verdict -->
 
 ## Rule
 
@@ -67,7 +67,7 @@ negative (caveman-04 path-list −108 %, caveman-06 mode-marker −123 %).
 
 ### Council split (recorded, not decisive)
 
-Council run [`caveman-v1-kc-verdict.json`](../../agents/council-responses/caveman-v1-kc-verdict.json) <!-- council-ref-allowed: ADR decision trace for v1 kill-criterion verdict -->
+Council run [`caveman-v1-kc-verdict.json`](../../agents/runtime/council/responses/caveman-v1-kc-verdict.json) <!-- council-ref-allowed: ADR decision trace for v1 kill-criterion verdict -->
 (2 members · 1 round · $0.0514 actual) split:
 
 - **`claude-sonnet-4-5`** → Decision A.1 (deprecate now) + Decision B.3