@event4u/agent-config 2.12.0 → 2.14.0

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>67 Rules</strong> · <strong>109 Commands</strong> · <strong>72 Guidelines</strong> · <strong>22 Personas</strong> · <strong>5 Advisors</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -31,8 +31,8 @@ replay it. [Core Principles](#core-principles) names the four invariants.
 [What this package is — and what it isn't](#what-this-package-is--and-what-it-isnt)
 draws the scope boundary. [Documentation](#documentation) lists the
 contracts the package ships against, including
-[`memory-visibility-v1`](docs/contracts/memory-visibility-v1.md) and
-[`decision-trace-v1`](docs/contracts/decision-trace-v1.md).
+[`memory-visibility-v1`](docs/contracts/memory-visibility-v1.md) (beta) and
+[`decision-trace-v1`](docs/contracts/decision-trace-v1.md) (beta).
 
 ## Contribute
 
@@ -288,7 +288,7 @@ Install in the same project (dev-only):
 npm install --save-dev @event4u/agent-memory
 ```
 
-→ [Memory contract & retrieval API](docs/contracts/agent-memory-contract.md) (beta) · [Built-in MCP server](docs/mcp-server.md) (experimental — local stdio access from Claude Desktop / Cursor / Zed / Continue, install with `task mcp:setup`; promotion to beta gated on [`mcp-beta-criteria.md`](docs/contracts/mcp-beta-criteria.md))
+→ [Memory contract & retrieval API](docs/contracts/agent-memory-contract.md) (beta) · [Built-in MCP server](docs/mcp-server.md) (experimental — local stdio access from Claude Desktop / Cursor / Zed / Continue, install with `task mcp:setup`; promotion to beta gated on `docs/contracts/mcp-beta-criteria.md`)
 
 ---
 
@@ -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 109 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 + 109 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/config/gitignore-block.txt

@@ -37,6 +37,12 @@
 /agents/council-responses/
 /agents/council-sessions/
 
+# Agent config — AI Council persistent events log (step-8 D3).
+# Local JSONL audit trail for necessity / quota decisions. Hashes
+# original_ask before write but is still considered private. Set
+# AGENT_CONFIG_NO_EVENTS_LOG=1 to disable writes entirely.
+/agents/council-events.log
+
 # Agent config — Tier 1 hook runtime state (context-hygiene.json,
 # onboarding-gate.json). Written by SessionStart / PostToolUse hooks
 # on Augment + Claude Code; regenerated on demand, never commit.

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,19 +10,19 @@ 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
 ```
 
 | Layer | Canonical contract | Tier |
 |---|---|---|
-| **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 |
-| **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`) |
+| **Distribution** | [`installed-tools-lockfile.md`](contracts/installed-tools-lockfile.md) + the "Distribution model" subsection below | (beta) |
+| **Governance** | [`command-clusters.md`](contracts/command-clusters.md) + [`command-surface-tiers.md`](contracts/command-surface-tiers.md) | (beta) |
+| **Router-Kernel** | [`kernel-membership.md`](contracts/kernel-membership.md) + [`rule-router.md`](contracts/rule-router.md) | (beta) |
+| **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 (adr-product-ui-track) / (beta) (implement-ticket-flow · orchestration-dsl-v1) |
+| **MCP Lite/Full** | `docs/contracts/mcp-phase-1-scope.md`, `docs/contracts/mcp-cloud-scope.md`, `docs/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`) |
 
 Stability tiers follow [`docs/contracts/STABILITY.md`](contracts/STABILITY.md):
 
@@ -34,10 +34,10 @@ Stability tiers follow [`docs/contracts/STABILITY.md`](contracts/STABILITY.md):
 
 Four load-bearing additions reshaped the top of the model between 2.2.2 and the current release. They are listed here so the diagram above reads as the *current* package, not a historical accumulation:
 
-1. **Router-Kernel** — the always-loaded Iron Laws collapsed into a 9-rule kernel with explicit per-rule character budgets enforced by `task lint-rule-budget`; everything else routes via tier-1/2 (`.agent-src/router.json`). Contract: [`kernel-membership.md`](contracts/kernel-membership.md) + [`rule-router.md`](contracts/rule-router.md).
-2. **MCP Lite/Full** — replaces the old "Tool Adapters" layer at the top level. Lite is the hosted read-only surface (Claude.ai, Cloud agents); Full is the local stdio server consumers self-host. Promotion to beta is gated on six falsifiable artefacts in [`mcp-beta-criteria.md`](contracts/mcp-beta-criteria.md); the old GitHub / Jira adapters remain as an internal detail of the Execution Contracts layer (see Tool Adapters subsection below).
+1. **Router-Kernel** — the always-loaded Iron Laws collapsed into a 9-rule kernel with explicit per-rule character budgets enforced by `task lint-rule-budget`; everything else routes via tier-1/2 (`.agent-src/router.json`). Contract: [`kernel-membership.md`](contracts/kernel-membership.md) + [`rule-router.md`](contracts/rule-router.md) — both (beta).
+2. **MCP Lite/Full** — replaces the old "Tool Adapters" layer at the top level. Lite is the hosted read-only surface (Claude.ai, Cloud agents); Full is the local stdio server consumers self-host. Promotion to beta is gated on six falsifiable artefacts in `docs/contracts/mcp-beta-criteria.md`; the old GitHub / Jira adapters remain as an internal detail of the Execution Contracts layer (see Tool Adapters subsection below).
 3. **npx distribution** — Composer and `npm install` paths retired in favour of `npx @event4u/agent-config`, with the lockfile-equivalent role played by `agent_config_version` in `.agent-settings.yml`. Full rationale in the "Distribution model" subsection below.
-4. **Command tiering** — `/`-commands now declare a `tier:` (0 / 1 / 2 / 3) that maps to invocation frequency and surface budget; tier-0 is the trimmed Tier-0 set surfaced in `agent-config --help` after the 2.7.x surface-discipline pass. Contract: [`command-surface-tiers.md`](contracts/command-surface-tiers.md) + [`command-clusters.md`](contracts/command-clusters.md).
+4. **Command tiering** — `/`-commands now declare a `tier:` (0 / 1 / 2 / 3) that maps to invocation frequency and surface budget; tier-0 is the trimmed Tier-0 set surfaced in `agent-config --help` after the 2.7.x surface-discipline pass. Contract: [`command-surface-tiers.md`](contracts/command-surface-tiers.md) + [`command-clusters.md`](contracts/command-clusters.md) — both (beta).
 
 > The previous "observability, feedback, lifecycle" layers were removed in
 > 1.5 — they were scaffolds without production consumers. The "Tool
@@ -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` |
@@ -142,8 +142,8 @@ note, package-internal path-swap, description budget, and the
 | Layer | Count | Purpose |
 |---|---|---|
 | **Skills** | 210 | 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`, … |
+| **Rules** | 67 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
+| **Commands** | 109 | 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 |
@@ -161,7 +161,7 @@ note, package-internal path-swap, description budget, and the
 - **Guidelines** → reference-only documentation
 - **Commands** → workflow orchestration
 
-Ensures: no guessing, analysis before action, real verification, consistent outputs. Canonical contracts: [`kernel-membership.md`](contracts/kernel-membership.md), [`rule-router.md`](contracts/rule-router.md), [`command-clusters.md`](contracts/command-clusters.md), [`command-surface-tiers.md`](contracts/command-surface-tiers.md).
+Ensures: no guessing, analysis before action, real verification, consistent outputs. Canonical contracts (all (beta)): [`kernel-membership.md`](contracts/kernel-membership.md), [`rule-router.md`](contracts/rule-router.md), [`command-clusters.md`](contracts/command-clusters.md), [`command-surface-tiers.md`](contracts/command-surface-tiers.md).
 
 ### 2. Runtime Dispatcher — stable mechanism, pilot coverage
 
@@ -248,7 +248,7 @@ independent components with separate stability tiers.
 
 ### 4. Tool Adapters — experimental (internal detail; superseded at the top level by MCP)
 
-> **Position in the new model.** Tool Adapters no longer occupy a top-level layer — that slot is now **MCP Lite/Full**. The adapter classes still ship as the internal mechanism the Work Engine uses for inline GitHub/Jira reads, but external integration is meant to land via MCP going forward. See [`mcp-phase-1-scope.md`](contracts/mcp-phase-1-scope.md), [`mcp-cloud-scope.md`](contracts/mcp-cloud-scope.md), and [`mcp-beta-criteria.md`](contracts/mcp-beta-criteria.md) for the surface that replaces this layer at the top level.
+> **Position in the new model.** Tool Adapters no longer occupy a top-level layer — that slot is now **MCP Lite/Full**. The adapter classes still ship as the internal mechanism the Work Engine uses for inline GitHub/Jira reads, but external integration is meant to land via MCP going forward. See `docs/contracts/mcp-phase-1-scope.md`, `docs/contracts/mcp-cloud-scope.md`, and `docs/contracts/mcp-beta-criteria.md` for the surface that replaces this layer at the top level.
 
 > **Status: scaffold + read-only GitHub calls.** With a `GITHUB_TOKEN` the
 > GitHub adapter performs real read calls; without one it returns scaffold

package/docs/archive/CHANGELOG-pre-2.11.0.md

@@ -0,0 +1,141 @@
+# Changelog Archive — pre-2.11.0
+
+> Frozen snapshot of `event4u/agent-config` changelog entries from
+> `2.10.0` and earlier (back to `2.7.0`), split out of the main
+> [`CHANGELOG.md`](../../CHANGELOG.md) on 2026-05-15 once the active
+> era's body crossed the 200-line drift cap enforced by
+> `tests/test_changelog_eras.py`.
+>
+> **Read-only.** New entries land in `CHANGELOG.md` § "Era: 2.11.x".
+> Entries here are not amended — git tags `2.10.0` and prior remain the
+> canonical source for what shipped.
+>
+> Entry shape follows the conventions documented in
+> [`docs/contracts/CHANGELOG-conventions.md`](../contracts/CHANGELOG-conventions.md).
+> Earlier eras live in
+> [`CHANGELOG-pre-2.7.0.md`](CHANGELOG-pre-2.7.0.md) and
+> [`CHANGELOG-pre-2.2.0.md`](CHANGELOG-pre-2.2.0.md).
+
+## [2.10.0](https://github.com/event4u-app/agent-config/compare/2.9.0...2.10.0) (2026-05-14)
+
+### Features
+
+* **ci:** lint-hook-concern-budget Tier-1 fail-closed gate ([8d60b8a](https://github.com/event4u-app/agent-config/commit/8d60b8ab464c4c5bdc6d072bb2a9b0123942e13b))
+* **cli:** settings:check command + YAML subset contract ([638e740](https://github.com/event4u-app/agent-config/commit/638e74017ffea8d7c08073a949e86fde047db109))
+* **hooks:** hooks:doctor + hooks:replay subcommands + fixture corpus ([3156e25](https://github.com/event4u-app/agent-config/commit/3156e25fd3253fc926a57b92e14b407a9ed54b58))
+* **work-engine:** add decision-trace memory_visibility hook + scoring ([bf056ac](https://github.com/event4u-app/agent-config/commit/bf056ace877a696afa5fe758053ea1eb350e5dff))
+
+### Bug Fixes
+
+* **roadmap:** point productization P6 gate at archived proof-not-features path ([35a1009](https://github.com/event4u-app/agent-config/commit/35a1009cffdfde28c7b0384c890c31a7e62b70cf))
+
+### Documentation
+
+* **roadmap:** complete road-to-proof-not-features 16/16 + sync dashboard ([89af72d](https://github.com/event4u-app/agent-config/commit/89af72d5514b74c19d533b5a2e69ff7ddf16ecbc))
+* **readme:** split README by audience + audience-order contract ([60a87c0](https://github.com/event4u-app/agent-config/commit/60a87c056555a80585d25555f3d5b87d54c7283a))
+
+### Refactoring
+
+* **check-council-references:** structural carve-outs for immutable inputs and decision provenance ([3ed7784](https://github.com/event4u-app/agent-config/commit/3ed77841c42c5e3ebf4191611bb7fa4a52ed2fa0))
+
+### Chores
+
+* **roadmap:** archive road-to-proof-not-features (16/16 done, Phase 1 deferred) ([9d05aed](https://github.com/event4u-app/agent-config/commit/9d05aed79a46023b1e95c5488a1e3d5e78748e67))
+
+Tests: 3663 (+60 since 2.9.0)
+
+## [2.9.0](https://github.com/event4u-app/agent-config/compare/2.8.0...2.9.0) (2026-05-13)
+
+### Features
+
+* tier-usage telemetry settings + report template ([22172f2](https://github.com/event4u-app/agent-config/commit/22172f2a59b530034633ff72226506006c5fd81b))
+* mcp beta-readiness criteria with pending gate tests ([3653788](https://github.com/event4u-app/agent-config/commit/36537880e03546e9baf424b2fdd70aa69d41eb03))
+* expand doctor diagnostic hub to 10 checks ([372c193](https://github.com/event4u-app/agent-config/commit/372c19362f8037c76f919a2d918780ae5ec9cb40))
+* **roadmap:** add road-to-surface-discipline (council-reviewed) ([d9da987](https://github.com/event4u-app/agent-config/commit/d9da9870989ccdb7594cd693e9b18608b957ab79))
+* **linter:** wing-4 cognition-boundary checks + spine slot vocab ([c4d9a4b](https://github.com/event4u-app/agent-config/commit/c4d9a4ba8e5c7184b9be0a58d4d8b220a60cab7c))
+
+### Bug Fixes
+
+* **skills:** clear missing_inspect_step + bare_noun warnings ([0c88c6e](https://github.com/event4u-app/agent-config/commit/0c88c6ee45873e47fd8c7d356ec82b28b63b12c5))
+* **docs:** drop roadmap-file pointers from wing-4 ADRs and handoff ([ccd7624](https://github.com/event4u-app/agent-config/commit/ccd7624127094d0a01eda0901fa41c31319f7bc5))
+* **template:** bump agent_config_version pin to 2.8.0 ([f21e916](https://github.com/event4u-app/agent-config/commit/f21e916c6bb793fa6efe7d264a1e069e11ab4c62))
+* **skills:** spine slot citations + finance-partner polish ([9072783](https://github.com/event4u-app/agent-config/commit/90727831b223bd970d8425d158940bf3e3bc104f))
+
+### Documentation
+
+* archive surface-discipline roadmap + 2.8.0 changelog ([551e306](https://github.com/event4u-app/agent-config/commit/551e306e43fa82fffda9178bdaa690b19d8bec4e))
+* 6-layer architecture refresh + thin-root sync ([91d25a8](https://github.com/event4u-app/agent-config/commit/91d25a80b37fb1c1782c2d5f00f23925ba6ec1b3))
+* **roadmap:** complete road-to-money-strategy-ops phase 1 ([83cf9fe](https://github.com/event4u-app/agent-config/commit/83cf9fe99c034b71e146099eddc9ce5b3137f434))
+* **contracts:** register wing-4 spine slots + marketplace entries ([75b829d](https://github.com/event4u-app/agent-config/commit/75b829d162bc18ab3dc2dda6614d15a087a4f32a))
+
+### Refactoring
+
+* trim tier-0 surface from 13 to 7 commands ([a9eafd1](https://github.com/event4u-app/agent-config/commit/a9eafd1c5226c10209e3dee2b972f38d9c0f3dd9))
+
+### Chores
+
+* **generated:** regenerate derived outputs for wing-4 additions ([54f3779](https://github.com/event4u-app/agent-config/commit/54f3779a6d2161ed06bfb327c3e416ec107b4016))
+
+Tests: 3603 (+26 since 2.8.0)
+
+## [2.8.0](https://github.com/event4u-app/agent-config/compare/2.7.0...2.8.0) (2026-05-13)
+
+### Features
+
+* **linter:** wing-scoped persona line budgets ([81c8cda](https://github.com/event4u-app/agent-config/commit/81c8cdaf08f243a61f848b2e53fad73305ec173d))
+* **personas:** GTM roadmap I1-I4 — Wing-3 personas (CMO, RevOps, CS, Growth-PM) ([a05d49e](https://github.com/event4u-app/agent-config/commit/a05d49e1fd2076effd68dabce7a0789676b2bbf5))
+* **skills:** GTM roadmap H8-H16 — RevOps, CS, Growth-PM clusters ([f79e7a1](https://github.com/event4u-app/agent-config/commit/f79e7a11f5447466c05c6be613a618b9c564a4b1))
+* **gtm:** H3–H7 — complete CMO cluster skills (gtm-launch, editorial-calendar, content-funnel-design, voice-and-tone-design, fundraising-narrative) ([a905bea](https://github.com/event4u-app/agent-config/commit/a905bea811a02d973a682465525ca39d274d3342))
+* **gtm:** H1+H2 — positioning + messaging-architecture senior skills ([00aeb27](https://github.com/event4u-app/agent-config/commit/00aeb279be9924c01dea998df7ee91442fd3ff88))
+* **gtm:** G3 — Wing-3 handoff guideline + Block G closed ([15643da](https://github.com/event4u-app/agent-config/commit/15643da3e2e96a6b00a738e8f4b7ba10edd18187))
+* **gtm:** G2 — Wing-3 cognition-boundary linter ([8445921](https://github.com/event4u-app/agent-config/commit/84459218a914dd5d39c524824e9e0a597c28daec))
+* **gtm:** G1 — extend context-spine with Wing-3 slots ([853e653](https://github.com/event4u-app/agent-config/commit/853e6538fff24429ab0f4136f5eec5d4b992dda4))
+
+### Bug Fixes
+
+* **refs:** drop roadmap-file citations from GTM ADR + handoff guideline ([092a01d](https://github.com/event4u-app/agent-config/commit/092a01d7bcd6b51c85d12bfcf83dc973b35c0fcc))
+* **contracts:** add stability frontmatter to command-surface-tiers.md ([3ab2ffd](https://github.com/event4u-app/agent-config/commit/3ab2ffde4345b4ca30cc4d64926f571bce5ce7dd))
+* **lint:** teach context-spine linter the Wing-3 GTM slots ([5bf81d5](https://github.com/event4u-app/agent-config/commit/5bf81d51864b652301d890eafb0574641d05b71a))
+* **refs:** replace dangling skill backticks with plain phrasing in GTM skills ([9f20b06](https://github.com/event4u-app/agent-config/commit/9f20b0612b58f8ef0273bfbe5f830793f4dca131))
+* **template:** bump agent_config_version to 2.7.0 in agent-project-settings template ([ac65734](https://github.com/event4u-app/agent-config/commit/ac657343a81879c3aee4664728e15233863016a5))
+
+### Refactoring
+
+* **skill:** rename positioning → positioning-strategy ([be1a5c9](https://github.com/event4u-app/agent-config/commit/be1a5c9019ac18fabde14469784db42aa7588a14))
+
+### Chores
+
+* **index:** regenerate after positioning → positioning-strategy rename ([9f42d91](https://github.com/event4u-app/agent-config/commit/9f42d9148f196d30635ae8288e9bba0feda66067))
+* **changelog:** split era 2.2.x → pre-2.7.0 ([7158c30](https://github.com/event4u-app/agent-config/commit/7158c30db391f3464fd74f3c7e193698b869b82d))
+* **generated:** refresh agents/index.md and docs/catalog.md for GTM skills/personas ([649b86e](https://github.com/event4u-app/agent-config/commit/649b86e287ecef7d0d28ce23ed2b0cbf43f2adc6))
+* **generated:** regenerate .claude/ tool output + marketplace + compression hashes for GTM skills/personas ([bb7d56c](https://github.com/event4u-app/agent-config/commit/bb7d56cd8e7cafb9037a4e6ec0078e56154f9d5c))
+* **roadmap:** archive road-to-gtm-and-growth — G+H+I all shipped ([dc48cdd](https://github.com/event4u-app/agent-config/commit/dc48cdd29e236c745e98b5f5fb8b45fa716a4c07))
+
+Tests: 3577 (+11 since 2.7.0)
+
+## [2.7.0](https://github.com/event4u-app/agent-config/compare/2.6.1...2.7.0) (2026-05-13)
+
+### Features
+
+* **install:** make augment global-only per ADR-007 amendment ([ea9a82f](https://github.com/event4u-app/agent-config/commit/ea9a82f2305a2a178b058ee66c40859790620d63))
+* **mcp:** define mcp_scope lite vs full boundary in cloud-scope contract ([15a268c](https://github.com/event4u-app/agent-config/commit/15a268c9f86fabe677b4d70db9fd4e3d1726ef8a))
+* **commands:** tier the slash + CLI command surface (Phase 4 of road-to-distribution-maturity) ([cc0102f](https://github.com/event4u-app/agent-config/commit/cc0102fe9677c936f703fd6e08b75cc99f758071))
+* **distribution:** roadmap phases 1+2 — MCP auth-surface sync + verified-offline install ([a85c1af](https://github.com/event4u-app/agent-config/commit/a85c1afdc457c5fa4d939afc2d91649c67926501))
+
+### Bug Fixes
+
+* **refs:** point evaluation-2-2-2-followups at archived roadmap location ([cde02e6](https://github.com/event4u-app/agent-config/commit/cde02e6fd3bfbb2d67e2a8e3976fe6794ea4de6c))
+
+### Documentation
+
+* **architecture:** split docs/architecture.md into four pipeline sub-pages + drift test ([4f13cf5](https://github.com/event4u-app/agent-config/commit/4f13cf504c0b2d9b92661234a597b5515a7c54e8))
+* **roadmap:** add distribution-maturity roadmap with council verdicts folded in ([14145cf](https://github.com/event4u-app/agent-config/commit/14145cff75ef34065358a2e99ee8c220ab0e59a0))
+
+### Chores
+
+* **ci:** refresh compression hashes after cc0102fe tiering pass ([ca06729](https://github.com/event4u-app/agent-config/commit/ca06729d03bb8bd8d1536b7aecef1d1b134d8333))
+* finalize roadmaps ([bb156ea](https://github.com/event4u-app/agent-config/commit/bb156ea4f52741d511c3e54cd87e3bcab2fbf107))
+* **roadmap:** close road-to-distribution-maturity, archive ([d48e5d6](https://github.com/event4u-app/agent-config/commit/d48e5d64f9396f6b75b47bf336fd6ac129c8e254))
+* **changelog:** split into eras, archive pre-2.2.0 entries ([e54c5cb](https://github.com/event4u-app/agent-config/commit/e54c5cbf0222de7f0f4c84a379118f4ea30b5a07))
+
+Tests: 3566 (+36 since 2.6.1)