@event4u/agent-config 2.11.0 → 2.13.0

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

@@ -3,6 +3,7 @@ name: skill-writing
 description: "Use when deciding 'should this be a skill or a rule?', creating/improving/reviewing agent skills, SKILL.md frontmatter, or procedure sections — even without saying 'skill-writing'."
 source: project
 domain: process
+meta_skill: true
 ---
 
 # skill-writing
@@ -62,22 +63,25 @@ Ask: **"Does the model need this to do its job correctly?"**
 
 ### Skills and commands share the `.claude/skills/` namespace
 
-Skills (`.agent-src.uncompressed/skills/{name}/SKILL.md`) AND commands
-(`.agent-src.uncompressed/commands/{name}.md`) both project into
-`.claude/skills/` (`scripts/compress.py` → `generate_claude_skills` +
-`generate_claude_commands`). Claude treats the directory as native
-skills.
-
-* Same-name collision: skill wins, command is skipped
-  (`generate_claude_commands` honors this). Don't reuse a command's
-  slug for a skill unless the command should retire.
-* Both compete on `description` for routing. A weak skill description
-  is shadowed by a stronger same-domain command — and vice versa.
-  Trigger phrasing must be precise (§ 1b below).
-* Workflow has both "user types `/foo`" path AND "model picks this up
-  from intent" path → author the skill first, let the command delegate
-  via `skills:` frontmatter. Two artifacts with the same trigger
-  surface fight each other in the router.
+Skills in `.agent-src.uncompressed/skills/{name}/SKILL.md` AND commands in
+`.agent-src.uncompressed/commands/{name}.md` both project into
+`.claude/skills/` (see `scripts/compress.py` →
+`generate_claude_skills` + `generate_claude_commands`). Claude treats
+the whole directory as native skills.
+
+Implications for skill authors:
+
+* If a same-name command already exists, the skill takes priority and
+  the command is skipped (`generate_claude_commands` honors this).
+  Don't reuse a command's slug for a skill unless the command should
+  retire.
+* Both artifacts compete on `description` for routing. A weak skill
+  description is shadowed by a stronger same-domain command — and vice
+  versa. Make trigger phrasing precise (§ 1b below).
+* When the workflow has both a "user types `/foo`" path AND a "model
+  picks this up from intent" path, author the skill first and let the
+  command delegate (`skills:` frontmatter). Two artifacts with the same
+  trigger surface fight each other in the router.
 
 ### When "Nothing" is the right answer
 
@@ -263,6 +267,87 @@ Example:
 * K7: Created with analysis (not blind, expected behavior defined)
 * Size: Within limits (see size-and-scope guideline)
 
+### 7. Run + iterate evals (quantitative loop)
+
+Triggers (`evals/triggers.json`) check **routing**. A separate
+`evals/evals.json` checks **behavior** — does the skill make the agent
+produce a better answer than baseline? Add this layer for any skill
+where the procedure has measurable output (commands, artifacts,
+structured text). Skip for evergreen heuristics with no falsifiable
+output (e.g. `direct-answers`, `language-and-tone`) unless the user
+asks for it.
+
+**Workspace layout** (all under `.gitignore`):
+
+```
+.agent-src.uncompressed/skills/{name}/evals/
+  triggers.json              # tracked — routing eval (§ 1c)
+  evals.json                 # tracked — behavior eval definitions
+  runs/                      # gitignored — per-iteration outputs
+    {timestamp}-baseline/    # sub-agent run without the skill
+    {timestamp}-with-skill/  # sub-agent run with the skill
+    {timestamp}-benchmark.json
+```
+
+**`evals.json` shape** — 3–10 scenarios, each with prompt + grading
+rubric:
+
+```json
+{
+  "skill": "{name}",
+  "scenarios": [
+    {
+      "id": "happy-path",
+      "prompt": "<full user-shaped task that exercises the skill>",
+      "assertions": [
+        {"kind": "contains", "value": "<expected substring in output>"},
+        {"kind": "file_exists", "path": "<artifact path the skill should create>"},
+        {"kind": "rubric", "criterion": "<one-line judgement, e.g. 'output includes a numbered procedure'>"}
+      ]
+    }
+  ]
+}
+```
+
+`contains` / `file_exists` grade deterministically. `rubric` items grade
+via a fresh sub-agent reading the output against the criterion — keep
+each criterion to one falsifiable sentence.
+
+**Loop** (orchestrated by `scripts/run_skill_evals.py`):
+
+1. **Scaffold** — `python3 scripts/run_skill_evals.py scaffold {skill}`
+   creates `runs/{timestamp}-{baseline,with-skill}/` and seeds each
+   scenario's `meta.json`.
+2. **Baseline run** — spawn one sub-agent per scenario **without** the
+   skill loaded. Capture stdout + any artifacts into
+   `runs/{timestamp}-baseline/{scenario-id}/`.
+3. **With-skill run** — same scenarios, same sub-agent harness, **with**
+   the skill loaded. Capture into `runs/{timestamp}-with-skill/{scenario-id}/`.
+4. **Grade** — for each scenario, write a `grade.json` file with
+   per-assertion pass/fail. Deterministic assertions auto-grade;
+   rubric assertions need a grader sub-agent.
+5. **Aggregate** — `python3 scripts/run_skill_evals.py aggregate {skill}
+   --run {timestamp}` produces `runs/{timestamp}-benchmark.json` with
+   pass-rate, timing, token deltas baseline-vs-with-skill.
+6. **Report** — `python3 scripts/run_skill_evals.py report {skill}
+   --run {timestamp}` prints the diff. Iterate on the skill body
+   until `with-skill` outperforms `baseline` on every scenario.
+
+The script ships with sub-agent spawning **stubbed** — the orchestration
+layer is per-environment (Claude Code, Augment, council). Implement
+the spawn function once for your environment, the rest of the loop
+(aggregate / report / scaffold) works out of the box.
+
+**Exit criterion** — every scenario passes with-skill, at least one
+fails baseline (proves the skill earns its slot). Commit the
+`evals.json` alongside the skill; never commit `runs/`.
+
+Neighbors:
+* `description-assist` — iterate on the trigger phrasing
+* `skill-reviewer` — structural 7-Killers audit
+* `lint-skills` — static checks (frontmatter, sections, size)
+* `skill-improvement-pipeline` — production-learning capture
+
 ## Output format
 
 1. Complete SKILL.md file

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

@@ -17,7 +17,7 @@ Do NOT use when:
 
 ## Procedure: Write raw SQL
 
-1. **Choose approach** — Use query builder when possible. Raw SQL only when query builder can't express the query.
+1. **Inspect call site & choose approach** — identify every dynamic value flowing into the query, then pick: query builder when possible. Raw SQL only when query builder can't express the query.
 2. **Parameterize** — Every variable must use `?` binding or named `:param`. Never interpolate PHP variables into SQL strings.
 3. **Use MariaDB syntax** — Not PostgreSQL or MSSQL. Check `php/sql.md` for MariaDB-specific patterns.
 4. **Verify** — Run EXPLAIN on complex queries. Check that no PHP interpolation (`"$var"`, `'{$var}'`) appears in SQL.

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.11.0",
+    "version": "2.13.0",
     "keywords": [
       "agent-config",
       "skills",
@@ -71,6 +71,7 @@
         "./.claude/skills/bug-fix",
         "./.claude/skills/bug-investigate",
         "./.claude/skills/build-buy-partner",
+        "./.claude/skills/canvas-design",
         "./.claude/skills/challenge-me",
         "./.claude/skills/challenge-me-vision",
         "./.claude/skills/challenge-me-with-docs",
@@ -104,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",
@@ -126,6 +129,7 @@
         "./.claude/skills/devcontainer",
         "./.claude/skills/developer-like-execution",
         "./.claude/skills/discovery-interview",
+        "./.claude/skills/doc-coauthoring",
         "./.claude/skills/docker",
         "./.claude/skills/dto-creator",
         "./.claude/skills/e2e-heal",

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,84 @@ 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
+
+* **linter:** evals.json schema validator + meta_skill exemption ([9568510](https://github.com/event4u-app/agent-config/commit/95685109540c7f2dc2643ec24ba9d996467e0645))
+* **skill-writing:** § 7 quantitative eval loop + run_skill_evals.py ([9eda402](https://github.com/event4u-app/agent-config/commit/9eda402dc43b8e14682787fb1cbbc9872eb16fcc))
+* **skills:** add doc-coauthoring from Anthropic ([161b904](https://github.com/event4u-app/agent-config/commit/161b9044743753f2e54bcae45c36a29daaa8058d))
+* **skills:** add canvas-design from Anthropic ([95c247c](https://github.com/event4u-app/agent-config/commit/95c247c08d3c6710c53bfcd7ba7a00f270e0d8d4))
+* **check-refs:** add file/line opt-out markers ([f381bcb](https://github.com/event4u-app/agent-config/commit/f381bcb5a08818e042af35836dd2c4d8965aa98e))
+* make ai-council max_output_tokens configurable ([5976b46](https://github.com/event4u-app/agent-config/commit/5976b4623b94277f6ba49b0e82bb36ab7d5adb50))
+
+### Bug Fixes
+
+* **marketplace:** register canvas-design + doc-coauthoring ([9fbfe6a](https://github.com/event4u-app/agent-config/commit/9fbfe6af83589bf45b27b72c1b818be9772ae60c))
+
+### Documentation
+
+* **audit:** mark forward-refs in north-star bundle as opt-out ([a1d7c21](https://github.com/event4u-app/agent-config/commit/a1d7c21df3d05c27bacf81344893c4e43ae72a06))
+* **roadmap:** expand step-99 with Total Dominance mandate ([c46cffd](https://github.com/event4u-app/agent-config/commit/c46cffd54214a61230be27ddaae3367053be39a5))
+* **roadmap:** add step-99 north-star restructure (meta · out-of-band) ([8dd18f9](https://github.com/event4u-app/agent-config/commit/8dd18f963742d14dd9d006237ddd93881b198a60))
+* **audit:** correct step-3 filename reference ([ee6bd7f](https://github.com/event4u-app/agent-config/commit/ee6bd7ffc6c6cd363b6207b6ff32aa72f2bc317e))
+* **audit:** add 2026-05-14 north-star audit + council synthesis ([589c2fb](https://github.com/event4u-app/agent-config/commit/589c2fbd3e35b57529ab0f934665d71d611012d4))
+* add roadmaps for council, persona, ghostwriter, user-types axis ([471fae3](https://github.com/event4u-app/agent-config/commit/471fae3a46182d930fea21adb4037a41ec99dcb3))
+* add v2 feedback follow-up roadmap ([23d17cb](https://github.com/event4u-app/agent-config/commit/23d17cb24b33e794f7c1e31e76055cc5c8f1ab6c))
+
+### Chores
+
+* prefix roadmaps with step-N execution sequence ([de87232](https://github.com/event4u-app/agent-config/commit/de87232213404ad104e07c5ca831d64f4a607f8e))
+
+Tests: 3718 (+0 since 2.11.0)
+
 ## [2.11.0](https://github.com/event4u-app/agent-config/compare/2.10.0...2.11.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>208 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 + 208 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,91 +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
-
-  # 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
 

package/docs/architecture.md

@@ -10,7 +10,7 @@ Six layers, ordered from "how the package reaches a consumer" down to "what a co
 Distribution         → npx-only runtime · install.sh · lockfile pin        ← stable
 Governance           → Kernel rules · tier-1/2 routing · command clusters  ← stable
 Router-Kernel        → router.json · always-loaded Iron Laws · char caps   ← stable
-Projection           → Compression · augment / multi-tool / cloud bundles  ← stable
+Projection           → Source · augment / multi-tool / cloud bundles       ← stable
 Execution Contracts  → Skills · commands · work-engine · roadmap engine    ← stable / beta
 MCP Lite/Full        → Hosted read-only (Lite) · local stdio (Full)        ← experimental
 ```
@@ -20,7 +20,7 @@ MCP Lite/Full        → Hosted read-only (Lite) · local stdio (Full)
 | **Distribution** | [`installed-tools-lockfile.md`](contracts/installed-tools-lockfile.md) + the "Distribution model" subsection below | stable |
 | **Governance** | [`command-clusters.md`](contracts/command-clusters.md) + [`command-surface-tiers.md`](contracts/command-surface-tiers.md) | stable |
 | **Router-Kernel** | [`kernel-membership.md`](contracts/kernel-membership.md) + [`rule-router.md`](contracts/rule-router.md) | stable |
-| **Projection** | [`architecture/compression.md`](architecture/compression.md), [`augment-projection.md`](architecture/augment-projection.md), [`multi-tool-projection.md`](architecture/multi-tool-projection.md), [`claude-bundle.md`](architecture/claude-bundle.md) | stable |
+| **Projection** | [`architecture/source-projection.md`](architecture/source-projection.md), [`augment-projection.md`](architecture/augment-projection.md), [`multi-tool-projection.md`](architecture/multi-tool-projection.md), [`claude-bundle.md`](architecture/claude-bundle.md) | stable |
 | **Execution Contracts** | [`implement-ticket-flow.md`](contracts/implement-ticket-flow.md), [`orchestration-dsl-v1.md`](contracts/orchestration-dsl-v1.md), [`adr-product-ui-track.md`](contracts/adr-product-ui-track.md) | stable (skills · commands) / beta (work-engine · roadmap engine) |
 | **MCP Lite/Full** | [`mcp-phase-1-scope.md`](contracts/mcp-phase-1-scope.md), [`mcp-cloud-scope.md`](contracts/mcp-cloud-scope.md), [`mcp-beta-criteria.md`](contracts/mcp-beta-criteria.md) | experimental — promotion to beta gated on `mcp-beta-criteria.md` (six artefact gates, monitored by `agent-config doctor --check mcp-beta-readiness`) |
 
@@ -64,7 +64,7 @@ the pipeline.
 
 | Pipeline | Page | Output |
 |---|---|---|
-| **A.** Compression | [`architecture/compression.md`](architecture/compression.md) | `.agent-src/` |
+| **A.** Source projection | [`architecture/source-projection.md`](architecture/source-projection.md) | `.agent-src/` |
 | **B.** Augment projection | [`architecture/augment-projection.md`](architecture/augment-projection.md) | `.augment/` |
 | **C.** Multi-tool projection | [`architecture/multi-tool-projection.md`](architecture/multi-tool-projection.md) | `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules`, `GEMINI.md` |
 | **D.** Claude.ai bundle | [`architecture/claude-bundle.md`](architecture/claude-bundle.md) | `dist/cloud/<skill>.zip` |
@@ -141,9 +141,9 @@ note, package-internal path-swap, description budget, and the
 
 | Layer | Count | Purpose |
 |---|---|---|
-| **Skills** | 208 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
-| **Rules** | 61 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
-| **Commands** | 106 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
+| **Skills** | 210 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
+| **Rules** | 65 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
+| **Commands** | 108 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
 | **Guidelines** | 72 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |