@event4u/agent-config 1.20.0 → 1.21.0

package/.agent-src/rules/token-efficiency.md

@@ -4,6 +4,12 @@ tier: "2a"
 description: "When running CLI tools, fetching logs, or producing replies — redirect verbose output, minimize tool calls, keep replies concise"
 alwaysApply: false
 source: package
+load_context:
+  - ../contexts/communication/rules-auto/token-efficiency-mechanics.md
+triggers:
+  - intent: "verbose CLI output"
+  - intent: "fetching logs"
+  - keyword: "minimize tool calls"
 ---
 
 # Token Efficiency
@@ -19,82 +25,12 @@ NEVER call the same tool more than 2 times in a row with similar parameters.
 If you catch yourself repeating a tool call — STOP, rethink, try a different approach, or ask the user.
 ```
 
-### Anti-loop: Extended Reasoning
-
-Do NOT use extended reasoning / chain-of-thought tools for simple tasks like viewing files,
-running commands, or making straightforward edits. They are ONLY for genuinely complex
-multi-step reasoning. If you find yourself calling such tools more than once per task —
-you are looping. Stop immediately and act directly instead.
-
-### Anti-loop: "CRITICAL INSTRUCTION" and self-prompting
-
-If you find yourself generating text that starts with "CRITICAL INSTRUCTION", "I need to",
-"Let me think", "Related tools:", or similar self-directed reasoning inside a tool call
-or as a preamble before acting — **you are in a loop**. This happens after connection errors
-or when the user says something like "continue" / "mach weiter".
-
-**Immediate action:**
-
-1. STOP generating self-instructions.
-2. Read the last user message — what did they actually ask?
-3. Do that ONE thing directly. No planning monologue, no tool selection reasoning.
-4. If you don't know what the user wanted, ask: "Where were we?"
-
 ## Fresh Output Over Memory
 
-**CRITICAL**: When a tool or command returns a value (branch name, file path, PR number),
-use that EXACT value in subsequent API calls. NEVER substitute a value from earlier in
-the conversation. Context decay causes silent mismatches — fresh output is the only source of truth.
-
-## Conversation Efficiency
-
-### Act, skip narration
-
-- **Skip repeating the user's request.** They know what they asked.
-- **Just do it** — skip announcing what you're about to do.
-- **Skip explaining obvious tool calls.** Reading a file needs no justification.
-- **Report only outcomes** — skip intermediate step summaries unless the user needs them.
-
-**This rule NEVER overrides user-interaction or command rules.**
-Token efficiency means fewer *unnecessary* words — NOT skipping required questions,
-numbered options, or command steps. When a rule or command says "ask the user", you ask.
-
-### Stop early — max 2 retries
-
-- **Command fails twice with same error** → stop, rethink. Try a different approach.
-- **grep/search returns nothing after 2 attempts** → switch approach or ask the user.
-- **Max 3 diagnostic commands** per error. Read the error, think, act.
-- **One hypothesis at a time.** Pick the most likely, try it. If it fails, ask.
-
-### Keep intermediate output minimal
-
-Read `personal.minimal_output` (default: `true`) and `personal.play_by_play`
-(default: `false`) from `.agent-settings.yml`.
-
-When `personal.minimal_output: true`:
-- Multi-step work: short bullet points only, no paragraphs.
-- No thinking out loud — user doesn't need your reasoning.
-- When `personal.play_by_play: false`: silently investigate, report conclusion only.
-- When `personal.play_by_play: true`: briefly share intermediate findings.
-- At the end: concise summary — what changed, what user needs to know.
-
-### Don't re-read what you already know
-
-- Edited a file → edit tool showed result. Don't re-read.
-- Ran a command → you have output. Don't re-run to "verify".
-- File in context from recent messages → don't reload.
-
-### Minimize tool calls
-
-- Parallel reads — don't read 5 files sequentially.
-- Regex search over full file reads. View specific line ranges.
-- One codebase search call with all symbols — not 5 separate.
-- Short question → short answer. Summary tables only for 3+ items.
+When a tool or command returns a value (branch name, file path, PR number), use that EXACT value in subsequent API calls. NEVER substitute a value from earlier in the conversation. Context decay → silent mismatches — fresh output is the only source of truth.
 
-### Exceptions
+## Mechanics — anti-loop patterns, conversation efficiency, exceptions
 
-- Small output (< 30 lines): read directly.
-- Debugging: OK to read more context around one error.
-- User explicitly asks for full output: show it.
+The anti-loop patterns (extended-reasoning loops, "CRITICAL INSTRUCTION" self-prompting), the act-skip-narration / stop-early / keep-output-minimal / don't-re-read / minimize-tool-calls clauses, and the small-output / debugging / explicit-full-output exceptions all live in [`contexts/communication/rules-auto/token-efficiency-mechanics.md`](../contexts/communication/rules-auto/token-efficiency-mechanics.md). The rule above is the obligation surface; the mechanics file is the lookup material.
 
-→ Detailed patterns: `docs/guidelines/agent-infra/output-patterns.md`
+This rule NEVER overrides `user-interaction` or command rules. Token efficiency means fewer *unnecessary* words — NOT skipping required questions, numbered options, or command steps.

package/.agent-src/rules/token-optimizer-maintenance.md

@@ -0,0 +1,68 @@
+---
+type: "auto"
+tier: "2a"
+description: "Editing a token-optimizer-cited asset (cli-output-handling, rtk-output-filtering, token-efficiency, agent-handoff, direct-answers, markitdown) — keep the catalog row in sync in the same commit."
+source: package
+triggers:
+  - keyword: "cli-output-handling"
+  - keyword: "rtk-output-filtering"
+  - keyword: "token-efficiency"
+  - keyword: "agent-handoff"
+  - keyword: "markitdown"
+  - keyword: "token-optimizer"
+routes_to:
+  - "skill:token-optimizer"
+validator_ignore:
+  - type: "substring"
+    pattern: ".agent-src.uncompressed/"
+    reason: "Rule lists the authoring-tree paths that must stay in sync with the catalog."
+---
+
+# Token Optimizer Maintenance
+
+## Iron Law
+
+```
+EDIT A CITED ASSET → UPDATE THE TOKEN-OPTIMIZER ROW IN THE SAME COMMIT.
+THE CI LINK VALIDATOR IS A BACKSTOP, NOT A SUBSTITUTE FOR CARE.
+```
+
+## When this rule fires
+
+About to edit any of:
+
+- `.agent-src.uncompressed/rules/cli-output-handling.md`
+- `.agent-src.uncompressed/rules/token-efficiency.md`
+- `.agent-src.uncompressed/rules/direct-answers.md`
+- `.agent-src.uncompressed/skills/rtk-output-filtering/SKILL.md`
+- `.claude/skills/agent-handoff/SKILL.md`
+- Any other asset cited by
+  [`token-optimizer`](../skills/token-optimizer/SKILL.md) (catalog
+  table is the canonical list).
+
+## Obligation
+
+If the edit touches:
+
+- **Trigger keywords** the decision tree associates with the asset, OR
+- **What the asset does** (the one-line "what it does" summary), OR
+- **The asset's path / location** (rename, move, deletion)
+
+then in the same commit, update the matching row in
+`.agent-src.uncompressed/skills/token-optimizer/SKILL.md` —
+the catalog table AND the relevant tree leaf.
+
+## Out of scope
+
+- Whitespace, comment, formatting, or grammar edits in the cited
+  asset → no token-optimizer update required.
+- Internal restructuring that leaves trigger + summary + path
+  unchanged → no update required.
+
+## Backstop
+
+The CI pipeline runs `scripts/check_token_optimizer_freshness.py`
+after the reference checker. The validator parses the catalog,
+verifies every cited path exists, and `grep`s the trigger keywords
+against each target. A failure is a **drift signal**, not a
+substitute for keeping the catalog correct manually.

package/.agent-src/rules/tool-safety.md

@@ -3,6 +3,10 @@ type: auto
 tier: "2b"
 source: package
 description: "When a skill uses external tools — enforce allowlist, deny-by-default, and no hidden credential patterns"
+triggers:
+  - keyword: "allowed_tools"
+  - keyword: "tool registry"
+  - intent: "external API"
 ---
 
 # Tool Safety

package/.agent-src/rules/ui-audit-gate.md

@@ -1,22 +1,28 @@
 ---
 type: "auto"
 tier: "2b"
-description: "Writing or editing UI — components, screens, partials, layouts, design tokens — require existing-ui-audit findings in state.ui_audit before non-trivial UI change; gate, not suggestion"
 alwaysApply: false
+description: "Writing or editing UI — components, screens, partials, layouts, design tokens — require existing-ui-audit findings in state.ui_audit before non-trivial UI change; gate, not suggestion"
 source: package
-load_context:
-  - .agent-src.uncompressed/contexts/communication/rules-auto/ui-audit-gate-mechanics.md
+triggers:
+  - path_prefix: "resources/views/"
+  - path_prefix: "resources/js/"
+  - keyword: "component"
+  - keyword: "design token"
+routes_to:
+  - "skill:existing-ui-audit"
 ---
 
-# UI-Audit Before Build
+# UI Audit Gate
 
 Defense-in-depth twin of the dispatcher gate in
 [`directives/ui/audit.py`](../templates/scripts/work_engine/directives/ui/audit.py).
-The dispatcher refuses to advance past `refine` without
-`state.ui_audit`; this rule refuses the write even when the agent
-acts outside the dispatcher (free-form edit, "add a tile" request,
-side conversation that bypasses [`/work`](../commands/work.md) or
-[`/implement-ticket`](../commands/implement-ticket.md)).
+The dispatcher refuses to advance past `refine` without `state.ui_audit`;
+this rule refuses the write even when the agent acts outside the dispatcher.
+
+Body migrated to [`skill:existing-ui-audit`](../skills/existing-ui-audit/SKILL.md)
+(per P4 of `road-to-kernel-and-router.md`). Trigger-set above activates this
+routing under the `balanced` and `full` profiles.
 
 ## The Iron Law
 
@@ -25,45 +31,6 @@ NO NEW COMPONENT, SCREEN, PARTIAL, OR PAGE WITHOUT AUDIT FINDINGS.
 EXISTING-UI-AUDIT RUNS FIRST. ALWAYS.
 ```
 
-Skipping the audit is the single biggest source of duplicated
-components and drift from project tokens. The audit is cheap (60 s
-on a primed cache); the cost of skipping is a refactor.
-
-## When this rule activates
-
-Before writing or editing any non-trivial UI surface:
-
-- New page / screen / route component
-- New Livewire / Flux / Blade / React / Vue / Svelte component or partial
-- Major edit to an existing screen (new section, new state, new layout band)
-
-Recognise the trigger from wording even when nobody says "audit":
-"add a dashboard tile", "build a settings panel", "neue Komponente
-für …", "render the orders table", "create the empty state for …".
-
-## Allow-list — when to skip
-
-Skip only when **all** hold:
-
-- `directive_set == "ui-trivial"` (set by Phase 1's intent classifier).
-- The change is provably bounded: ≤ 1 file, ≤ 5 changed lines, no
-  new component, no new state, no new dependency.
-
-Any precondition fails at edit time → stop, reclassify as
-`ui-improve`, re-enter the gate. Backend-only edits and
-documentation work were never in scope for this rule.
-
-## What to do when the gate fires
-
-1. Stop. Do not open an editor on a component file.
-2. Run [`existing-ui-audit`](../skills/existing-ui-audit/SKILL.md);
-   it writes the result to `state.ui_audit`.
-3. On rebound, the dispatcher enters `design` with the audit as
-   defaults in the design-brief halt.
-4. Greenfield → present the numbered scaffold / bare /
-   external-reference halt **before** code; record the pick in
-   `state.ui_audit.greenfield_decision`.
-
 ## What "audit findings" means
 
 `state.ui_audit` is a non-empty dict carrying at least one of:
@@ -71,23 +38,20 @@ documentation work were never in scope for this rule.
 - `components_found` — inventory entries from `existing-ui-audit`.
 - `greenfield: true` plus `greenfield_decision` ∈
   `{scaffold, bare, external_reference}`.
-- Legacy `components` alias — back-compat for the same shape.
+- Legacy `components` alias — back-compat.
+
+`null` or `{}` is **not** findings; empty dict is rejected on purpose.
 
-`null`, `{}`, or a dict without those keys is **not** findings —
-the empty dict is rejected on purpose. An audit that finds nothing
-must record either ≥1 `components_found` or the greenfield branch.
+## Allow-list — `ui-trivial`
+
+Skip only when **all** hold:
+
+- `directive_set == "ui-trivial"`.
+- ≤ 1 file, ≤ 5 changed lines, no new component, no new state.
 
 ## Failure modes
 
 - Writing the component first and "thinking about reuse later".
-- Citing a similar-looking component from memory without verifying.
+- Citing a similar-looking component from memory without verifying via the audit.
 - Treating `state.ui_audit = {}` as "audit ran, found nothing".
 - Bypassing the gate for "just one tile".
-
-## Lookup material — see mechanics
-
-The full failure-mode catalog, cross-rule interactions, and the
-cloud-surface adaptation live in
-[`contexts/communication/rules-auto/ui-audit-gate-mechanics.md`](../contexts/communication/rules-auto/ui-audit-gate-mechanics.md).
-Pull it whenever the gate fires or the agent is unsure whether a
-recorded `state.ui_audit` qualifies.

package/.agent-src/rules/upstream-proposal.md

@@ -2,76 +2,18 @@
 type: "auto"
 tier: "2a"
 description: "After creating or significantly improving a skill, rule, guideline, or command — ask if it should be contributed upstream to the shared package"
-alwaysApply: false
 source: package
+triggers:
+  - phrase: "after creating"
+  - phrase: "after improving"
+  - keyword: "upstream"
+routes_to:
+  - "skill:upstream-contribute"
 ---
 
 # Upstream Proposal
 
-## When to activate
+**Iron Law.** After creating or significantly improving a skill / rule / guideline / command, ask whether to upstream it.
 
-After the agent **creates or significantly improves** any of these in a consumer project:
-
-- Skill (new or major update)
-- Rule (new or major update)
-- Guideline (new or major update)
-- Command (new or major update)
-
-**Also activate when:**
-
-- A project-specific skill/rule could be **generalized** to benefit all consumers
-- An override was created that improves on the shared version
-- A learning was captured that produced a high-quality new artifact
-
-**Do NOT activate when:**
-
-- Working inside the agent-config package itself (no self-referential proposals)
-- The change is a trivial fix (typo, formatting)
-- The user already declined upstream for this exact item in this conversation
-
-## Consent check
-
-**⛔ MANDATORY: Always ask the user. Never skip this step.**
-
-After completing the creation/improvement, evaluate:
-
-1. **Is this universal?** Could other projects benefit from this?
-2. **Is this generalizable?** Even if project-specific, can it be abstracted?
-3. **Is this high-quality?** Does it pass the promotion gate from `capture-learnings`?
-
-If ANY of these is YES → propose to the user:
-
-### For universal content (directly applicable):
-
-```
-> 🔄 The [skill/rule/guideline] `{name}` you just created could benefit all projects
-> using the shared agent-config package.
->
-> 1. Yes — contribute upstream via PR
-> 2. No — keep project-local only
-```
-
-### For project-specific content (needs generalization):
-
-```
-> 🔄 The [skill/rule/guideline] `{name}` is project-specific, but I could generalize
-> it for the shared package. [Brief explanation of what would change]
->
-> 1. Yes — generalize and contribute upstream
-> 2. No — keep project-local only
-```
-
-## After user response
-
-- **User picks 1** → invoke `upstream-contribute` skill (which has its own consent gate for repo access)
-- **User picks 2** → stop. Do NOT ask again for this item.
-- **Max 1 proposal per created artifact** — never nag.
-
-## Important
-
-- **Consent is non-negotiable** — the user decides, always.
-- **Do NOT batch proposals** — ask for each artifact separately.
-- **Do NOT interrupt flow** — only propose AFTER the creation/improvement is complete.
-- **Do NOT propose for trivial changes** — formatting, typos, comment updates.
-- **Respect "no"** — if the user declines, do not revisit unless they bring it up.
-- **Token efficiency** — this rule costs zero tokens when not triggered (auto type).
+Body migrated to `skill:upstream-contribute` (per P4 of `road-to-kernel-and-router.md`).
+Trigger-set above activates this routing under the `balanced` and `full` profiles.

package/.agent-src/rules/user-interaction.md

@@ -5,14 +5,18 @@ description: "Asking the user a question, presenting options, or summarizing pro
 alwaysApply: false
 source: package
 load_context:
-  - .agent-src.uncompressed/contexts/communication/rules-auto/user-interaction-mechanics.md
+  - ../contexts/communication/rules-auto/user-interaction-mechanics.md
+triggers:
+  - intent: "ask user a question"
+  - intent: "numbered options"
+  - intent: "summarizing progress"
 ---
 
 # User Interaction
 
-Two Iron Laws govern every reply that contains numbered options. They
-override conversation momentum, brevity, and the urge to defer to the
-user. **Missing a recommendation is a rule violation, not a slip.**
+Two Iron Laws govern every reply that contains numbered options.
+They override conversation momentum, brevity, and the urge to defer
+to the user. **Missing a recommendation is a rule violation, not a slip.**
 
 ## Iron Law 1 — Single-Source Recommendation
 
@@ -27,57 +31,6 @@ PROSE NAMING A "RECOMMENDED" PATH ABOVE OR BEFORE THE OPTIONS BLOCK = NO RECOMME
 WRONG-LANGUAGE LABEL (`Recommendation:` WHEN USER IS GERMAN, OR VICE VERSA) = NO RECOMMENDATION.
 ```
 
-The agent has read the code, the contracts, the trade-offs. Refusing
-to take a position dumps that work back on the user. Take the
-position; be wrong out loud if needed. "Egal, was bevorzugst Du?" /
-"no preference" is NEVER acceptable.
-
-**Position-agnostic — closes the most common slip:** End-of-turn
-"Wie weiter?" / "What next?" / "How to proceed?" / "How should we
-continue?" blocks with numbered options are **numbered-options
-blocks**. Same Iron Law applies — exactly one `Empfehlung: N` /
-`Recommendation: N` line, every time. There is no "these are just
-follow-up suggestions" exception, no "the user knows better here"
-exception, no "I genuinely don't have a preference" exception. If
-the agent prints `1. … 2. … 3. …` anywhere in the reply, the
-recommendation line is mandatory.
-
-**Format — non-negotiable:**
-
-- Options block stays NEUTRAL — no `(recommended)`, no `(rec)`, no `←`, no bold, no checkmark.
-- Directly after the options block, ONE line, bolded, in the user's language:
-  - English: `**Recommendation: N — <option-name>** — <why>. Caveat: <flip-condition>.`
-  - German:  `**Empfehlung: N — <option-name>** — <warum>. Caveat: <flip-bedingung>.`
-- Other numbers MAY appear later in the prose, but ONLY as caveats
-  (`escalate to 3 if …`, `flip to 1 when …`). NEVER as a primary recommendation.
-- If the agent genuinely cannot pick (rare — true 50/50 with missing data),
-  say what data would break the tie and ask for that instead.
-
-**No trailing open-ended question after numbered options:**
-
-If the reply contains numbered options, the recommendation line IS
-the closer. No `Welcher Pfad?` / `What's it gonna be?` / `Was meinst
-Du?` / `Was sagst Du?` / `Welche willst Du?` / `What do you think?`
-after the recommendation — that reframes the vote as an opinion poll
-and is hedging in disguise. The user picks a number; the agent does
-not re-ask. Permitted: a clarifying caveat sentence on the
-recommendation line itself (`Caveat: flip to 2 if …`). Forbidden:
-any standalone trailing question that re-opens the choice.
-
-**What does NOT count as a recommendation:**
-
-- "Both work" / "either is fine" / "depends on what you prefer"
-- Listing pros and cons without picking a number
-- "I'd lean towards X" without a reason
-- Hiding behind "you know the project better"
-- Inline `(recommended)` tag with no follow-up `Recommendation: N` line
-
-**Slip handling — same protocol as [`language-and-tone`](language-and-tone.md#slip-handling).**
-User calls out a missing or wrong recommendation → acknowledge once
-in the user's language, rewrite the reply with a recommendation,
-ship. No "from now on" promises — only the next reply proves
-compliance.
-
 ## Iron Law 2 — Pre-Send Self-Check
 
 ```
@@ -85,59 +38,20 @@ EVERY REPLY WITH NUMBERED OPTIONS RUNS THE SELF-CHECK. NO EXCEPTIONS.
 SKIPPING IT IS A RULE VIOLATION, NOT A SLIP.
 ```
 
-Before emitting any reply that contains numbered options, scan the
-**entire drafted reply** — top to bottom, including end-of-turn
-"Wie weiter?" / "What next?" continuation menus, follow-up
-suggestion blocks, and any list of `1. … 2. … 3. …` regardless of
-its position or framing:
-
-1. Count occurrences of `(recommended)` / `(rec)` / `(empfohlen)` inline next to a numbered option → MUST be **zero**. Found one → rewrite, drop the tag.
-2. Count `1\.\s` / `2\.\s` / `3\.\s` patterns inside blockquotes or top-level prose → if **any** numbered-option block exists anywhere in the reply, the recommendation line is mandatory.
-3. Count distinct `Recommendation:\s*N` / `Empfehlung:\s*N` lines (case-insensitive) → MUST be **exactly one per options block**. Zero → add one. Two or more distinct numbers → rewrite, pick one.
-4. The number on the recommendation line MUST exist in the option block it follows.
-5. If the reply has multiple options blocks (e.g. a clarification block AND an end-of-turn menu), each block gets its own `Recommendation: N` line directly underneath.
-
-Mechanical backstop: `python3 scripts/check_reply_consistency.py --stdin < draft.md`
-(non-zero exit on any rule above). Self-scan is the primary gate; the
-script is the deterministic safety net for ambiguous cases.
-
-### Common failure modes — known, named, no excuses
-
-- **End-of-turn menu skipped.** Reply answers the question fine, then ends with `1. … 2. … 3. …` and no `Empfehlung:`. Iron Law 1 was violated — these are numbered options, position is irrelevant.
-- **Trailing-question hedge.** Reply has options + recommendation, but ends with `Welcher Pfad?` / `What's it gonna be?` / `Was meinst Du?` — the open question reframes the vote as opinion-poll. Banned by Iron Law 1; the recommendation line is the closer.
-- **"Genuinely no preference" hedge.** Pick anyway. The agent has more context than the user on the trade-off; refusing to pick dumps the work back. Pick the safest option, name the flip-condition.
-- **"User knows the project better" hedge.** Same failure mode, different costume. The user asked for an opinion by virtue of accepting the options block; deliver it.
-- **Multi-block reply with one recommendation.** Two options blocks but only one `Empfehlung:` line — the second block is unguarded. Rule 5 of Iron Law 2 closes this.
-
-## Numbered Options — Always
-
-When asking the user a question with predefined choices, **always
-present numbered options**. The user should be able to reply with
-just a number (e.g., `1`) instead of typing a sentence.
-
-### Format
-
-```
-> 1. First option — brief explanation
-> 2. Second option — brief explanation
-> 3. Third option — brief explanation
-
-**Recommendation: 2 — Second option** — <one-sentence reason>. Caveat: <flip-condition>.
-```
-
-### Rules
-
-- **Every question with choices** must use numbered options — no exceptions.
-- **Every numbered list with `1. … 2. … 3. …`** is a numbered-options block, regardless of position. End-of-turn "Wie weiter?" / "What next?" / "How to proceed?" menus, mid-reply continuation prompts, and clarification blocks all count.
-- **Keep options short** — one line each, with a brief explanation after the dash.
-- **Always include a "skip" or "no change" option** when applicable.
-- **Always state a recommendation** — Iron Law 1 above. Per options block, every time, position-agnostic.
-- **Use the user's language** for the question and options.
-- **Accept both** the number and a natural language answer (e.g., "1" or "the first one").
+Mechanical backstop:
+`python3 scripts/check_reply_consistency.py --stdin < draft.md`
+(non-zero exit on any rule below). Self-scan is the primary gate;
+the script is the deterministic safety net.
 
-### Examples and "when NOT to use" — see mechanics
+## Mechanics — rationale, failure modes, format details, examples
 
-Worked examples (binary choice, multiple choice with skip,
-confirmation with context), the "when NOT to use numbered options"
-catalog, progress indicators, and summary-table patterns live in
+The "why take a position", position-agnostic clause, format
+specification (neutral block + bolded recommendation line + caveat),
+no-trailing-open-question rule, "what does NOT count" catalog, full
+five-step pre-send self-check, named failure-mode catalog (end-of-turn
+menu, trailing-question hedge, no-preference hedge, multi-block reply,
+…), slip-handling protocol, numbered-options rules, format examples,
+progress indicators, and summary-table patterns all live in
 [`contexts/communication/rules-auto/user-interaction-mechanics.md`](../contexts/communication/rules-auto/user-interaction-mechanics.md).
+The rule above is the obligation surface; the mechanics file is the
+lookup material.

package/.agent-src/rules/verify-before-complete.md

@@ -5,7 +5,7 @@ description: "Verify before completion — run tests and quality tools before cl
 alwaysApply: true
 source: package
 load_context:
-  - .agent-src.uncompressed/contexts/execution/verification-mechanics.md
+  - ../contexts/execution/verification-mechanics.md
 ---
 
 # Verify Before Completion

package/.agent-src/skills/agent-docs-writing/SKILL.md

@@ -187,7 +187,7 @@ After completing a significant code change, run this mental checklist:
 | New API endpoint | OpenAPI annotations, `AGENTS.md` API section |
 | New module created | Create `app/Modules/{Module}/agents/` |
 | Service/repository signature changed | Check if referenced in `agents/docs/services-and-repos.md` |
-| New environment variable | `.env.example`, `AGENTS.md` environment section |
+| New environment variable | `.env.example`, `AGENTS.md` env section |
 | Docker/compose change | `agents/docs/docker.md`, `Makefile` documentation |
 | New Artisan command | `AGENTS.md` commands section |
 | New pattern/convention introduced | Relevant guideline in `.augment/guidelines/` |

package/.agent-src/skills/ai-council/SKILL.md

@@ -144,6 +144,48 @@ provider's reply, when available) for observability. Mixed runs
    into concrete numbered options for the user. The user decides;
    the council advises.
 
+## Output path convention
+
+Council artefacts (questions, responses, sessions) are **dev-time
+scratch** — gitignored in both the package repo and consumer repos
+and auto-pruned after `ai_council.session_retention_days` (default
+7). They inform a decision; they are not the durable contract. The
+durable contract lives in the roadmap / ADR / skill body that cites
+the council's convergence inline.
+
+**Linking to a specific council file is forbidden by
+[`no-council-references`](../../rules/no-council-references.md)** —
+gitignored, not in the cloned repo, gone after the retention window.
+Inline the convergence with date + members instead.
+
+Three directories, three modes:
+
+| Mode | Path | Format |
+|---|---|---|
+| **Topic-anchored question** (paired with a roadmap or ADR) | `agents/council-questions/<topic-slug>.md` | Markdown |
+| **Topic-anchored response** (paired with the question above) | `agents/council-responses/<topic-slug>.json` | JSON from `council:run --output` |
+| **Ad-hoc session** (no durable artefact yet) | `agents/council-sessions/<UTC-timestamp>.json` | JSON from `council:run --output` |
+
+`<topic-slug>` is kebab-case and **must match** the corresponding
+roadmap / ADR slug if one exists (e.g. `path-fixes` mirrors the
+matching `road-to-<topic-slug>` roadmap under `agents/roadmaps/`).
+
+### Forbidden
+
+- Files at `agents/` root (e.g. `agents/council-question-foo.md`).
+- Dot-prefix scratch (e.g. `agents/.council-question-foo.md`).
+- Any other directory below `agents/` (e.g. `agents/scratch/`,
+  `agents/tmp/`).
+- Cross-references from any artefact to specific council files —
+  see [`no-council-references`](../../rules/no-council-references.md).
+  Inline the convergence summary instead, with date and member list
+  for traceability (`Council (claude-sonnet-4-5 + gpt-4o, YYYY-MM-DD)
+  reviewed N candidate strategies; converged on …`).
+
+`scripts/check_council_layout.py` is the mechanical check for the
+output path convention — wire it into the package's CI pipeline so
+violations break the build.
+
 ## Output format
 
 Every council reply MUST contain, in this order:
@@ -294,8 +336,16 @@ prompt as `<original artefact> + <prior round, anonymised>` so each
 member can refine, agree, or push back on the previous critique
 without seeing which provider produced which point.
 
+The default round count comes from `ai_council.min_rounds` in
+`.agent-settings.yml` (default `2` so members critique each other
+at least once before convergence). The host agent does **not** ask
+"how many rounds?" when the requested count is `<= min_rounds` —
+the settings owner already made that decision. Ask only when a
+genuinely complex artefact justifies more depth than the default.
+
 | Property | Behaviour |
 |---|---|
+| Default count | `ai_council.min_rounds` (default `2`). Override per-invocation with `rounds:N` (or `--rounds N` to the CLI). |
 | Anonymisation | Provider/model identity is stripped. Reviewers are labelled `Reviewer A / B / C…` in input order. |
 | Errored prior responses | Skipped — they reveal nothing useful and can leak provider error formats. |
 | Cost budget | Accumulates across rounds. A round-2 call that breaches the cap fires `on_overrun` exactly like a round-1 breach. |
@@ -322,6 +372,21 @@ Round 2: artefact + anonymised round 1 critiques
 | **total**          |           | $0.0594 |
 ```
 
+### Manual-mode parity
+
+The orchestrator drives rounds the same way for `api` and `manual`
+transports. One round = one full pass over every enabled member,
+top-to-bottom, then `_augment_for_next_round()` folds the
+anonymised critiques into the round-N+1 user prompt. For manual
+mode this means: emit the round-1 block for member A → user
+pastes A's reply → next member B → user pastes B's reply → host
+agent consolidates round 1 → emit the round-2 block (now carrying
+the anonymised round-1 critiques) for member A → … and so on
+until the configured round count is reached. ManualClient's
+internal "more feedback" follow-up loop (1 / 2 / 3 menu) is
+**inside** a single member's chat thread and is orthogonal to the
+orchestrator-level rounds.
+
 ## See also
 
 - `/council` command — the user-facing entry point.

package/.agent-src/skills/analysis-autonomous-mode/SKILL.md

@@ -80,7 +80,7 @@ Route to the primary skill. Monitor findings for signals to chain additional ski
 
 Merge all specialist findings into ONE prioritized output:
 
-1. Confirmed root causes (with evidence)
+1. Confirmed root → (with evidence)
 2. Contributing factors
 3. Risks not yet proven but worth checking
 4. Concrete fixes (ordered by priority)