@event4u/agent-config 1.20.0 → 1.22.0

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/adversarial-review/SKILL.md

@@ -4,6 +4,7 @@ description: "ONLY when user explicitly requests adversarial review, devil's adv
 personas:
   - critical-challenger
 source: package
+council_depth: deep
 ---
 
 # Adversarial Review

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

@@ -43,6 +43,7 @@ prompt that asks them to think on their own merits.
 THE COUNCIL DOES NOT SEE THE HOST AGENT'S ANALYSIS.
 THE COUNCIL DOES NOT SEE PRIOR REPLIES.
 THE COUNCIL SEES THE ARTEFACT + THE NEUTRAL SYSTEM PROMPT. NOTHING ELSE.
+THE HOST AGENT IS THE CONVENER, NEVER A REVIEWER.
 ```
 
 If you find yourself wanting to "frame" the artefact for the council,
@@ -50,6 +51,13 @@ stop. Framing is exactly what kills the second-opinion value. Use the
 unbiased system prompts in `scripts/ai_council/prompts.py`; do not
 roll your own.
 
+The host runs the council and synthesises convergence — it is the
+convener, not a reviewer. The reviewer-ban is structural: the host
+wrote (or framed) the artefact and cannot critique it independently.
+Anonymising the host as "Reviewer C" is worse than excluding it — the
+user is told they got an outside vote when they did not. Externals
+down → surface and skip; never substitute the host as a reviewer.
+
 ### Neutrality — context-handoff
 
 External reviewers do better critique when they know **what the
@@ -120,6 +128,27 @@ token counts (from the manual-paste length heuristic or the
 provider's reply, when available) for observability. Mixed runs
 (one manual + one api) gate only the api members.
 
+## Degradation modes
+
+How the council behaves when fewer than two billable members are
+reachable. The orchestrator never silently substitutes — degradation
+is visible to the user.
+
+| Reachable | Behaviour | Independence |
+|---|---|---|
+| **2+** | Full fan-out, multi-round debate. Default. | High — cross-provider diversity. |
+| **1** | Single-voice critique with a degraded-run warning. Multi-round mode lets the model see its own anonymised reply, but convergence ≠ correctness. | Low — shared blind spots. |
+| **0** | Council skipped. Surface the failure, proceed without external review. **Never** substitute the host or an unrequested manual pass. | None. |
+
+Rejected anti-patterns (council convergence, 2026-05-06): persona
+prompts (same model, same blind spots, more cost), temperature
+spread (noise, not signal), host-as-fallback (Iron Law breach).
+Supported single-provider strategy is **sibling models on the same
+provider** (e.g. Sonnet ↔ Opus, gpt-4o ↔ o1) — different training
+cutoffs / reasoning architectures within one provider family. Cost
+is real (siblings price-tier higher); explicit opt-in per invocation,
+not a default.
+
 ## Procedure
 
 1. **Resolve target.** Identify the artefact mode (`prompt`, `roadmap`,
@@ -140,9 +169,103 @@ provider's reply, when available) for observability. Mixed runs
    into the host agent's voice.
 6. **Summarise.** Write a `Convergence / Divergence` block listing
    agreements, disagreements, and unique insights — provider-attributed.
-7. **Translate to options.** Convert actionable council suggestions
-   into concrete numbered options for the user. The user decides;
-   the council advises.
+7. **Critically evaluate** every finding before it leaves the host
+   (see *Critical evaluation* below). The host is the convener **and**
+   the skeptic — never a reviewer of the artefact itself, but always a
+   reviewer of the **council's output**.
+8. **Translate validated findings to options.** Convert each finding
+   the host accepts (or accepts with modification) into a concrete
+   numbered option for the user. Tag every option with the host's
+   verdict so the user sees the agent's reasoned position, not the
+   council's raw output. The user decides; the council advises; the
+   host filters.
+
+## Critical evaluation — convener-skeptic stance
+
+```
+COUNCIL CONVERGENCE IS NOT CORRECTNESS.
+DO NOT BLINDLY ACCEPT FINDINGS. DO NOT BLINDLY REJECT THEM.
+EVERY FINDING GETS A REASONED VERDICT BEFORE IT REACHES THE USER.
+```
+
+The council is **uninformed about the codebase, ADRs, locked
+contracts, prior decisions, and project history** — it sees only the
+artefact + neutrality preamble. That is the source of its diversity
+**and** its blind spots. Convergence between members can mean shared
+generic best-practice priors, not project-specific correctness.
+
+The host applies a critical lens to **every finding** (convergence
+**and** divergence) before surfacing it as a numbered option:
+
+| Check | Question | Tool |
+|---|---|---|
+| **Codebase fit** | Does the finding match the actual code, files, signatures, conventions? | `view` / `codebase-retrieval` / `grep` |
+| **Locked-decision conflict** | Does it contradict an ADR, kernel rule, contract under `docs/contracts/`, or `docs/decisions/`? | `view` |
+| **Already addressed** | Is it a generic best-practice already covered by an existing rule, skill, or test? | `view` / `grep` |
+| **Cost / benefit** | Is the change worth the diff size, churn, and review cost vs. the marginal benefit? | reasoning |
+| **Hallucination** | Does the finding cite a file, function, or behavior that does not exist? | `view` |
+
+Each finding receives one of three verdicts:
+
+- **`accept`** — codebase fits, no locked-decision conflict, benefit clears cost. Surface as a normal numbered option.
+- **`accept-with-modification`** — core insight valid, but the proposed shape needs adjusting (wrong file, contradicts ADR detail, scope creep). Surface with the **modified** patch and a one-line note.
+- **`reject`** — finding is wrong (hallucinated reference, contradicts a locked decision, already addressed, generic noise). Surface as a **Rejected by host** entry with a one-line reason. Still visible — the user can override.
+
+The verdict is the host's **own** reasoning, not the council's.
+Pretending convergence equals correctness, or paraphrasing council
+output as host analysis, both breach the [`direct-answers`](../../rules/direct-answers.md)
+no-invented-facts rule. When the host cannot reach a confident
+verdict on a finding (mixed evidence, ambiguous scope), it surfaces
+the finding as `needs-input` with the open question — the user
+decides, the host does not guess.
+
+### What this is NOT
+
+- **Not a re-review by the host.** The host did not write the artefact independently and cannot critique it independently — that boundary still holds.
+- **Not a vote against the council.** Rejecting a finding requires evidence (file, line, contract reference), not preference.
+- **Not silent filtering.** Every finding reaches the user with its verdict and reason. The user can pick a `reject` option and override the host.
+
+## 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
 
@@ -153,16 +276,26 @@ Every council reply MUST contain, in this order:
    containing the member's verbatim output.
 3. **Convergence / Divergence summary** — bullet list, every claim
    attributed by provider name.
-4. **User-facing options** — numbered block per `user-interaction`,
-   with "discard council input" always present as an option.
-
-The host agent NEVER ships council output as its own reasoning.
-Provider attribution stays visible in every render.
+4. **Host verdict per finding** — one row per finding with `accept`
+   / `accept-with-modification` / `reject` / `needs-input` plus a
+   one-line reason citing host evidence (file:line, ADR, contract).
+   See *Critical evaluation* above.
+5. **User-facing options** — numbered block per `user-interaction`,
+   carrying the host verdict in each option, with "discard council
+   input" always present as an option.
+
+The host agent NEVER ships council output as its own reasoning, and
+NEVER ships the host verdict as council output. Provider attribution
+stays visible in the per-member sections; host verdicts stay
+attributed to the host.
 
 ## Do NOT
 
 - Do NOT paraphrase council output into the host agent's voice — strip
   attribution and you've stripped the value.
+- Do NOT surface council findings to the user without a host verdict
+  — convergence ≠ correctness, and the user deserves the agent's
+  reasoned filter, not a raw forward.
 - Do NOT pre-warm the council with the host agent's analysis or
   identity — that primes the reviewer and collapses diversity.
 - Do NOT silently truncate a too-large bundle — surface the size and
@@ -194,6 +327,9 @@ Real failure modes seen in the wild:
 | Silently truncate a too-large bundle. | Misleads the reviewer into thinking they saw the whole thing. | Bundler raises `BundleTooLarge`; surface and ask for narrower scope. |
 | Reuse the same SDK client across calls without re-loading the key. | Leaks the key in long-lived process state. | Each invocation builds fresh clients from `load_*_key()`. |
 | Auto-spend tokens under `personal.autonomy: on`. | Autonomy ≠ permission to spend money. | Always ask before consultation, even under autonomy. |
+| Forward council convergence to the user as numbered options without a host verdict. | Convergence ≠ correctness; the council never saw the codebase. | Apply the *Critical evaluation* lens; tag every finding `accept` / `accept-with-modification` / `reject` / `needs-input` with one-line reason. |
+| Reject a finding on preference, not evidence. | "I don't like this" is not a verdict. | Cite the file, line, ADR, or contract that justifies the rejection — or surface as `needs-input`. |
+| Paraphrase council output into the host's own analysis to defend a verdict. | Strips attribution, breaches `direct-answers` no-invented-facts. | Verdict cites host evidence (file:line); council output stays attributed in the per-member sections. |
 
 ## Redaction expectations
 
@@ -294,8 +430,46 @@ 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.
+
+### Deep-reasoning tier (`council_depth: deep`)
+
+Architecture review, refactoring proposals, and bug-diagnosis runs
+benefit from an extra critique round. The deep tier is opt-in per
+artefact:
+
+1. The consuming **rule, skill, or command** declares
+   `council_depth: deep` in its frontmatter. The schema accepts
+   **only `deep`** — `standard` is the implicit default and is
+   rejected by the linter (every frontmatter byte costs context
+   window; see `scripts/schemas/{rule,skill,command}.schema.json`).
+   To return an artefact to default depth, **delete the key**.
+2. The **host agent** reads that frontmatter when it dispatches the
+   council and passes `--depth deep` to `council_cli`. If multiple
+   active artefacts disagree, **deep wins** (max policy).
+3. The **CLI** floors the round count at
+   `max(ai_council.deep_min_rounds, ai_council.min_rounds)` —
+   defaults to `3` and `2` respectively. Lowering `deep_min_rounds`
+   below `min_rounds` has no effect (defensive max).
+
+The CLI itself has no knowledge of frontmatter; the contract is the
+flag. Resolution chain (highest priority first):
+
+```
+--rounds N           → explicit, any value (user override)
+--depth deep         → max(deep_min_rounds, min_rounds)
+(no flag)            → min_rounds (default 2)
+```
+
 | Property | Behaviour |
 |---|---|
+| Default count | `ai_council.min_rounds` (default `2`). Override per-invocation with `rounds:N` (or `--rounds N` to the CLI). |
+| Deep floor | `ai_council.deep_min_rounds` (default `3`). Activated by `council_depth: deep` in artefact frontmatter (host translates to `--depth deep`) or explicit `--depth deep` on the CLI. Floored at `min_rounds`. |
 | 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 +496,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)

package/.agent-src/skills/analysis-skill-router/SKILL.md

@@ -106,18 +106,18 @@ Check:
 
 **Choose `project-analysis-core` if:** broad discovery needed, framework deep-dive not yet justified.
 
-**Choose `project-analysis-hypothesis-driven` if:** problem is concrete, multiple causes plausible, main job is explanation not discovery.
+**Choose `project-analysis-hypothesis-driven` if:** problem is concrete, multiple → plausible, main job is explanation not discovery.
 
 **Choose framework-specific analysis if:** framework is explicit, failure pattern is framework-shaped.
 
-**Do NOT route broadly if:** one component or file is enough, fix is obvious and local, task is implementation not investigation.
+**Do NOT route broadly if:** one component or file is enough, fix is obvious and local, task is impl not investigation.
 
 ## Examples
 
 **"Analyze this whole Laravel project"** → `universal-project-analysis` → chain `project-analysis-laravel`
 **"Hydration mismatch in Next.js"** → `project-analysis-nextjs` (no full-project needed)
 **"Bug could be cache, queue, or version mismatch"** → `project-analysis-hypothesis-driven`
-**"Change one React component"** → no analysis skill, use implementation skill
+**"Change one React component"** → no analysis skill, use impl skill
 
 ## Gotcha
 

package/.agent-src/skills/artisan-commands/SKILL.md

@@ -41,7 +41,7 @@ Do NOT use when:
 - Destructive? → Add `--force` flag + confirmation.
 - Scheduled? → Ensure non-interactive, idempotent, loud failures.
 - Long-running? → Use chunking/cursors, progress bar.
-- Production? → Add environment check if needed.
+- Production? → Add env check if needed.
 
 ### Step 4: Test
 
@@ -62,7 +62,7 @@ Do NOT use when:
 
 - `$this->info()` is suppressed in quiet mode — use `$this->line()` for critical info.
 - Always add `--force` for destructive commands — never delete data without confirmation.
-- Add environment checks for production commands.
+- Add env checks for production commands.
 
 ## Do NOT
 

package/.agent-src/skills/authz-review/SKILL.md

@@ -168,4 +168,4 @@ Runtime confirmation (e.g. *"reproduce the cross-tenant read against staging"*,
   [`data-exposure-review`](../data-exposure-review/SKILL.md),
   [`judge-security-auditor`](../judge-security-auditor/SKILL.md),
   [`security`](../security/SKILL.md),
-  [`security-audit`](../security-audit/SKILL.md) — sibling review / implementation skills.
+  [`security-audit`](../security-audit/SKILL.md) — sibling review / impl skills.

package/.agent-src/skills/aws-infrastructure/SKILL.md

@@ -16,9 +16,9 @@ Do NOT use when:
 
 ## Procedure: Modify AWS infrastructure
 
-1. Read the `.aws/` directory (or equivalent) for environment configs and templates.
+1. Read the `.aws/` directory (or equivalent) for env configs and templates.
 2. Read CI/CD workflows (e.g., `.github/workflows/`) for the deployment pipeline.
-3. Check the environment-specific vars files.
+3. Check the env-specific vars files.
 4. **Read project-level overrides** — check `agents/overrides/skills/aws-infrastructure.md` for project-specific service names, prefixes, and infrastructure details.
 
 ## Architecture overview
@@ -38,7 +38,7 @@ Do NOT use when:
 | **ECS Fargate** | Container orchestration (no EC2 instances) |
 | **ECR** | Docker image registry |
 | **EFS** | Shared filesystem (private + public access points) |
-| **Secrets Manager** | `.env` file storage per environment |
+| **Secrets Manager** | `.env` file storage per env |
 | **IAM Roles** | OIDC-based GitHub Actions authentication |
 | **VPC** | Networking (security groups, subnets) |
 
@@ -97,7 +97,7 @@ Template variables:
 ### Authentication
 
 - GitHub Actions uses **OIDC** (no long-lived AWS credentials).
-- Role ARN is per-environment in the vars file.
+- Role ARN is per-env in the vars file.
 - `aws-actions/configure-aws-credentials` handles the OIDC exchange.
 
 ### Image tagging
@@ -139,7 +139,7 @@ See the `terraform` and `terragrunt` skills for general IaC conventions.
 
 ## Gotcha
 
-- Never hardcode AWS credentials — always use Secrets Manager or environment variables.
+- Never hardcode AWS credentials — always use Secrets Manager or env variables.
 - ECS task definitions are immutable — you create new revisions, not edit existing ones.
 - gomplate templates use `{{ }}` which conflicts with other template engines — escape carefully.