@event4u/agent-config 1.15.0 → 1.17.0

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

@@ -1,8 +1,10 @@
 ---
-type: "always"
-description: "User interaction — numbered options, progress indicators, summaries"
-alwaysApply: true
+type: "auto"
+description: "Asking the user a question, presenting options, or summarizing progress — numbered-options Iron Law, single-recommendation rule, progress indicators"
+alwaysApply: false
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/user-interaction-mechanics.md
 ---
 
 # User Interaction
@@ -55,7 +57,7 @@ recommendation line is mandatory.
 - 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#when-the-user-calls-out-a-language-slip).**
+**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
@@ -84,12 +86,11 @@ Mechanical backstop: `python3 scripts/check_reply_consistency.py --stdin < draft
 (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. Foo > 2. Bar > 3. Stop` and no `Empfehlung:`. Iron Law 1 was violated — these are numbered options, position is irrelevant.
-- **"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 above closes this.
+Common failure modes (end-of-turn menu skipped, "no preference"
+hedges, multi-block reply with one recommendation) and the named
+slip catalog live in
+[`contexts/communication/rules-auto/user-interaction-mechanics.md`](../contexts/communication/rules-auto/user-interaction-mechanics.md)
+§ Common failure modes.
 
 ## Numbered Options — Always
 
@@ -117,65 +118,9 @@ just a number (e.g., `1`) instead of typing a sentence.
 - **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").
 
-### Examples
-
-**Binary choice:**
-
-```
-> 1. Interactive — ask before each comment
-> 2. Automatic — handle all independently
-
-**Recommendation: 1 — Interactive** — the comments touch security-sensitive code,
-so a wrong auto-fix is more expensive than approving each one. Caveat: flip to 2
-if the comments turn out to be pure formatting.
-```
-
-**Multiple choice with skip:**
-
-```
-> 1. Fix the code
-> 2. Fix the test
-> 3. Skip
-
-**Recommendation: 1 — Fix the code** — the test asserts the documented behaviour;
-the production code drifted from the contract. Caveat: pick 2 only if the contract
-itself is wrong.
-```
-
-**Confirmation with context:**
-
-```
-> Found PR #1399 on branch `chore/refactor-agent-setup-2`.
->
-> 1. Yes, that's the right PR
-> 2. No, different PR — I'll provide the URL
+### Examples and "when NOT to use" — see mechanics
 
-**Recommendation: 1 — Yes** — the branch name matches the PR title exactly.
-Caveat: flip to 2 if the PR was reopened from a different branch.
-```
-
-### When NOT to use numbered options
-
-- **Open-ended questions** where the answer is free text (e.g., "What should the class be named?").
-- **Simple yes/no** can use numbered options OR accept "ja"/"nein" directly.
-  Even for yes/no, prefer numbered options if there's additional context to show.
-
-## Progress Indicators
-
-When processing multiple items (e.g., review comments, test failures), show progress:
-
-```
-**Comment 3/7** — `filename.php:42`
-```
-
-## Summaries
-
-After completing a batch of actions, provide a summary table:
-
-```
-| # | File | Action |
-|---|---|---|
-| 1 | `file.php` | Fixed null check |
-| 2 | `test.php` | Updated assertion |
-| 3 | `config.php` | Skipped (intentional) |
-```
+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
+[`contexts/communication/rules-auto/user-interaction-mechanics.md`](../contexts/communication/rules-auto/user-interaction-mechanics.md).

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

@@ -3,6 +3,8 @@ type: "always"
 description: "Verify before completion — run tests and quality tools before claiming done"
 alwaysApply: true
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/execution/verification-mechanics.md
 ---
 
 # Verify Before Completion
@@ -15,25 +17,6 @@ NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
 
 If you haven't run the verification command **in this message**, you cannot claim it passes.
 
-## When to run what — timing matters
-
-**Quality tools (PHPStan, Rector, ECS) run ONCE at the very end** — not after every edit.
-Do NOT run quality checks between tasks if you have more work to do.
-Only run the full quality pipeline when you are about to finish all work in the current conversation.
-
-**Tests: as targeted as possible, as little as necessary.**
-- During work: run ONLY the specific test class or test case affected by the change.
-  Use `--filter=ClassName` or `--filter=test_name` — NEVER the full suite mid-work.
-- Only run tests when you genuinely need to verify behavior (not "just to be safe").
-- Full test suite: ONCE at the very end, before quality tools.
-
-**The sequence at the end:**
-1. All code changes are done
-2. Run tests — targeted first (`--filter`), full suite only if targeted passes
-3. Run quality pipeline (PHPStan → Rector → ECS → PHPStan)
-4. Fix any issues from step 2-3
-5. ONLY THEN claim completion or suggest commit/push/PR
-
 ## The Gate
 
 Before claiming ANY work is complete:
@@ -67,54 +50,16 @@ Skip any step = the claim is unverified.
 For specific commands → see the `quality-tools` skill.
 
 For the detailed evidence-gate playbook (claim→command mapping, output
-inspection, end-of-work sequence) → see the `verify-before-complete`
+inspection, end-of-work sequence) → see the `verify-completion-evidence`
 skill.
 
-## Minimum verification per task type
-
-| Task | Required evidence |
-|---|---|
-| Code change | Tests + PHPStan |
-| New feature | Tests + PHPStan + smoke test |
-| Bug fix | Regression test + full suite |
-| Refactoring | Full suite + PHPStan + Rector |
-| Config/migration | Relevant tests or command output |
-| API endpoint | curl/HTTP response output |
-| Documentation only | No verification needed |
-
-**Never accept** as proof: "should work", "looks correct", "logic is sound".
-No captured output = not verified.
-
-## Confidence gating
-
-State confidence explicitly before claiming completion on non-trivial work.
-
-- **High** — runtime path read end-to-end, relevant tests inspected or run,
-  no hidden side-effects (queues/events/observers) unaccounted for.
-- **Medium** — main path verified but one gap remains; list the gap in the
-  completion message.
-- **Low** — broad implementation NOT allowed; switch to analysis, narrow
-  the scope, or ask the user before proceeding.
-
-For high-risk areas (auth, tenancy, migrations, queues, dependencies,
-external APIs, data exposure), "high" requires tests AND a cross-layer
-read — not inference from a single file.
-
-## Break-glass reduction
-
-During a live production incident the verification gate is **narrowed**,
-never skipped. Break-glass requires explicit user invocation (e.g.
-`break-glass: true`, "this is a hotfix"). Never enter it unilaterally.
-
-Minimum evidence:
-
-- **Targeted test(s)** covering the exact regression — zero tests is not
-  acceptable.
-- **Smoke check** of the fixed path (curl, manual trigger, log tail) with
-  output captured in the message.
-- **Explicit list of skipped validations** and a **follow-up commitment**
-  (ticket or PR line) to run them within 24h.
+## Mechanics — when to run what, per-task evidence, confidence, break-glass
 
-Completion wording: _"hotfix applied, full verification deferred per
-break-glass"_ — never _"done"_ or _"verified"_. The normal gate resumes
-on the follow-up PR.
+The decision logic for **when** to run quality tools vs. tests, the
+per-task-type minimum-evidence table, confidence gating (High /
+Medium / Low), and the break-glass reduction during live incidents
+all live in
+[`verification-mechanics`](../contexts/execution/verification-mechanics.md).
+The Iron Law and the Gate above are the obligation surface; the
+mechanics context is the lookup material the agent pulls when the
+gate fires.

package/.agent-src/scripts/update_roadmap_progress.py

@@ -44,17 +44,21 @@ from pathlib import Path
 
 CHECKBOX_RE = re.compile(r"^\s*[-*]\s+\[([ xX~\-])\]\s", re.MULTILINE)
 # H2 or H3 heading starting with "Phase <id>"; separator (colon, em-dash,
-# hyphen, or whitespace) and name are optional. The id supports three
+# hyphen, or whitespace) and name are optional. The id supports four
 # project-level conventions:
 #   - numeric        `Phase 0`, `Phase 10`
+#   - numeric+sub    `Phase 2a`, `Phase 10c` (digit run + single
+#                    lowercase letter for sub-phases)
 #   - roman I..XXXIX `Phase I`, `Phase III`
 #   - letter track   `Phase A`, `Phase B1` (single uppercase letter,
 #                    optional trailing digits for sub-track IDs)
 # Roman is capped at [IVX]+ (up to XXXIX) on purpose: the broader
 # [IVXLCDM]+ would also match all-caps words like `Phase LIVE`. Letter
 # is [A-Z] not [A-Za-z] so `## Phase overview` stays a non-phase anchor.
+# The numeric+sub branch keeps the lowercase-letter restriction so
+# `Phase abc` (no digits) still falls through to the rejection branch.
 PHASE_RE = re.compile(
-    r"^(#{2,3})\s+Phase\s+(\d+|[IVX]+|[A-Z](?:\d+)?)"
+    r"^(#{2,3})\s+Phase\s+(\d+[a-z]?|[IVX]+|[A-Z](?:\d+)?)"
     r"(?:[\s:\u2014\-]+(.*?))?\s*$",
     re.MULTILINE,
 )
@@ -74,8 +78,9 @@ DRAFT_VALUES = frozenset({"draft"})
 @dataclass
 class PhaseStats:
     # Phase identifier as it appears in the heading: numeric ("0"),
-    # roman ("III"), or letter-track ("A", "B1"). Kept as a string so
-    # non-numeric conventions survive round-tripping through render().
+    # numeric+sub ("2a"), roman ("III"), or letter-track ("A", "B1").
+    # Kept as a string so non-numeric conventions survive round-tripping
+    # through render().
     id: str
     name: str
     done: int = 0

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

@@ -0,0 +1,335 @@
+---
+name: ai-council
+description: "Use when polling external AIs (OpenAI, Anthropic) outside the host session for a neutral second opinion on a roadmap, diff, prompt, or file set — or 'cross-check with another model'."
+source: package
+---
+
+> **Experimental.** AI Council is not yet validated by external users. API costs apply per consultation.
+
+# ai-council
+
+## When to use
+
+* The host agent has drafted a roadmap, plan, or design and wants an
+  **external** critique that is not biased by its own framing.
+* The user asks "what would Claude / GPT say about this?" or invokes
+  `/council`.
+* A PR diff or commit range needs a second-opinion review beyond the
+  internal four-judge pass.
+* A free-form proposal benefits from being challenged by an outside
+  reviewer before it calcifies into work.
+
+Do NOT use when:
+
+* The decision is internal-only and budget matters more than diversity
+  of opinion → use `subagent-orchestration` (in-session, no network,
+  no money).
+* The artefact contains secrets that cannot be redacted with the
+  bundler's pattern set → ask the user before sending.
+* The user has not configured any council member → state that and stop;
+  do not silently fall back to anything.
+
+## Goal
+
+Bring in **independent** external models to critique a project
+artefact. Independent means: the council members never see the host
+agent's reasoning, internal state, or framing language — only the
+artefact (roadmap, diff, prompt, file set) plus a neutral system
+prompt that asks them to think on their own merits.
+
+## Neutrality guidelines (Iron Law)
+
+```
+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.
+```
+
+If you find yourself wanting to "frame" the artefact for the council,
+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.
+
+### Neutrality — context-handoff
+
+External reviewers do better critique when they know **what the
+project is**, not just what the artefact looks like. The council
+ships a neutral **handoff preamble** (modelled on `/agent-handoff`)
+in front of every member's system prompt, assembled by
+`prompts.handoff_preamble(project, original_ask)`:
+
+| Carried | Forbidden |
+|---|---|
+| Project name (from `composer.json` / `package.json` / repo dir) | Host-agent identity (Augment, Claude Code, Cursor, Cline, Windsurf, Copilot agent) — stripped line-by-line before send |
+| Stack one-liner inferred from manifest files | Host-agent reasoning, prior turns, internal analysis |
+| One paragraph of repo purpose from `README.md` (max 400 chars) | Host-agent framing language ("I think this looks weak", "the user probably wants…") |
+| The user's **original ask** verbatim (the free-form sentence that triggered `/council`) | Anything the host agent generated about the artefact |
+
+`detect_project_context()` in `scripts/ai_council/project_context.py`
+reads only the manifest files + root README; missing fields collapse
+to `None` and the preamble silently omits the line. With both
+`project=None` and `original_ask=""`, the preamble degrades to the
+bare `NEUTRALITY_PREAMBLE` (v1 shape — back-compat for callers that
+have not migrated yet).
+
+## Execution modes
+
+A council member can run in one of three transports. The neutrality
+preamble is identical across all of them — only the path the bytes
+travel changes.
+
+| Mode | Client | Billable | Transport | Status |
+|---|---|---|---|---|
+| `api` | `AnthropicClient` / `OpenAIClient` | yes | provider SDK + key from `~/.config/agent-config/<provider>.key` | shipped |
+| `manual` | `ManualClient` | no | `stdout` (prompt block) + `stdin` (user pastes the web-UI reply, terminated by a line containing only `END`) | shipped (Phase 2b) |
+| `playwright` | `PlaywrightClient` | no | persistent-profile browser at the provider's chat URL via DOM adapter | reserved (Phase 2c — capture-only) |
+
+Resolution lives in `scripts/ai_council/modes.py`:
+`resolve_mode(name, invocation_mode, member_settings, global_mode)`
+with precedence **invocation flag > per-member setting > global
+setting > default (`api`)**. Whitespace-and-case insensitive; empty
+strings fall through; unknown values raise `InvalidModeError` with
+the offending settings path (`ai_council.mode`,
+`ai_council.members.<name>.mode`, or `/council mode=`).
+
+### Manual-mode UX
+
+`ManualClient` is the user-as-transport variant: the agent prints
+one Markdown block per member (system prompt + handoff preamble +
+artefact between two `═` rules), the user pastes it into a web
+chat (Claude.ai, ChatGPT, Gemini), then pastes the reply back
+ending with a line containing only `END`. After each reply, a 1/2/3
+menu surfaces:
+
+1. More feedback for this member (continue this thread)
+2. Done with this member, move to the next
+3. Abort the council run
+
+`1` re-emits a follow-up block addressed to the **same chat
+thread** (no system prompt repetition). `2` records the round and
+moves to the next member. `3` returns `error="manual_aborted"` for
+that member and the orchestrator stops the fan-out.
+
+### Cost-gate bypass for non-billable members
+
+`ExternalAIClient.billable` is the contract. Clients with
+`billable=False` (today: `ManualClient`; future: `PlaywrightClient`)
+bypass the cost gate entirely — the orchestrator skips the
+projection check, the `on_overrun` callback, and the USD-budget
+short-circuit for that member, but still records the response's
+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.
+
+## Procedure
+
+1. **Resolve target.** Identify the artefact mode (`prompt`, `roadmap`,
+   `diff`, `files`) and locate the source. Refuse to proceed if the
+   target is ambiguous.
+2. **Bundle + redact.** Call `scripts/ai_council/bundler.py` to produce
+   a redacted artefact bundle. If `BundleTooLarge` fires, surface the
+   size and ask the user to narrow scope — do NOT truncate silently.
+3. **Confirm spend.** Before any network call, surface members + cost
+   ceiling and require an explicit user `1` to proceed. Autonomy
+   settings do not override this gate.
+4. **Fan out.** Dispatch the bundle to each enabled council member via
+   `scripts/ai_council/orchestrator.py`. Each member receives the
+   neutrality preamble from `prompts.py` plus the artefact — nothing
+   from the host agent's prior reasoning.
+5. **Render results.** Stack each member's response under its own
+   provider-attributed heading. Never merge or paraphrase responses
+   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.
+
+## Output format
+
+Every council reply MUST contain, in this order:
+
+1. **Header line** with mode, member count, and total token cost.
+2. **One section per member**, titled `### <provider> · <model>`,
+   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.
+
+## Do NOT
+
+- Do NOT paraphrase council output into the host agent's voice — strip
+  attribution and you've stripped the value.
+- 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
+  ask for narrower scope.
+- Do NOT auto-spend tokens under `personal.autonomy: on` — the cost
+  gate fires every time, no exceptions.
+- Do NOT reuse SDK clients across invocations — re-load keys via
+  `load_*_key()` each call.
+
+## Gotchas
+
+Real failure modes seen in the wild:
+
+- **Bias-by-framing:** agent pastes "I think X is the right answer,
+  what do you think?" → council rubber-stamps. Symptom: 100%
+  convergence, zero unique insight. Fix: send artefact only, neutral
+  preamble, no host reasoning.
+- **Silent budget overrun:** `cost_budget_exceeded` mid-fan-out, agent
+  retries one member to "complete" the council. Result: skewed sample,
+  hidden spend. Fix: surface partial result, stop, ask user.
+- **Identity leak:** roadmap text contains "the agent decided…" —
+  reviewer infers host model and mirrors it. Fix: redact host-agent
+  identity strings before bundling.
+
+| Anti-pattern | Why it's wrong | Correct approach |
+|---|---|---|
+| "Pre-warm" the council with the agent's own analysis. | Bias attack — collapses the reviewer to a yes-man. | Send the artefact text only. |
+| Paste the host-agent identity ("I am Augment / Claude Code…") | Identity primes the reviewer's model. | Neutrality preamble in `prompts.py` already handles this. |
+| 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. |
+
+## Redaction expectations
+
+The bundler's redaction pass strips:
+
+- Paths matching `~/.config/agent-config/*.key`.
+- Lines starting with `Authorization:`.
+- `key = …`, `secret = …`, `token = …`, `password = …` assignments.
+- `sk-ant-…` and `sk-…` token-like strings.
+
+If your artefact contains other sensitive data (customer names,
+internal hostnames, contractual prose) you are responsible for
+scrubbing it before bundling. The redaction pass is a **floor**, not
+a ceiling.
+
+## Cost awareness
+
+Every consultation hits a paid API. The orchestrator enforces
+per-invocation caps from `ai_council.cost_budget`:
+
+- `max_input_tokens` / `max_output_tokens` — token caps across all members.
+- `max_total_usd` — per-invocation USD ceiling. `0` disables the USD ceiling (token caps still apply).
+- `max_calls` — maximum number of council members per invocation.
+- `daily_limit_usd` — rolling 24h spend cap across all `/council`
+  invocations. `0` disables. Persists in
+  `~/.config/agent-config/council-spend.jsonl` (mode 0600). Breach
+  fires `on_overrun(event)` with `event.breach_kind == "daily"` and,
+  if the callback returns False or is absent, tags the member
+  `daily_budget_exceeded` instead of `cost_budget_exceeded`.
+
+Prices come from `.agent-prices.md` (gitignored, refreshed weekly).
+The pricing module bootstraps it from `_default_prices.py` on first
+use and flags it stale when older than the most recent Monday 00:00
+UTC.
+
+### Pre-call estimate format
+
+Before the cost gate, compute `orchestrator.estimate(question, members,
+table)` and render a per-member table. Heuristic: `len(text) / 4` for
+input, member's `max_tokens` ceiling for output (actual spend is
+usually lower).
+
+> External council call — billable
+>
+> Mode: roadmap · Target: `agents/roadmaps/<name>.md` (~3 KB after redaction)
+>
+> | member                          | est. in / out tokens | est. USD |
+> |---------------------------------|---------------------:|---------:|
+> | anthropic / claude-sonnet-4-5   |      ~750 / 1024     |  $0.0176 |
+> | openai / gpt-4o                 |      ~750 / 1024     |  $0.0121 |
+> | **total**                       |                      | **$0.0297** |
+>
+> Budget: 50k in / 20k out tokens · USD ceiling: $0.50
+>
+> 1. Run the consultation
+> 2. Cancel
+
+### Stale price-table gate
+
+If `pricing.is_stale(table)` returns true, ask before proceeding:
+
+> Price table is stale (last_updated: YYYY-MM-DD)
+> 1. Refresh now (`python3 scripts/update_prices.py`)
+> 2. Continue with the stale table
+> 3. Cancel
+
+Do not silently auto-refresh — the user keeps control.
+
+### Mid-flow overrun callback (`on_overrun`)
+
+The orchestrator runs members **sequentially**. Before each member
+whose projected spend would breach a cap, it invokes the
+`on_overrun(event)` callback. The callback returns `True` to proceed
+with that member (raises the effective ceiling for THIS call only)
+or `False` to skip and record `cost_budget_exceeded`. The callback
+fires again for every subsequent breaching member — the user keeps
+control on each step.
+
+> Cost budget overrun — pausing before next member
+>
+> Member: openai / gpt-4o (member 2 of 2)
+> Already spent: ~620 in / ~480 out tokens · $0.0094
+> Next call estimate: ~750 in / 1024 out tokens · $0.0121
+> **Projected total after this call: $0.0215** (ceiling: $0.0150)
+>
+> 1. Continue with this member
+> 2. Skip this member (records `cost_budget_exceeded`, continues with the rest)
+
+Without `on_overrun`, breaching short-circuits all remaining members
+(v1 fallback). Do not retry silently. Surface the partial result and
+ask the user.
+
+## Multi-round debate (`rounds:N`)
+
+`consult(..., rounds=N)` enables 2-3 round critique loops. Round 1
+runs the standard single-round flow. Round 2+ rebuilds the user
+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.
+
+| Property | Behaviour |
+|---|---|
+| 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. |
+| Daily limit | Same — every billable round-2 call records spend in the rolling 24h ledger. |
+| Return value | Final round only. Use `on_round_complete(round_idx, responses)` to capture intermediate rounds for rendering. |
+
+> Iron Law: anonymisation is non-negotiable. If you ever need to
+> surface "which model said what" between rounds, that is a different
+> feature — debug-only, off by default, never enabled in user-facing
+> output. The neutrality contract dies the moment a member learns it
+> is talking to Claude vs GPT in round 2.
+
+Pre-call estimate must surface the round count: total = `N × single-round cost`. Render inline:
+
+```
+External council call — billable · 2 rounds
+Round 1: artefact only
+Round 2: artefact + anonymised round 1 critiques
+
+| member             | per-round | × 2     |
+|--------------------|----------:|--------:|
+| anthropic/sonnet   |   $0.0176 | $0.0352 |
+| openai/gpt-4o      |   $0.0121 | $0.0242 |
+| **total**          |           | $0.0594 |
+```
+
+## See also
+
+- `/council` command — the user-facing entry point.
+- `subagent-orchestration` skill — internal multi-agent variant (no
+  network, no spend, but no diversity of weights either).
+- `scripts/ai_council/prompts.py` — neutrality preamble + per-mode
+  system prompts.
+- `scripts/ai_council/bundler.py` — redaction pattern set + size
+  guard.
+- `docs/customization.md` § `ai_council.*` — settings reference.

package/.agent-src/skills/api-endpoint/SKILL.md

@@ -28,8 +28,8 @@ Do NOT use when:
 
 ### What to generate
 
-1. **Controller** — Single Action (invokable). Read `agents/docs/controller.md` and `.augment/guidelines/php/controllers.md`.
-2. **FormRequest** — Validation rules, `authorize()` via policies. Read `.augment/guidelines/php/validations.md`.
+1. **Controller** — Single Action (invokable). Read `agents/docs/controller.md` and `../../../docs/guidelines/php/controllers.md`.
+2. **FormRequest** — Validation rules, `authorize()` via policies. Read `../../../docs/guidelines/php/validations.md`.
 3. **Resource** — JSON response transformation. Read `agents/docs/api-resources.md`.
 4. **Route** — Add to the correct versioned route file.
 5. **Policy** — If authorization is needed.

package/.agent-src/skills/api-testing/SKILL.md

@@ -13,7 +13,7 @@ contract validation, response structure checks, or external service mocking.
 
 ## Procedure: Write API tests
 
-1. **Understand the endpoint** — Read controller, form request, existing tests. Understand expected behavior and edge cases before writing anything.
+1. **Understand the endpoint** — Read the controller, form request, and existing tests. Understand expected behavior, edge cases, and auth requirements before writing anything.
 2. **Set up test data** — Use seeders (preferred) or factories. Mock external services with `Http::fake()`.
 3. **Write test cases** — Cover success, validation errors, authorization failures, edge cases.
 4. **Assert response** — Check status code, JSON structure, data values. Use `assertJsonStructure()`.

package/.agent-src/skills/blade-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: blade-ui
-description: "Stack-implementation skill for Laravel Blade — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Blade. Covers views, components, partials, layouts, and view logic."
+description: "Use when the project's frontend stack is Blade — dispatched by `directives/ui/{apply,review,polish}.py`. Covers views, components, partials, layouts, and view logic."
 source: package
 ---
 

package/.agent-src/skills/blast-radius-analyzer/SKILL.md

@@ -81,7 +81,7 @@ For every dependency, mark:
 
 ### 5. Consult engineering memory
 
-Via [`memory-access`](../../guidelines/agent-infra/memory-access.md) call
+Via [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md) call
 `retrieve(types=["architecture-decisions", "ownership"],
 keys=<changed paths + changed symbol>, limit=5)`. Surface:
 

package/.agent-src/skills/bug-analyzer/SKILL.md

@@ -84,7 +84,7 @@ Gather all available evidence before forming any hypothesis:
 - Read each file in the call chain to understand the data flow.
 - Check existing context docs (`agents/contexts/`) for the affected area.
 - **Consult engineering memory.** Via
-  [`memory-access`](../../guidelines/agent-infra/memory-access.md) call
+  [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md) call
   `retrieve(types=["historical-patterns", "incident-learnings"],
   keys=[<error class>, <affected file paths>], limit=3)`. A prior
   matching pattern or incident is the single most reliable accelerator