@event4u/agent-config 2.12.0 → 2.13.0

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

@@ -292,6 +292,65 @@ NEVER ships the host verdict as council output. Provider attribution
 stays visible in the per-member sections; host verdicts stay
 attributed to the host.
 
+## Synthesis templates (lens-aware)
+
+The **Convergence / Divergence** slot in `council:render` output is
+populated with a lens-specific synthesis prompt. The host agent reads
+this prompt and writes the summary in the shape it dictates. The five
+templates live in `scripts/ai_council/prompts.py::_SYNTHESIS_TABLE`
+and are exposed via `synthesis_template(mode)`.
+
+**R4 Q4 split** — decision lenses get a structured Karpathy-style
+template; creative lenses stay open-ended prose (bare slot):
+
+| Lens | Class | Synthesis sections |
+|---|---|---|
+| `default` | decision | Agreement · Clashes · Blind spots · Recommendation · Next step |
+| `pr` | decision | Consensus · Conflicts · Must-fix before merge · Recommendation |
+| `analysis` | decision | Top-10 by consensus · Supporting · Outliers |
+| `design` | creative | *(no template — open prose passthrough)* |
+| `optimize` | creative | *(no template — open prose passthrough)* |
+
+Input modes (`prompt` / `roadmap` / `diff` / `files`) inherit the
+`default` decision template — they are bundling shapes, not lenses.
+
+**Source citations:**
+* Template shape — Round 2 council verdict
+  (`agents/council-sessions/2026-05-14-ai-council-redesign/round-1.md`,
+  Opus's lens-adaptive synthesis proposal).
+* Decision/creative split — Round 4 Q4 verdict
+  (`agents/council-sessions/2026-05-14-ai-council-redesign/round-3-responses.json`).
+  R4 reframed `optimize` as creative because perf trade-offs resist
+  pre-templated shape — Performance-wins / Trade-offs /
+  Implementation-order is too rigid for the variety of optimize-lens
+  artefacts. R4 reframed `design` for the same reason — design
+  critiques are inherently narrative.
+
+### `--prose-synthesis` escape hatch (R4 Q4)
+
+Both `council:run` and `council:render` accept symmetric escape-hatch
+flags on top of the lens table:
+
+* `--prose-synthesis` — force creative-lens passthrough (bare slot)
+  regardless of lens. Use when the user on `default`/`pr`/`analysis`
+  prefers a narrative recommendation over the structured template.
+* `--no-prose-synthesis` — force the `default` structured template
+  even on a creative lens. Use when a `design` or `optimize` artefact
+  has a one-shot need for Karpathy-style structure.
+
+The flag is mutually exclusive — picking one disables the other on
+the same invocation. When `council:run` records either flag in the
+output JSON, `council:render` honours it unless the renderer is
+called with an explicit flag of its own.
+
+### Renderer lens resolution
+
+`council:render <responses.json>` resolves the active lens in this
+order: explicit `--prompt-mode` flag > `prompt_mode` field in the
+payload > `mode` field in the payload > `None` (default decision
+template). The `--prose-synthesis` / `--no-prose-synthesis` flag
+overrides the table regardless of how the lens resolved.
+
 ## Do NOT
 
 - Do NOT paraphrase council output into the host agent's voice — strip
@@ -435,8 +494,8 @@ 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
+The default round count comes from `defaults.min_rounds` in
+`agents/.ai-council.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
@@ -516,6 +575,121 @@ 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.
 
+### `/council debate` sub-command (progressive disclosure)
+
+`/council debate <artefact> [--rounds N] [--continue-as-debate <session>]`
+runs an **interactive** multi-round critique with a confirmation gate
+between every round so the user can stop the spend at any point.
+
+| Property | Behaviour |
+|---|---|
+| Round flow | Same orchestrator as `rounds:N` (`run_debate()`), but each round prints its responses then pauses on a y/n prompt before launching the next round. |
+| Cost gate | After every round the CLI prints `Spent so far: $X · Next round: ~$Y · Cap: $Z`. `n` exits cleanly with partial results; `y` continues. |
+| Hard cap | If the projected next-round cost would breach `max_total_usd`, `run_debate()` raises `DebateCapExceeded` and the CLI exits with the partial transcript. No silent overrun. |
+| `--continue-as-debate` | Seeds round 1 from an existing `/council default` (or analysis lens) session. No round-1 API calls are billed; round 2+ run normally. Member list must match. |
+| Session files | One file per round under `agents/council-sessions/<slug>/debate-round-NN.md`. |
+| Anonymisation | Identical to `rounds:N`. The continue-as-debate path also anonymises the seeded round-1 responses when building the round-2 prompt. |
+
+Use this when the artefact is genuinely contentious and the user
+wants to control depth interactively. For a fire-and-forget
+multi-round run, prefer `consult(..., rounds=N)` or `--rounds N` on
+`/council default`.
+
+
+## Karpathy peer-review (opt-in)
+
+After the final deliberation round, an optional **anonymous peer-review
+pass** lets each member critique the *other* members' responses for
+blind spots before synthesis. Inspired by Andrej Karpathy's "ask the
+strongest models to review each other anonymously" pattern; see his
+[talks / threads on inter-model critique](https://karpathy.ai/) and the
+internal verdict in
+`agents/council-sessions/2026-05-14-ai-council-redesign/round-2.md`
+(R2 split: one approve-as-flag, one reject-as-default → opt-in only).
+
+Pipeline order when every feature is active:
+
+```
+deliberation rounds → peer-review → consensus-scoring → synthesis
+```
+
+Activation — two equivalent paths:
+
+* CLI: `--peer-review` on `council:estimate` or `council:run`.
+* Config: `ai_council.peer_review.enabled: true` in
+  `agents/.ai-council.yml`. Default is `false`.
+
+Mechanics:
+
+1. The final deliberation round's outputs are anonymised into
+   `Response-A`, `Response-B`, … in stable input order. Provider /
+   model identity is stripped (Iron-Law neutrality holds); empty or
+   errored deliberation responses are skipped.
+2. Each member receives an N−1 view (its own response filtered out)
+   plus the Karpathy prompt: *strongest response*, *weakest blind
+   spot*, *what did everyone miss*, *refinement*.
+3. The N critiques flow back into synthesis through a
+   "Peer-Review-Surfaced Blind Spots" addendum on the lens template.
+4. **Advisor preserve-persona (R4 Q3, hard-coded):** when the
+   deliberation was an advisor-mode run (Phase 6), anonymisation
+   strips provider identity but **preserves the advisor persona
+   label**. Peer-review renders as `Response A (Contrarian)`, never
+   `Response A (Anthropic Opus)`. Plain-member runs strip identity
+   entirely.
+
+Cost — adds exactly N billable calls (one per member) at the same
+per-call cost as a deliberation call. The `council:estimate` table
+surfaces the delta as a `+peer-review: +N calls (~+$X)` row.
+
+Needs ≥ 2 distinct deliberation outputs; below that the round is a
+no-op and nothing extra is billed. Self-review is structurally
+impossible — a member never sees its own response.
+
+## Thinking-style advisors (replace-mode)
+
+Phase 6 introduces five **advisor personas** the council adopts in
+*replace-mode*: an enabled advisor substitutes its bound member's
+plain call with the same provider running the advisor's persona
+prompt. Total call count stays the same — only the system prompt
+swaps.
+
+| Advisor | Default bound member | Focus |
+|---|---|---|
+| **Contrarian** | `anthropic` | strongest counterargument, hidden assumptions |
+| **First-Principles** | `anthropic` | strip metaphor, derive from physics / math / cost |
+| **Expansionist** | `openai` | adjacent opportunities, second-order effects |
+| **Outsider** | `openai` | naive-but-sharp questions, beginner's-mind probes |
+| **Executor** | `anthropic` | what ships this quarter, what blocks delivery |
+
+Activation — edit `agents/.ai-council.yml` and flip the advisor's
+`enabled: true`. Optional `model: <name>` overrides the bound
+member's default model. An advisor referencing a disabled member
+fails closed at config load — never silently skipped.
+
+```yaml
+advisors:
+  contrarian:
+    enabled: true        # ← swap anthropic's plain call for contrarian
+    member: anthropic
+    # model: claude-opus-4   # optional pin
+```
+
+`council:estimate` surfaces every active swap on a dedicated line
+above the cost table:
+
+```
+council:estimate · mode=prompt · members=2 (billable=2)
+  advisor: Contrarian on anthropic via claude-sonnet-4-5
+anthropic/claude-sonnet-4-5: ~991 in + 256 out  =  $0.0068
+openai/gpt-4o: ~208 in + 256 out  =  $0.0031
+```
+
+Cost-bounded — replace-mode never adds calls. The persona prompt is
+larger than plain (~1k extra input tokens per swap); output tokens
+and call count are unaffected. Peer-review preserves the advisor
+label while stripping provider identity (`Response A (Contrarian)`).
+Two enabled advisors on the same member is a config error.
+
 ## See also
 
 - `/council` command — the user-facing entry point.
@@ -523,6 +697,10 @@ orchestrator-level rounds.
   network, no spend, but no diversity of weights either).
 - `scripts/ai_council/prompts.py` — neutrality preamble + per-mode
   system prompts.
+- `scripts/ai_council/advisors.py` — replace-mode planning + persona
+  resolution.
 - `scripts/ai_council/bundler.py` — redaction pattern set + size
   guard.
 - `docs/customization.md` § `ai_council.*` — settings reference.
+- `docs/contracts/ai-council-config.md` § advisors — schema + precedence
+  contract.

package/.agent-src/skills/copilot-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: copilot-config
-description: "Use when configuring GitHub Copilot — copilot-instructions.md, PR review patterns, output optimization — even when the user just says 'tune Copilot' or 'why is Copilot commenting on X'."
+description: "Tune the GitHub Copilot AI — `copilot-instructions.md`, PR-review patterns, suggestion behavior, output verbosity. NOT for dev-environment setup (use `devcontainer`)."
 source: package
 domain: process
 ---

package/.agent-src/skills/devcontainer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: devcontainer
-description: "Use when configuring DevContainers or GitHub Codespaces — devcontainer.json, custom images, secrets, VS Code features — even when the user just says 'why does my Codespace not start'."
+description: "Wire up DevContainers / GitHub Codespaces — `devcontainer.json`, container images, secrets, VS Code features, port forwarding. NOT for tuning Copilot itself (use `copilot-config`)."
 source: package
 domain: devops
 ---

package/.agent-src/skills/laravel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: laravel
-description: "Writes Laravel code following framework conventions, project architecture, and modern best practices for controllers, requests, services, jobs, events, policies, and application structure."
+description: "Writes Laravel PHP — Eloquent, Artisan controllers, FormRequests, jobs, events, policies, providers. For Symfony / Doctrine use `symfony-workflow`. For framework-free PHP use `php-coder`."
 source: package
 domain: engineering
 ---

package/.agent-src/skills/project-analysis-core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project-analysis-core
-description: "Use for the universal deep-analysis workflow: project discovery, version resolution, docs loading, architecture mapping, execution flow, and package research."
+description: "Raw discovery primitives — project discovery, version resolution, docs loading, architecture mapping, execution flow. Called by `universal-project-analysis`. Single-pass scan → `project-analyzer`."
 source: package
 domain: discovery
 ---

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

@@ -1,6 +1,6 @@
 ---
 name: project-analyzer
-description: "ONLY when user explicitly requests: full project analysis, tech stack detection, or structured analysis documents for agents/analysis/. NOT for regular feature work."
+description: "ONLY when user asks for single-pass tech-stack detection or `agents/analysis/` write-up. Deep multi-pass audit → `universal-project-analysis`. Raw primitives → `project-analysis-core`."
 source: package
 domain: discovery
 ---

package/.agent-src/skills/symfony-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: symfony-workflow
-description: "Writes Symfony code following framework conventions, container wiring, and modern best practices for controllers, services, bundles, Messenger, Doctrine, security, and console commands."
+description: "Writes Symfony PHP — DI container, bundles, Doctrine, Messenger, Security voters, console commands. For Laravel / Eloquent / Artisan use `laravel`. For framework-free PHP use `php-coder`."
 source: package
 domain: engineering
 ---

package/.agent-src/skills/universal-project-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: universal-project-analysis
-description: "ONLY when user explicitly requests: full project analysis, deep codebase audit, or comprehensive architecture review. Routes to core and framework-specific analysis skills."
+description: "ONLY when user asks for deep multi-pass codebase audit — orchestrator routing to `project-analysis-core` + framework-specific `project-analysis-*`. Single-pass scan → `project-analyzer`."
 source: package
 domain: discovery
 ---

package/.agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.py (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "2.8.0"
+agent_config_version: "2.12.0"
 
 # --- Project identity ---
 project:

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "2.12.0",
+    "version": "2.13.0",
     "keywords": [
       "agent-config",
       "skills",
@@ -105,6 +105,8 @@
         "./.claude/skills/copilot-config",
         "./.claude/skills/cost-report",
         "./.claude/skills/council",
+        "./.claude/skills/council-analysis",
+        "./.claude/skills/council-debate",
         "./.claude/skills/council-default",
         "./.claude/skills/council-design",
         "./.claude/skills/council-optimize",

package/AGENTS.md

@@ -18,7 +18,7 @@ task ci                # full pipeline — green before PR
 
 - **Package self-orientation** (beta) — identity, four-wing cognition map, repo layout, tech stack, key-rules table, telemetry, command-suggester: [`docs/contracts/package-self-orientation.md`](docs/contracts/package-self-orientation.md).
 - **Kernel + Router** (beta) — 9 always-loaded Iron-Law rules, tier-1 / tier-2 routing, cost profiles, per-rule char caps enforced by `task lint-rule-budget`: [`kernel-membership`](docs/contracts/kernel-membership.md) + [`rule-router`](docs/contracts/rule-router.md).
-- **Content pipelines** — A [compression](docs/architecture/compression.md), B [Augment projection](docs/architecture/augment-projection.md), C [multi-tool projection](docs/architecture/multi-tool-projection.md), D [Claude.ai bundle](docs/architecture/claude-bundle.md). Index: [`docs/architecture.md`](docs/architecture.md).
+- **Content pipelines** — A [source projection](docs/architecture/source-projection.md), B [Augment projection](docs/architecture/augment-projection.md), C [multi-tool projection](docs/architecture/multi-tool-projection.md), D [Claude.ai bundle](docs/architecture/claude-bundle.md). Index: [`docs/architecture.md`](docs/architecture.md).
 - **Editing this repo** — Iron-Law rules (portability, source-of-truth, skill-quality) + Thin-Root contract: [`augment-portability`](.agent-src/rules/augment-portability.md), [`augment-source-of-truth`](.agent-src/rules/augment-source-of-truth.md), [`skill-quality`](.agent-src/rules/skill-quality.md), [`agents-md-thin-root`](.agent-src/skills/agents-md-thin-root/SKILL.md).
 - **Consumer story** — `npx` + `scripts/install.sh` + `.agent-settings.yml` opt-in flags, sandbox/offline install paths, verified-offline manifest: [`README.md`](README.md).
 - **Personas** — 11 review-lens cast (6 core · 5 specialist), `personas:` vs `/mode` axes, citation map, override pattern: [`docs/personas.md`](docs/personas.md), schema [`docs/contracts/persona-schema.md`](docs/contracts/persona-schema.md) (beta).

package/CHANGELOG.md

@@ -429,6 +429,53 @@ our recommendation order, not its support status.
 > that forces a new era split (`# Era: 2.8.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [2.13.0](https://github.com/event4u-app/agent-config/compare/2.12.0...2.13.0) (2026-05-14)
+
+### Features
+
+* **council:** Phase 7 — debate orchestration + CLI wiring ([647a3f0](https://github.com/event4u-app/agent-config/commit/647a3f07698792f41beb7413600d54b2321f4a96))
+* **council:** Phase 7 — /council debate sub-command files ([abbd436](https://github.com/event4u-app/agent-config/commit/abbd43666b7e2c704ab3c46f2901f01eae446139))
+* **council:** Phase 6 — thinking-style advisor personas ([21c8b88](https://github.com/event4u-app/agent-config/commit/21c8b88310a2a65d7ea9082da085d023f813d114))
+* **council:** Phase 5 — Karpathy peer-review opt-in flag ([bce381a](https://github.com/event4u-app/agent-config/commit/bce381ae9c412abf501473fa4154f91d9c0befbf))
+* **council:** analysis lens + lens-adaptive synthesis + consensus scoring ([6d7136a](https://github.com/event4u-app/agent-config/commit/6d7136ad6be31b7627a332600a7623f2cd929e76))
+* **council:** add config loader, overlay, and 3 new provider clients ([0cb5591](https://github.com/event4u-app/agent-config/commit/0cb55914457a62b6f57744d8c8dac16bf777921d))
+* **council:** introduce agents/.ai-council.yml as single source of truth ([043c2d2](https://github.com/event4u-app/agent-config/commit/043c2d23445f2ef7ad8aee880dc83d97c347635f))
+* **governance:** Phase 5 — roadmap trajectory metric + architectural-consensus ADR ([926a632](https://github.com/event4u-app/agent-config/commit/926a63237c3dbe1fcfd7df05c9230809382d8790))
+* **projection:** Phase 4 + 1.4 — multi-tool projection fidelity contract + ci-strict gate ([e18e4ad](https://github.com/event4u-app/agent-config/commit/e18e4ad73595e17889009b0123ebd000254c165b))
+* **routing:** Phase 3 — tighten skill descriptions + 4 tier-3 routing rules for failing clusters ([2a11c70](https://github.com/event4u-app/agent-config/commit/2a11c70b274741e7d98fd814ac39c1d05a1a38c9))
+* **governance:** Phase 1 — credibility (CONTRIBUTING preface, source-projection rename, archive 7 migration scripts) ([2e5cfe0](https://github.com/event4u-app/agent-config/commit/2e5cfe02e1b5f4218d1283108796b0ce43fd9165))
+
+### Bug Fixes
+
+* **docs:** drop transient council-sessions citation from multi-tool-projection ([55dbbb1](https://github.com/event4u-app/agent-config/commit/55dbbb1e599aae2d913dc56a05c9dab0014e2739))
+* **linter:** treat ../docs/contracts/ links as out-of-scope like guidelines ([a2249b0](https://github.com/event4u-app/agent-config/commit/a2249b02b70233e2b13ccf3efeda4188686b6181))
+* **routing:** strip transient roadmap citation from tier-3 routing rules ([2cf745c](https://github.com/event4u-app/agent-config/commit/2cf745cad9beb40c4e6e9eb7f97abbc58a94d9de))
+
+### Documentation
+
+* **roadmap:** rename "rule" to "invariant" for deep_min_rounds reference ([758ea46](https://github.com/event4u-app/agent-config/commit/758ea46568c23ef5518ff61d80700f7559bc54a1))
+* **ai-council:** sync compressed SKILL.md with Phase 6 advisors section ([6d57034](https://github.com/event4u-app/agent-config/commit/6d57034c7b342abdd5d38ff300fa67c51deb3471))
+* **council:** document master/wrapper contract for the council cluster ([7346f34](https://github.com/event4u-app/agent-config/commit/7346f34376b48c02ced3ae939dfff6ea215025ba))
+
+### Tests
+
+* **ai-council:** Phase 8 — negative-test backfill for config loader ([cc3a08c](https://github.com/event4u-app/agent-config/commit/cc3a08c360c94685f9a1efaaa57f84001f78788c))
+
+### Chores
+
+* **roadmaps:** archive step-2-ai-council-consolidation — all phases + ACs done ([c7f0c9c](https://github.com/event4u-app/agent-config/commit/c7f0c9ca7ac300023c5da0b939e0c63554dbcfed))
+* **docs:** bump getting-started command count 106 -> 108 after council debate sub-command ([5e256d7](https://github.com/event4u-app/agent-config/commit/5e256d79d3eea3046900e8afa5be64526b4fc61d))
+* **roadmaps:** retag complexity from "medium" to lint-valid values ([4c5457e](https://github.com/event4u-app/agent-config/commit/4c5457e271f8dcdc03943bac7adff84455388615))
+* regenerate index + catalog for council-debate skill ([3c365a3](https://github.com/event4u-app/agent-config/commit/3c365a375da22f16f97829677c875500e40d436a))
+* **roadmap:** mark Phases 6-7 of step-2-ai-council-consolidation complete ([7e8e557](https://github.com/event4u-app/agent-config/commit/7e8e557505bbf88b486605980a7f5ee2f97bcbb4))
+* **roadmap:** mark Phases 1-4 of step-2-ai-council-consolidation complete ([101a5cf](https://github.com/event4u-app/agent-config/commit/101a5cf70d4fc694f85a270b2bebfb8fe545833a))
+* **roadmap:** mark Phase 0 of step-2-ai-council-consolidation complete ([4fa2734](https://github.com/event4u-app/agent-config/commit/4fa27346c8faad54de582757ce5cfe7216041bda))
+* **template:** bump agent_config_version pin to 2.12.0 ([e5c41fd](https://github.com/event4u-app/agent-config/commit/e5c41fd433105359d6e36b03b0de62415be212f0))
+* regenerate agents/index.md + docs/catalog.md after rule additions ([b7fa4b6](https://github.com/event4u-app/agent-config/commit/b7fa4b6e25cbc55d8b3197f815c00530bd1eee79))
+* **roadmap:** archive completed step-1-v2-feedback-followup (20/20 done) ([88a07ea](https://github.com/event4u-app/agent-config/commit/88a07ea9a983f0b63710e5461c8fddee36b2d378))
+
+Tests: 3868 (+150 since 2.12.0)
+
 ## [2.12.0](https://github.com/event4u-app/agent-config/compare/2.11.0...2.12.0) (2026-05-14)
 
 ### Features

package/CONTRIBUTING.md

@@ -3,6 +3,11 @@
 Thanks for considering a contribution to `event4u/agent-config`. This file
 describes how to propose changes and what the package's conventions are.
 
+> **This project is currently single-maintainer (`matze4u`).** Contributions
+> are welcome; expect direct review and potentially slower response than
+> multi-maintainer projects. The process below describes the target workflow
+> as the contributor base grows.
+
 ## Status and scope
 
 The package is maintained by a small team at event4u:

package/README.md

@@ -7,7 +7,7 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
 > Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).
 
 <p align="center">
-  <strong>210 Skills</strong> · <strong>61 Rules</strong> · <strong>106 Commands</strong> · <strong>72 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>210 Skills</strong> · <strong>65 Rules</strong> · <strong>108 Commands</strong> · <strong>72 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -524,7 +524,7 @@ kernel set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-member
 | [`/jira-ticket`](.agent-src/commands/jira-ticket.md) | Read ticket from branch, implement feature |
 | [`/compress`](.agent-src/commands/compress.md) | Compress skills for token efficiency |
 
-→ [Browse all 106 active commands](.agent-src/commands/)
+→ [Browse all 108 active commands](.agent-src/commands/)
 
 ---
 
@@ -556,7 +556,7 @@ slash-commands) &nbsp; 📌 = informational marker only (no auto-discovery
 or manual wiring required)
 
 > **What this means in practice:** Claude Code gets the full project-scoped
-> package (rules + 210 skills + 106 native commands); Augment Code gets the
+> package (rules + 210 skills + 108 native commands); Augment Code gets the
 > same content but only from a single global install at `~/.augment/`.
 > Cursor, Cline, Windsurf, Gemini CLI, GitHub Copilot, Roo Code, Codex CLI,
 > and Continue.dev only get the **rules** natively; skills and commands are

package/config/agent-settings.template.yml

@@ -232,100 +232,12 @@ worktrees:
 
 # --- AI Council (external second-opinion network) ---
 #
-# When enabled, the /council command lets the agent poll independent
-# external models (OpenAI, Anthropic) for a neutral critique of a
-# roadmap, diff, prompt, or file set. Council members never see the
-# host agent's reasoning — only the artefact + a neutral system prompt.
+# Configuration moved to `agents/.ai-council.yml` as of the Step-2
+# consolidation roadmap. Consumer projects opt in by copying the
+# reference file from the package (`agents/.ai-council.yml`) into their
+# own `agents/` tree and flipping `enabled: true` per provider.
 #
-# Tokens are NEVER stored here. They live in ~/.event4u/agent-config/
-# <provider>.key (mode 0600; legacy ~/.config/agent-config/<provider>.key
-# is read as a fallback), installed via:
-#   bash scripts/install_anthropic_key.sh
-#   bash scripts/install_openai_key.sh
-#
-# Cost note: every consultation makes real, paid API calls. The
-# autonomy directive does NOT silently spend tokens — the /council
-# command always asks before invoking, even under autonomy: on.
-ai_council:
-  # Master switch (true, false). Default false — installing a key is
-  # not the same as wanting the agent to spend money on it.
-  enabled: false
-
-  # Default transport mode for every member (overridable per-member
-  # below, and per-invocation via `/council mode:<x>`).
-  #
-  #   api    = direct SDK call against the provider's API (billable).
-  #   manual = copy-paste loop, user is the transport (free).
-  #
-  # Precedence: invocation flag > per-member mode > global mode > "manual".
-  mode: "manual"
-
-  # Per-member configuration. Set enabled=true on the providers you want
-  # to consult. The model field selects which model receives the query.
-  # Optional `mode:` overrides the global setting for that member only.
-  members:
-    anthropic:
-      enabled: false
-      model: "claude-sonnet-4-5"
-      # mode: "api"      # uncomment to override ai_council.mode
-    openai:
-      enabled: false
-      model: "gpt-4o"
-      # mode: "manual"   # uncomment to override ai_council.mode
-
-  # Default number of debate rounds per /council invocation.
-  #
-  # Round 1 sees the artefact alone. Round 2+ sees the artefact plus
-  # anonymised critiques from the previous round (provider/model
-  # identity stripped per the neutrality Iron Law). Applies identically
-  # to api and manual transports — manual mode runs round 1 across all
-  # members, the host agent consolidates, then round 2 starts with the
-  # anonymised round-1 critiques folded in.
-  #
-  # Default is 2 so council members critique each other at least once
-  # before convergence. The agent does NOT ask "how many rounds?" when
-  # the requested rounds <= min_rounds; pass `rounds:N` on the
-  # invocation (or `--rounds N` to the CLI) to override.
-  min_rounds: 2
-
-  # Higher floor for deep-reasoning artefacts (architecture review,
-  # refactoring proposals, bug-diagnosis runs). Activated when the
-  # consuming rule, skill, or command declares `council_depth: deep`
-  # in its frontmatter, or the user passes `--depth deep` to the CLI.
-  # Effective rounds = max(deep_min_rounds, min_rounds), so this floor
-  # is monotonic — lowering it below `min_rounds` has no effect.
-  # Standard tasks keep `min_rounds`; cost rises only when an artefact
-  # opts in. Set to `min_rounds` to disable the deep tier.
-  deep_min_rounds: 3
-
-  # Per-member output-token budget passed to every API call. The CLI
-  # `--max-tokens` flag overrides this on a single invocation; the
-  # cost estimator uses the same value as its worst-case ceiling.
-  # `0` means "unlimited" — internally widened to the safe provider
-  # ceiling (16384) because Anthropic rejects max_tokens=0. Raise
-  # explicitly past 16384 only when a model genuinely supports more
-  # and you want longer answers.
-  max_output_tokens: 2048
-
-  # Hard cost ceiling per /council invocation. The orchestrator pauses
-  # before any member whose projected spend would breach a cap and asks
-  # the user to continue. `max_total_usd: 0` disables the USD ceiling
-  # (token caps still apply). Total spend = rounds * single-round cost.
-  #
-  # Prices come from `agents/.agent-prices.md` (gitignored, refreshed weekly
-  # by `python3 scripts/update_prices.py`; bootstrapped from
-  # scripts/ai_council/_default_prices.py on first run).
-  cost_budget:
-    max_input_tokens: 50000
-    max_output_tokens: 20000
-    max_calls: 10
-    max_total_usd: 0.50
-
-  # Retention for council artefacts. Files older than this in
-  # `agents/council-{questions,responses,sessions}/` are pruned
-  # automatically on the next `save()` and on `task council-prune`.
-  # `0` disables pruning (keep forever — disk grows unbounded).
-  session_retention_days: 7
+# See `docs/contracts/ai-council-config.md` for the schema.
 
 # --- Onboarding ---
 #

package/docs/architecture/multi-tool-projection.md

@@ -61,6 +61,56 @@ removes `.cursor/` on next `task generate-tools`.
 | Stale `.windsurfrules` after rule rename | concatenation cache | `task clean-tools && task generate-tools` |
 | Gemini CLI reads outdated content | `AGENTS.md` changed without re-symlink | `task generate-tools` |
 
+## Per-tool projection size
+
+The previous "0.45 % reduction" headline was a wrong-boundary
+measurement: that figure compares `.agent-src.uncompressed/` to
+`.agent-src/`, but the pipeline's claimed function is *projection*, not
+byte compression. The table below is produced by
+[`scripts/measure_projection_bytes.py --regenerate`](../../scripts/measure_projection_bytes.py)
+with every tool ID temporarily enabled in `.agent-tools.yml`.
+
+| Surface | Files | Symlinks | Bytes materialized | Method |
+|---|---:|---:|---:|---|
+| `.agent-src.uncompressed/` | 596 | 0 | 3,253,997 | verbose source (input) |
+| `.agent-src/` | 596 | 0 | 3,242,579 | source projection (path-rewrite + `.npmignore`) |
+| `.augment/` | 61 | 7 | 136,146 | Augment Code — copies (rules) + symlinks (skills/cmds) |
+| `.claude/` | 0 | 395 | 0 | Claude Code — pure symlinks |
+| `.cursor/` | 61 | 189 | 124,741 | Cursor — per-rule `.mdc` materialized + symlinks |
+| `.clinerules/` | 0 | 61 | 0 | Cline — pure symlinks |
+| `.windsurf/` | 61 | 106 | 125,010 | Windsurf — per-rule wave-8 `.md` + symlinks |
+| `.windsurfrules` | 1 | 0 | 114,263 | Windsurf legacy — concatenated single file |
+| `GEMINI.md` | 0 | 1 | 0 | Gemini CLI — symlink → `AGENTS.md` |
+
+**What the pipeline optimises**
+
+- **Format fidelity** — each tool receives content in the format its host
+  reads natively (Cursor `.mdc` frontmatter, Windsurf Wave-8 frontmatter,
+  Claude / Cline symlinked into the source tree, Gemini single-file).
+- **Path stability** — surface paths match the host vendor's
+  documentation so users opt in by enabling the tool, not by remapping.
+- **Materialization minimization** — pure-symlink tools (`.claude/`,
+  `.clinerules/`, `GEMINI.md`) contribute zero bytes; tools that need a
+  format transform materialize only the transformed rule files.
+
+**What the pipeline does not optimise**
+
+- **Raw byte count** — `.cursor/` and `.windsurf/` *grow* the on-disk
+  footprint by ~125 KB each because their host formats require
+  per-rule frontmatter that cannot be supplied via symlink alone.
+  `.windsurfrules` materializes the rule set a second time as a
+  concatenated single file for users who prefer that surface.
+- **Source dedup** — the same rule body appears in `.agent-src/rules/`
+  *and* in every tool's materialized projection. This is intentional:
+  removing the duplication would push format conversion into runtime.
+
+Re-run the measurement after every change to the projection logic:
+
+```bash
+python3 scripts/measure_projection_bytes.py --regenerate
+python3 scripts/measure_projection_bytes.py --json    # CI-friendly
+```
+
 ## Proving the pipeline
 
 - [`tests/test_modern_editor_formats.py`](../../tests/test_modern_editor_formats.py)
@@ -68,5 +118,8 @@ removes `.cursor/` on next `task generate-tools`.
   frontmatter; runs only when `task generate-tools` has been executed.
 - [`tests/test_compress.py`](../../tests/test_compress.py) — covers
   the shared compress / generate-tools entrypoint and `_filter_tool_dirs`.
+- [`scripts/measure_projection_bytes.py`](../../scripts/measure_projection_bytes.py)
+  — per-tool byte / file / symlink count; the per-tool-size table above
+  is its output.
 
 ← [Architecture overview](../architecture.md)

package/docs/architecture/{compression.md → source-projection.md}

@@ -1,7 +1,25 @@
-# Pipeline A — Compression
+# Pipeline A — Source projection
 
-> **Scope:** transform verbose authoring source into the token-efficient
-> distribution payload that ships in the npm package.
+> **Scope:** transform verbose authoring source into the deterministic
+> distribution payload that ships in the npm package. The pipeline does
+> path-rewriting, `.npmignore`-style filtering, hash-tracking, and (on
+> selected files) caveman-style prose compression. The *primary* function
+> is the source-to-dist projection itself; raw byte reduction is small
+> (~0.35 % on the source/dist boundary: 3,253,997 B → 3,242,579 B across
+> 596 files) because most files are 1:1-projected with only frontmatter
+> and link rewrites. Per-tool size at the downstream projection
+> boundaries (`.augment/`, `.claude/`, `.cursor/`, `.windsurf/`,
+> `.clinerules/`, `.windsurfrules`, `GEMINI.md`) is measured separately
+> — see [`multi-tool-projection.md § Per-tool projection size`](multi-tool-projection.md#per-tool-projection-size)
+> for the table produced by [`scripts/measure_projection_bytes.py`](../../scripts/measure_projection_bytes.py).
+
+> **Historical note.** This pipeline was previously labelled
+> "Compression". Renamed in the v2.10.0 feedback follow-up after the
+> council pointed out that the dominant function is projection, not
+> byte compression. The script names (`scripts/compress.py`,
+> `scripts/compress.sh`) are kept for now to avoid a large blast-radius
+> refactor; the prose-compression sub-step (and the `/compress` slash
+> command for caveman text compression) still earn the legacy name.
 
 ## Input → Transform → Output