@event4u/agent-config 2.10.0 → 2.12.0

package/CHANGELOG.md

@@ -429,6 +429,74 @@ 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.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
+
+* **stability:** add beta-review marker protocol and CI gate (P5.4) ([9b6cdfe](https://github.com/event4u-app/agent-config/commit/9b6cdfe9f9167e3e80551dfa2a88f80fff85646a))
+* **lint:** add 'type: orchestrator' frontmatter tag for cluster routers (P5.3) ([e6385bb](https://github.com/event4u-app/agent-config/commit/e6385bbaf022dc3763f55c2dd54fe85046c59fd4))
+* **skills:** add nextjs-patterns and symfony-workflow workflow skills (P4) ([038522b](https://github.com/event4u-app/agent-config/commit/038522b7ad2bd2ba1d8d8c4f9a61692694b7ebc8))
+* **onboard:** add Quickstart pointer step and surface balanced default (P3.3) ([5879b4c](https://github.com/event4u-app/agent-config/commit/5879b4cc66fc9f49fa42c99e72794e4c60f43739))
+* **install:** default cost_profile to balanced (P3.2) ([75caac2](https://github.com/event4u-app/agent-config/commit/75caac20fa2986222b5bd45a7cb63f07f9c4179f))
+* **work-engine:** wire decision_gate hook into runner ([c41a89d](https://github.com/event4u-app/agent-config/commit/c41a89d38c7eb4892358b5c931abbe9a5889038c))
+* **work-engine:** add decision_engine schema and gate evaluator ([fd1e8e2](https://github.com/event4u-app/agent-config/commit/fd1e8e2bb2e45e2288727ccd4a3bda4f809c6151))
+* **release:** release-trunk-sync contract and CI gate (P1.2, P1.3) ([a3e0d12](https://github.com/event4u-app/agent-config/commit/a3e0d12c156c367c995e84c7c0bb5d6a21ff6325))
+
+### Bug Fixes
+
+* **readme:** rename 'For contributors' to 'Development' for linter ([7957274](https://github.com/event4u-app/agent-config/commit/7957274c65895d80fa4801f95df876979362ee86))
+
+### Documentation
+
+* **roadmap:** close + archive road-to-productization (Level-6) ([7ee50e8](https://github.com/event4u-app/agent-config/commit/7ee50e8b16f1ce7d4461f1466d9a6e46f4138101))
+* **roadmap:** mark P3.1-P3.3 + P3.1a done in road-to-productization ([b0ff24f](https://github.com/event4u-app/agent-config/commit/b0ff24f23cb38d4ac556106c9ed060f104f83c8c))
+* **readme:** add 3-step Quickstart and move contributor detail below the fold (P3.1) ([b98152e](https://github.com/event4u-app/agent-config/commit/b98152eb86607d6b34f63ea9ad4c152951de58a6))
+* **roadmap:** mark P2.1-P2.3 done in road-to-productization ([189c780](https://github.com/event4u-app/agent-config/commit/189c780faef19cfbd9bceb3ad51ec42cb8cb05b7))
+
+### CI
+
+* **install:** add structural Quickstart smoke test (P3.1a) ([228445b](https://github.com/event4u-app/agent-config/commit/228445b97eefb20118bbea2872640c54225a1355))
+* **work-engine:** validate decision_engine block in agent-settings ([1a1f428](https://github.com/event4u-app/agent-config/commit/1a1f428bec4832f8ffb222a8b450719ba6409605))
+
+### Chores
+
+* **generate-tools:** expose nextjs-patterns + symfony-workflow skills ([3422ac7](https://github.com/event4u-app/agent-config/commit/3422ac7e3f273497a0cbb176b2580a0cf1256522))
+* **sync:** align orchestrator frontmatter + hash registry ([0e9ba2d](https://github.com/event4u-app/agent-config/commit/0e9ba2d50463ca99baf86651ea67ed82ca63d7f6))
+* **gitignore:** ignore python coverage artifacts ([e1a3289](https://github.com/event4u-app/agent-config/commit/e1a328921f08fad03325adc256b63a544582efb7))
+
+Tests: 3718 (+55 since 2.10.0)
+
 ## [2.10.0](https://github.com/event4u-app/agent-config/compare/2.9.0...2.10.0) (2026-05-14)
 
 ### Features

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>206 Skills</strong> · <strong>61 Rules</strong> · <strong>106 Commands</strong> · <strong>72 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>210 Skills</strong> · <strong>61 Rules</strong> · <strong>106 Commands</strong> · <strong>72 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -46,6 +46,30 @@ or `.agent-src/`.
 
 ## Quickstart
 
+**Three steps. Five minutes. Decision-traced first task.**
+
+```bash
+# 1. Install (writes .agent-settings.yml, .augment/, .claude/, …)
+npx @event4u/agent-config init
+
+# 2. First-run setup (sets your name, IDE, cost profile)
+#    Open your AI agent (Claude Code, Cursor, …) and type:
+/onboard
+
+# 3. First real task — agent refines, plans, logs a decision_result
+/work "your first real task"
+```
+
+A `decision_result` entry lands in `agents/state/` confirming the
+work-engine phases ran end-to-end. Stack-aware skills auto-load.
+
+> Pick specific AIs, switch to global scope, deploy MCP on Cloudflare,
+> or wire optional memory — see [**Detailed installation**](#detailed-installation)
+> below. Contributors rebuilding the package — jump to
+> [**Development**](#development).
+
+### Detailed installation
+
 Two minutes from `npx` to a better-behaved agent — no install, no
 vendored package, no postinstall hook.
 
@@ -451,12 +475,14 @@ kernel set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-member
 | Stack | Coverage |
 |---|---|
 | Laravel · modern PHP | Skills, rules, project-analysis, quality-tool wiring (Pest · PHPStan · Rector · ECS) |
-| Symfony · Zend / Laminas | Project-analysis skills + shared PHP coder/quality skills |
-| Next.js · React · Node / Express | Project-analysis skills + UI directive set (`react-shadcn`) |
+| Symfony | Workflow skill (`symfony-workflow`) + project-analysis + shared PHP coder/quality skills |
+| Zend / Laminas | Project-analysis skills + shared PHP coder/quality skills |
+| Next.js · App Router | Workflow skill (`nextjs-patterns`) + project-analysis + UI directive set (`react-shadcn`) |
+| React · Node / Express | Project-analysis skills + UI directive set (`react-shadcn`) |
 | Vue · plain HTML | UI directive set (`vue` / `plain`) — analysis skills as they ship |
 | Cross-stack | API design · testing · security · database · Docker · Git · CI · review · threat modeling · observability |
 
-**Deepest reference stack today: Laravel.** Skill density covers Pest, PHPStan, Rector, Eloquent, Livewire/Flux, Horizon, Pulse, Reverb, Pennant — the stack the package was first proven on. Other stacks ship in the order they are battle-tested, not second-class. Adopting on a thin stack? Open an issue so we can prioritize the right skills for extraction.
+**Deepest reference stack today: Laravel** — Pest, PHPStan, Rector, Eloquent, Livewire/Flux, Horizon, Pulse, Reverb, Pennant. **Workflow-grade second tier: Symfony** (`symfony-workflow` — DI, Doctrine, Messenger, voters, Twig) and **Next.js App Router** (`nextjs-patterns` — RSC boundaries, Server Actions, caching, route handlers). Other stacks ship in the order they are battle-tested, not second-class. Adopting on a thin stack? Open an issue so we can prioritize the right skills for extraction.
 
 ---
 
@@ -530,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 + 206 skills + 106 native commands); Augment Code gets the
+> package (rules + 210 skills + 106 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
@@ -652,11 +678,14 @@ re-enabled or the chat ends. Full scoring contract and hardening:
 
 ## Development
 
-Edit in `.agent-src.uncompressed/`, compress, verify:
+Working on the package itself? Edit in `.agent-src.uncompressed/`,
+then regenerate compressed and projected trees:
 
 ```bash
-task ci            # Run all CI checks
-task test          # Run all tests
+task sync             # regenerate .agent-src/ and .augment/
+task generate-tools   # regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
+task ci               # full pipeline — green before PR
+task test             # unit + integration tests
 ```
 
 → Full commands and project structure: [**docs/development.md**](docs/development.md)

package/config/agent-settings.template.yml

@@ -298,6 +298,15 @@ ai_council:
   # 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
@@ -418,6 +427,63 @@ hooks:
     tier1_concerns: []
     hard_fail: false
 
+# --- Decision engine ---
+#
+# Controllable gates layered over the observability surface. Absent
+# block = current behaviour (observe-only, no gates fire). Enforcement
+# is strictly opt-in; the engine never silently rejects work without
+# a configured gate. See docs/contracts/decision-engine-gates.md for
+# the full schema, gate-conflict matrix, and non-TTY timeout protocol.
+#
+# Gate-conflict resolution (only the first firing gate per phase
+# surfaces a reason; downstream gates are skipped):
+#   1. block_on_risk         (Phase=Implement, highest impact)
+#   2. require_memory_hits   (Phase=Refine)
+#   3. min_confidence        (Phase=Plan, lowest impact)
+#
+# Unknown keys are rejected hard by scripts/validate_decision_engine.py
+# (wired into `task ci`). Removing the entire block restores observe-only.
+decision_engine:
+  # Opt-in for DecisionTraceHook (default false). Mirrored into
+  # hooks.decision_trace.enabled by work_engine.hooks.settings.
+  surface_traces: false
+
+  # Confidence-band floor for Phase=Plan.
+  #   off    = no floor (default)
+  #   low    = refuse to advance when band is below low
+  #   medium = refuse when below medium
+  #   high   = refuse when below high
+  min_confidence: off
+
+  # Risk-class ceiling for Phase=Implement.
+  #   off    = no ceiling (default)
+  #   low    = refuse when risk_class >= low (most aggressive)
+  #   medium = refuse when risk_class >= medium
+  #   high   = refuse only when risk_class == high
+  block_on_risk: off
+
+  # Phase=Refine demands at least one memory hit when true (default false).
+  # Gated on road-to-proof-not-features.md P2 (memory-consequence trace);
+  # leaving this off avoids opaque rejections until the trace can explain
+  # which memory entry was missing.
+  require_memory_hits: false
+
+  # What happens when a gate fires.
+  #   stop = halt the engine with reason on the trace (default)
+  #   ask  = prompt the user; falls back to on_block_fallback in CI
+  #   warn = log the reason but advance
+  on_block: stop
+
+  # Non-TTY timeout (seconds) when on_block=ask runs without a TTY
+  # (CI=true env or stdin not a TTY). After the timeout, the engine
+  # applies on_block_fallback and surfaces block_reason=ask_timeout.
+  ask_timeout_seconds: 30
+
+  # Resolution after ask_timeout fires.
+  #   stop = halt the engine (default — fail-safe)
+  #   warn = log and advance
+  on_block_fallback: stop
+
 # --- Update check ---
 #
 # Daily background check against the npm registry for a newer

package/docs/architecture.md

@@ -141,7 +141,7 @@ note, package-internal path-swap, description budget, and the
 
 | Layer | Count | Purpose |
 |---|---|---|
-| **Skills** | 206 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
+| **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`, … |
 | **Guidelines** | 72 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |

package/docs/contracts/STABILITY.md

@@ -83,6 +83,22 @@ Promotion criteria:
   with the contract unchanged, or the contract has been explicitly
   frozen as part of a roadmap step.
 
+## Beta-review markers
+
+Every `stability: beta` contract MUST carry exactly one of the
+following frontmatter markers (audit-acceptance for the periodic beta
+review; see `road-to-productization.md` § P5.4):
+
+| Marker | Shape | Meaning |
+|---|---|---|
+| `promote-to: stable` | literal | Contract has been ≥ 30 days in beta, zero breaking changes in the last 14 days, ≥ 1 consumer reference. Schedule promotion in the next release. |
+| `keep-beta-until: YYYY-MM-DD` | ISO date | API still moving or consumer count = 0. Date is the next review deadline (max 90 days from the last review). |
+| `superseded-by: <contract-id>` | string | Replaced by a stable contract. Slated for deprecation, not deletion. |
+
+The audit is repeated whenever the `keep-beta-until` date passes for
+≥ 25 % of beta contracts, or at the start of any roadmap phase that
+touches the contract surface.
+
 ## Current contracts
 
 See the file headers themselves for current levels. The frontmatter is

package/docs/contracts/adr-chat-history-split.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # ADR — Chat-history rule split

package/docs/contracts/adr-forecast-construction-shape.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # ADR — `forecast-construction-shape`: the O2 ↔ H10 interface

package/docs/contracts/adr-gtm-context-spine.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # ADR — GTM context-spine: Wing-3 slot extension

package/docs/contracts/adr-level-6-productization.md

@@ -0,0 +1,147 @@
+---
+stability: stable
+---
+
+# ADR — Level-6 Productization Closure
+
+> **Status:** Decided · 2026-05-14
+> **Context:** Closure record for `road-to-productization.md` and its
+> two sibling roadmaps (`road-to-proof-not-features.md`,
+> `road-to-better-skills-and-profiles.md` Block A). PR #43 lifted the
+> package from Level-4 (execution engine) to Level-5 (observable
+> decision system); this roadmap was the Level-5 → Level-6 jump:
+> **steerable + provable + onboardable**.
+> **Cross-links:**
+> [`road-to-productization.md`](../../agents/roadmaps/road-to-productization.md) ·
+> [`road-to-proof-not-features.md`](../../agents/roadmaps/archive/road-to-proof-not-features.md) ·
+> [`road-to-better-skills-and-profiles.md`](../../agents/roadmaps/archive/road-to-better-skills-and-profiles.md).
+
+## What shipped
+
+### Decision-Engine steerability (Phase 2)
+
+- [`decision-engine-gates.md`](decision-engine-gates.md) — additive
+  `decision_engine:` block in `.agent-settings.yml` with
+  `min_confidence`, `block_on_risk`, `require_memory_hits`, `on_block`,
+  `ask_timeout_seconds`, `on_block_fallback`. Absent block = unchanged
+  observe-only behaviour.
+- Gate-conflict resolution matrix (P2.1a) + non-TTY timeout fallback
+  (P2.1b) shipped before the gates themselves; the engine refuses to
+  evaluate downstream gates after the first rejection and falls back
+  to `on_block_fallback` in non-interactive contexts.
+- Confidence-band gate (P2.2) and risk-class gate (P2.3) wired into
+  the scoring path. Memory-required policy (P2.4) unblocks on P6.2
+  shipping (`affected` keys in the decision trace).
+
+### UX simplification (Phase 3)
+
+- README "Quickstart" block — install → `/onboard` → `/work "first
+  real task"`, contributor detail moved below the `## For contributors`
+  fold.
+- Default `cost_profile` flipped from `minimal` to `balanced`;
+  rationale in [`cost-profile-defaults.md`](cost-profile-defaults.md).
+- `/onboard` step 11 prints the Quickstart command list inline.
+- CI gate: `task smoke-quickstart` runs the installer into a tmpdir
+  and validates the documented default surface deterministically.
+
+### Multi-stack skill depth (Phase 4)
+
+- `symfony-workflow` skill (~8.6 KB) — DI, Doctrine, Messenger,
+  voters, Twig, console.
+- `nextjs-patterns` skill (~9.9 KB) — App Router, RSC boundaries,
+  Server Actions, caching, route handlers, 14.x↔15.x deltas.
+- README stack table now separates Symfony / Next.js / Zend-Laminas
+  rows; "Deepest reference stack" paragraph names the workflow-grade
+  second tier explicitly.
+
+### Architecture cleanup (Phase 5)
+
+- Auto-rules (`non-destructive-by-default`, `scope-control-policy`)
+  audited: already refactored to trigger + Iron Law + pointer shape;
+  bound by the kernel-budget linter at 4 000-char override ceiling
+  (P5.1).
+- Rule-Interaction matrix marked rule-only by design;
+  [`rule-interactions.md`](rule-interactions.md) § "Out of scope —
+  orchestration surfaces" points at `decision-engine-gates`,
+  `decision-trace-v1`, `agent-memory-contract`, `memory-visibility-v1`,
+  and the `ai-council` skill for Council × Memory × Work-Engine
+  interactions (P5.2).
+- `type: orchestrator` frontmatter tag exempts cluster routers from
+  the `command_missing_skill_references` linter check; 15 commands
+  carry the tag (P5.3).
+- Beta-review marker protocol shipped in [`STABILITY.md`](STABILITY.md)
+  § Beta-review markers; `scripts/check_beta_review_markers.py` wired
+  into `task ci`; 39 beta contracts back-filled (P5.4).
+- Test-redundancy audit produced
+  [`step-5-test-cleanup.md`](../../agents/roadmaps/step-5-test-cleanup.md)
+  — audit-only, no deletions (P5.5).
+
+### Release-trunk discipline (Phase 1)
+
+- [`release-trunk-sync.md`](release-trunk-sync.md) protocol; CI gate
+  fails the release-prep branch when `main` is more than one tagged
+  release behind (P1.3).
+
+### Proof + cognition layers (Phases 6 + 7)
+
+- Memory-consequence in the trace: `affected` keys in
+  [`decision-trace-v1.md`](decision-trace-v1.md) (sibling P2.1a–c).
+- README three-audience split (sibling P2.2a–c).
+- Hook doctor (sibling P2.3).
+- Persona spine: Core-tier 5-section + Specialist-tier 7-section
+  spines locked in [`persona-schema.md`](persona-schema.md) (sibling
+  Block A).
+
+## What got cancelled
+
+- **P6.1 — Three real showcase sessions** (sibling P1.1–P1.4).
+  Cancelled upstream — capturing real host-agent sessions requires a
+  hosted-LLM runner that is out of scope for this roadmap. P1.0
+  pre-flight shipped; the capture surface is ready when a runner
+  exists. Reopen as `road-to-showcase-capture.md` once a runner is
+  on the table.
+- **P8.1 — End-to-end Level-6 smoke** — same gating as P6.1.
+  Structural coverage (`task smoke-quickstart` + decision-engine
+  schema validator + gate-evaluator unit tests) covers the
+  configuration surface deterministically; the live smoke remains
+  the manual pre-tag gate.
+
+## What stayed beta
+
+39 contracts carry `keep-beta-until: 2026-08-12` (next audit
+deadline). None met the 30-day promotion floor at audit time.
+First-commit age range: 0–12 days. Audit cap is 90 days from the
+audit date; CI rejects undated betas, multiple markers, and
+keep-beta-until dates beyond the window.
+
+## What got deferred to siblings
+
+- **Showcase capture** → future `road-to-showcase-capture.md` when a
+  hosted-LLM runner is on the table.
+- **Test-suite deletion** →
+  [`step-5-test-cleanup.md`](../../agents/roadmaps/step-5-test-cleanup.md)
+  (audit-only sibling spawned by P5.5; non-destructive by default).
+- **Persona Block B** (Architect / Risk-Officer extension) —
+  anti-recommended per the sibling closure decision; not deferred,
+  closed.
+- **Distribution / adoption** →
+  `road-to-distribution-and-adoption.md`, gated on this roadmap
+  closing (which this ADR records).
+- **MCP server work** — own strand, out of scope.
+
+## Consequences
+
+- **Steerable:** the Decision Engine now gates on configurable
+  thresholds; the configuration surface is documented and CI-tested.
+- **Provable:** memory hits/misses surface as `affected` keys in the
+  decision trace; the trace shape is contract-stable.
+- **Onboardable:** a fresh user can land at a working `/work`
+  invocation in three Quickstart steps without scrolling past the
+  fold.
+- **Multi-stack credible:** Laravel stays the deepest reference;
+  Symfony and Next.js shipped at workflow-grade depth; other stacks
+  remain project-analysis-only with the honest delta language in the
+  README.
+- **Architecturally tidy:** orchestrator commands no longer warn,
+  beta contracts cannot rot undated, and the contract surface itself
+  carries a periodic review obligation.

package/docs/contracts/adr-settings-sync-engine.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # ADR — Settings sync engine: stdlib-only round-trip

package/docs/contracts/adr-wing4-context-spine.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # ADR — Wing-4 context-spine: Money / Strategy / Ops slot extension

package/docs/contracts/agent-memory-contract.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Agent-Memory Contract (as expected by `agent-config`)

package/docs/contracts/agents-md-tech-stack.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Tech stack — deep detail

package/docs/contracts/audit-log-v1.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Audit-log v1

package/docs/contracts/command-clusters.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Command-cluster contract

package/docs/contracts/command-surface-tiers.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 

package/docs/contracts/context-paths.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Context-file path conventions

package/docs/contracts/cost-profile-defaults.md

@@ -0,0 +1,105 @@
+# Cost-Profile Defaults — Contract
+
+> **Status:** beta · **Owner:** package maintainer · **Last reviewed:** 2026-05-14
+>
+> Normative contract for the **default `cost_profile`** new installs receive.
+> Profile semantics themselves are documented in
+> [`docs/customization.md` § cost_profile](../customization.md) and
+> [`docs/contracts/rule-router.md`](rule-router.md); this file owns only the
+> **default-selection decision** and the rationale behind it.
+
+## Decision
+
+```
+DEFAULT_PROFILE = "balanced"
+```
+
+`scripts/install.py` and `npx @event4u/agent-config init` write
+`cost_profile: balanced` into `.agent-settings.yml` for fresh installs
+unless the user passes `--profile=minimal` or `--profile=full`.
+
+## Profile table
+
+| Profile | Contents | Token footprint | Use when |
+|---|---|---|---|
+| `minimal` | Kernel only (9 always-loaded Iron-Law rules, ≤ 26 k chars) | Lowest | Token-constrained agents (small context windows, free-tier models) or projects that opt out of routing |
+| **`balanced`** *(default)* | Kernel + tier-1 auto-rules (workflow + safety floor) | Medium | Every productized install — the documented "current behaviour superset" |
+| `full` | Kernel + tier-1 + tier-2 (every rule, every guideline-cited skill) | Highest | Teams running large-context models (Opus 4, GPT-5) that want maximum guardrail coverage |
+| `custom` | Ignore profile; every matrix value set explicitly | Variable | Power users tuning per-rule load decisions |
+
+## Why `balanced`, not `minimal`
+
+The kernel-only `minimal` profile predates the tier-1 router. It was the
+correct default while tier-1 was experimental, but four signals now point
+at `balanced`:
+
+1. **Documented intent already says so.** Both
+   `config/agent-settings.template.yml` (the source the installer projects
+   from) and `docs/customization.md` describe `balanced` as
+   "default — current behaviour superset". The code default of `minimal`
+   was a drift artifact, not a deliberate stance.
+2. **Productization (Level-6) demands sensible-default-out-of-the-box.**
+   A fresh `npx init` followed immediately by `/work` should engage the
+   full workflow guardrail set — `developer-like-execution`,
+   `verify-before-complete`, `minimal-safe-diff`, `scope-control`.
+   These live in tier-1, not the kernel. With `minimal`, the
+   work-engine runs unanchored against most quality guardrails.
+3. **Decision-engine gates assume tier-1 is present.** The P2.x gates
+   (`min_confidence`, `block_on_risk`, `require_memory_hits`) are
+   harmless under `minimal` but only reach their documented behaviour
+   under `balanced` and above — because the confidence model and
+   risk-classification rules they read live in tier-1.
+4. **Opt-out is cheap, opt-in is invisible.** A team that wants the
+   `minimal` floor flips one YAML value. A team that doesn't know
+   tier-1 exists never finds it. The default should err toward
+   guardrail coverage.
+
+## Opt-out path
+
+Token-budget pressure → flip in `.agent-settings.yml`:
+
+```yaml
+cost_profile: minimal
+```
+
+…or pass `--profile=minimal` to `npx @event4u/agent-config init`.
+No migration is required: removing tier-1 rules from a session has no
+state-machine impact because the kernel carries the Iron-Law floor.
+
+## Drift detection
+
+CI must keep three surfaces in sync:
+
+- `scripts/install.py` — `DEFAULT_PROFILE` constant.
+- `config/agent-settings.template.yml` — comment block on the
+  `cost_profile:` key.
+- `docs/customization.md` — cost-profile table default column.
+
+Reviewer guidance: a PR that changes any one of these must touch the
+other two **plus** this file's `Last reviewed:` field. The
+`docs-sync` rule enforces the cross-reference check; a missing update
+trips it.
+
+## Re-review schedule
+
+`re-review: 2026-11-14` (six months out). Triggers for earlier
+re-review:
+
+- Tier-1 rule count drops below 5 (the router would carry too little
+  to justify the load cost).
+- Median `npx init` token cost grows past 40 k for a fresh agent
+  session (then re-evaluate `minimal` as the default).
+- A consumer-project tally shows ≥ 80 % of installs override the
+  default within seven days (the default is wrong for the population).
+
+## Non-goals
+
+- This contract does **not** dictate what tier-1 contains. That belongs
+  to [`rule-router.md`](rule-router.md) and the `kernel-membership.md`
+  contract.
+- It does **not** add a fourth profile. `custom` covers the
+  per-tenant-tuning case; no new tier needed.
+- It does **not** auto-migrate existing installs. Projects already
+  pinned to `minimal` keep `minimal` until a developer edits the file
+  or runs `npx @event4u/agent-config migrate` (which preserves
+  user-set values per [`migration/v1-to-v2.md`](../migration/v1-to-v2.md)).

package/docs/contracts/cross-wing-handoff.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---