@event4u/agent-config 2.8.0 → 2.10.0

package/docs/contracts/decision-trace-v1.md

@@ -113,6 +113,36 @@ the trace inherits the **maximum** risk class across all files the
 phase touched. If no files were touched (pure planning phase), risk
 is `low`.
 
+## Memory consequence keys
+
+**Purpose.** Bound the surface area where a memory hit can be said
+to have *changed* an outcome. Closed list, not open — without this
+bound, every memory call risks the "memory affected everything"
+failure mode (Risk register row 2 of
+[`agents/roadmaps/road-to-proof-not-features.md`](../../agents/roadmaps/road-to-proof-not-features.md)).
+
+**Closed list (v1).** Exactly four keys. Adding a fifth requires a
+schema bump + entry under `### Breaking` in `CHANGELOG.md`.
+
+| Key | Source | Diff semantics |
+|---|---|---|
+| `confidence_band` | Top-level envelope field. | String inequality (`high` ≠ `medium` ≠ `low`). |
+| `risk_class` | Top-level envelope field. | String inequality. |
+| `applied_rules` | Derived: sorted list of `rules[].rule_id` where `applied == true`. | Set inequality. |
+| `test_plan` | Derived: sorted list of test paths captured in the Plan-phase `state.plan.tests` slice. May be `null` when the phase is not `plan` or no Plan-phase tests were captured. | Set inequality; `null` on either side suppresses the key from the diff. |
+
+**Diff semantics.** The producer renders two traces for the same
+phase: one **with** the memory entry consulted, one **without**
+(re-running the heuristic against `memory.hits` decremented by the
+entry's contribution). The `affected` field is the sorted list of
+keys above whose values differ between the two traces. Empty list
+means "consulted but no key diverged" — the call was informational,
+not load-bearing.
+
+**Out of scope for v1.** Gradations beyond binary key-diverged /
+not-diverged (overridden, combined, filtered). Tracked as a Phase-1-
+gated revisit in the same Risk register.
+
 ## Privacy floor
 
 - `memory.ids` carries opaque ids only — no entry bodies, no secrets.

package/docs/contracts/hook-architecture-v1.md

@@ -205,6 +205,50 @@ that:
 The dispatcher silently no-ops when called with `--platform copilot`;
 the fallback is consumed by reading the rule, not by hook invocation.
 
+## Fixture corpus — `tests/fixtures/hooks/`
+
+Replay-safe, platform-native payloads. One JSON file per event in the
+agent-config event vocabulary. Consumed by `./agent-config hooks:replay`
+and by the dispatcher replay tests
+(`tests/hooks/test_hooks_replay.py` — Phase 2.4c).
+
+```
+tests/fixtures/hooks/
+  session_start.json · session_end.json · user_prompt_submit.json
+  pre_tool_use.json  · post_tool_use.json · stop.json
+  pre_compact.json   · agent_error.json
+  README.md          — corpus contract + platform-shape table
+```
+
+Each fixture is a **stdin payload** — the dispatcher wraps it via
+`_build_envelope` before handing it to a concern. Required keys:
+
+- Valid JSON object at the top level.
+- `session_id` — string, non-empty (drives feedback dir naming).
+- Event-specific fields realistic enough that the bound concerns
+  (`chat-history`, `roadmap-progress`, `context-hygiene`,
+  `verify-before-complete`, `minimal-safe-diff`) run without raising
+  — primarily `tool_name` (for `*_tool_use`), `prompt` (for
+  `user_prompt_submit`).
+- No real user content. Committed alongside source; the redaction
+  workflow in [`hook-payload-capture`](../hook-payload-capture.md)
+  applies to **captured** payloads, not committed fixtures.
+
+The corpus is platform-shape-representative, not platform-exhaustive
+— multi-platform shape coverage lives in
+`tests/hooks/test_event_shape_contract.py`. The replay test asserts
+1:1 mapping between `EVENT_VOCABULARY` and this directory.
+
+## Replay mode — `AGENT_CONFIG_REPLAY=1`
+
+Concerns that write under `agents/state/` MUST honor the
+`AGENT_CONFIG_REPLAY` env var: when set to `1`, skip all state
+mutations and run as read-only. The dispatcher passes the env var
+through to subprocess concerns unchanged. Concerns that do not honor
+the flag are listed by `./agent-config hooks:doctor` as not
+replay-safe; replay tests assert no `agents/state/` mutation
+post-invocation.
+
 ## Stability
 
 Beta. Breaking changes between v1 and v2 are allowed in a minor
@@ -218,3 +262,5 @@ majors.
   operational how-to for capturing redacted live payloads to upgrade
   a platform's chat-history extractor from `docs-verified` to
   `payload-verified`.
+- [`tests/fixtures/hooks/README.md`](../../tests/fixtures/hooks/README.md)
+  — fixture corpus contract.

package/docs/contracts/mcp-beta-criteria.md

@@ -0,0 +1,129 @@
+---
+stability: experimental
+mcp_scope: lite
+---
+
+# MCP Beta Criteria — Promotion Gate (Hard Contract)
+
+> **Status:** Active · governs the `experimental → beta` promotion for
+> the MCP surface (`scripts/mcp_server/` local stdio kernel + the
+> hosted `workers/mcp/` bridge). Owned by Phase 3 of
+> [`road-to-surface-discipline.md`](../../agents/roadmaps/road-to-surface-discipline.md).
+> Companion contract:
+> [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md) (local) ·
+> [`mcp-cloud-scope.md`](mcp-cloud-scope.md) (hosted).
+
+## Purpose
+
+The current MCP wording uses `experimental` across READMEs, module
+docstrings, and the initialize-result server description. There is no
+defined bar for retiring that label. This contract names six gates
+that together flip `experimental → beta`. Every gate is **observable**
+(test file, doc, or script), **falsifiable** (red is allowed; missing
+is not), and **machine-reportable** through `agent-config doctor
+--check mcp-beta-readiness` (lands in Phase 3 Step 5).
+
+> **Iron Law:** all six gates must be green for the same release tag
+> before any user-visible surface drops `experimental`. A green gate
+> sheet on `main` does not authorize a back-dated wording change on a
+> release branch that did not also pass the sheet.
+
+## The six gates
+
+Each gate is owned by a single artefact. When the artefact is missing,
+Phase 3 Step 3 creates a **failing test** (`pytest.skip("pending: …",
+allow_module_level=True)` or `raise NotImplementedError("mcp-beta-gate-N
+pending")`) so the AC stays falsifiable.
+
+### Gate 1 — External-client end-to-end run
+
+At least one MCP client **outside this repo's own test harness** has
+completed a full session against MCP Lite: `initialize` →
+`prompts/list` → `prompts/get` → `resources/list` → `resources/read`
+→ shutdown. Evidence is a transcript or recorded session under
+`tests/mcp/external-clients/` plus the client name and version
+(Claude Desktop ≥ vX, Cursor ≥ vY, Zed ≥ vZ, Continue ≥ vW).
+
+### Gate 2 — Bearer-auth coverage
+
+`tests/mcp/auth/` must cover four cases against the hosted Worker
+surface — **happy path**, **401 on missing token**, **401 on expired
+token**, **401 → 200 on rotated token**. Each case asserts the wire
+envelope shape, not only the status code. Gate fails if any case is
+skipped, xfailed, or absent.
+
+### Gate 3 — Lite/Full parity smoke suite
+
+For every primitive the published surface exposes (`prompts/list`,
+`prompts/get`, `resources/list`, `resources/read`), a parametrized
+test asserts the response body from the hosted Worker (Lite) and the
+local stdio kernel (Full) **byte-identical** (modulo the documented
+deltas in `mcp-cloud-scope.md § Lite vs Full`). Failure must surface
+the diff, not just a boolean.
+
+### Gate 4 — Health endpoint under load
+
+The hosted Worker exposes `/healthz` (or equivalent) that returns a
+structured JSON envelope `{status, uptime_s, build_sha,
+last_content_refresh}`. A k6 / wrk smoke test in
+`tests/mcp/load/healthz.k6.js` proves p95 < 200 ms across 60 s at 50
+RPS. The local stdio kernel surfaces the same envelope through a
+`server/health` JSON-RPC ping.
+
+### Gate 5 — Abuse / rate-limit plan
+
+`docs/contracts/mcp-rate-limit.md` exists and pins three knobs —
+per-token RPS, per-token daily quota, per-IP burst — with a fallback
+behaviour on overrun (`429` + `Retry-After`). The Worker enforces the
+knobs; a contract test in `tests/mcp/rate-limit/` asserts that
+exceeding any knob returns `429` with a non-empty `Retry-After`.
+
+### Gate 6 — Lite ↔ Full no-drift
+
+A nightly CI job runs the Phase 3 Step 3 parity suite (Gate 3) plus a
+canary: ingest one prompt and one resource on both surfaces, hash the
+body, and assert equality. Drift > 0 fails the job and posts a Slack
+ping. Evidence: the workflow file (`.github/workflows/mcp-no-drift.yml`)
+**and** at least one successful run within the last 7 days.
+
+## Promotion procedure
+
+1. Open a release-candidate branch named `release/mcp-beta-rcN`.
+2. Run `./agent-config doctor --check mcp-beta-readiness` — must
+   print all six gates green.
+3. Flip the wording in the **five** surfaces inventoried in
+   [`road-to-surface-discipline.md` Phase 3 Step 1](../../agents/roadmaps/road-to-surface-discipline.md):
+   `docs/mcp-server.md` (status banner + Remote-MCP sub-claim),
+   `README.md` (pointer line), `scripts/mcp_server/server.py`
+   (initialize-result `serverInfo.name`),
+   `scripts/mcp_server/__init__.py` (module docstring `Stability:`).
+4. Update the changelog with the gate sheet snapshot.
+5. Merge the RC branch through the normal review path. Tag is **not**
+   created until the gate sheet is reproducible on the merge commit.
+
+## Demotion procedure
+
+Any single gate going red on `main` for more than 7 consecutive days
+demotes the surface back to `experimental` at the next release. This
+is a wording-only demotion; no code is reverted. The doctor check
+reports the demotion automatically.
+
+## Surface delta
+
+This contract adds **0 new commands**, **0 new skills**, **0 new
+personas**. It defines a promotion gate; nothing more. Net surface
+delta for Phase 3: ≤ 0.
+
+## Cross-references
+
+- [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md) — local stdio kernel
+  hard contract (A0).
+- [`mcp-cloud-scope.md`](mcp-cloud-scope.md) — hosted Worker hard
+  contract (A0-cloud).
+- [`mcp-tool-stub-envelope.md`](mcp-tool-stub-envelope.md) — Phase 1
+  discovery contract.
+- [`STABILITY.md`](STABILITY.md) — stability tier definitions
+  (`experimental` / `beta` / `stable`) and what wording each tier may
+  use in user-visible surfaces.
+- [`road-to-surface-discipline.md`](../../agents/roadmaps/road-to-surface-discipline.md)
+  — Phase 3 acceptance criteria and step-level evidence pointers.

package/docs/contracts/memory-visibility-v1.md

@@ -24,6 +24,7 @@ and a single space:
 
 ```
 🧠 Memory: <hits>/<asks> · ids=[<comma-separated-ids>]
+🧠 Memory: <hits>/<asks> · ids=[<comma-separated-ids>] · affected: <keys>
 ```
 
 Examples:
@@ -32,6 +33,8 @@ Examples:
 🧠 Memory: 3/4 · ids=[mem_42, mem_57, mem_91]
 🧠 Memory: 0/2 · ids=[]
 🧠 Memory: 5/5 · ids=[mem_a01, mem_a02, mem_a03, …+2]
+🧠 Memory: 3/4 · ids=[mem_42, mem_57] · affected: confidence_band,applied_rules
+🧠 Memory: 2/4 · ids=[mem_42] · affected: none
 ```
 
 Cap at 5 ids inline; remainder rendered as `…+N`. The full id list
@@ -45,10 +48,15 @@ lives in the decision-trace JSON
 | `hits` | Count of `memory_retrieve_*` calls during this turn that returned ≥ 1 entry. |
 | `asks` | Count of `memory_retrieve_*` calls during this turn — both successful and empty. |
 | `ids` | Stable memory entry ids returned across all calls, deduped, ordered by retrieval timestamp. |
+| `affected` | Optional trailing segment. Comma-separated list of decision-trace keys that diverged when this memory was consulted vs not consulted. Closed key list defined in [`decision-trace-v1.md § Memory consequence keys`](decision-trace-v1.md#memory-consequence-keys). Rendered as `none` when `hits ≥ 1` but no key diverged. Omitted entirely when `hits == 0` or when the producer cannot compute a counterfactual trace. |
 
 `hits ≤ asks` is invariant. If `asks == 0`, the engine MUST suppress
 the line entirely — no `0/0` noise.
 
+The `affected` segment is a forward-compat trailing extension per
+the Stability clause below — clients pinned to the segment-free
+shape MUST still parse the line.
+
 ## Privacy floor
 
 The visibility line and the JSON it derives from MUST NOT contain:
@@ -88,6 +96,31 @@ counts and ids for downstream metrics.
 Cost-profile lookup respects `.agent-settings.yml`'s `cost_profile`
 key. Default is `standard`.
 
+## End-of-run "Memory changed decisions" block
+
+When the visibility line carries a non-empty `affected` segment, the
+engine MUST also append a structured block at the end of the run's
+report surface so reviewers can audit attribution without parsing
+the inline segment:
+
+```
+Memory changed decisions:
+- mem_42 → confidence_band
+- mem_57 → confidence_band
+```
+
+Rules:
+
+- Suppressed entirely when `affected` is empty or absent (no key
+  diverged, or memory was not consulted).
+- Each consulted id from the visibility line's `ids` is paired with
+  each affected key. v1 attribution is aggregate; per-id attribution
+  is a follow-up risk tracked in the roadmap Risk register.
+- Block heading is the literal string `Memory changed decisions:`
+  followed by `-` bullet lines in `<id> → <key>` shape.
+- Implementation: `format_changed_decisions_block` in
+  `work_engine/scoring/memory_visibility.py`.
+
 ## Audit-as-memory feed
 
 The visibility output produced by the engine is the input to the

package/docs/contracts/settings-sync-yaml-subset.md

@@ -0,0 +1,138 @@
+---
+stability: beta
+---
+
+# Settings-sync YAML subset
+
+**Purpose.** Pin the YAML feature set that `.agent-settings.yml` and
+`config/agent-settings.template.yml` may use, so contributors can cite a
+contract instead of inferring it from
+[`scripts/sync_yaml_rt.py`](../../scripts/sync_yaml_rt.py) source. The
+sync engine ([ADR](adr-settings-sync-engine.md)) is a custom stdlib-only
+round-trip parser/emitter; staying inside the subset below is what
+keeps user-line preservation (every byte of every user line round-trips
+unchanged unless the merger explicitly edits the key).
+
+Authoritative source: this document. The module docstring of
+`sync_yaml_rt.py` mirrors it; on drift, this file wins and the docstring
+is corrected to match.
+
+## Supported
+
+### Document shape
+
+- One YAML document per file. No `---` or `...` document separators.
+- UTF-8. CRLF and LF line endings — both accepted, preserved per-line.
+
+### Mappings (sections)
+
+- Block-style mappings only (`key: value` on its own line).
+- Indent: 2- or 4-space, **no tabs** in indent.
+- Nested mappings unlimited in depth (the template uses 3 levels —
+  e.g. `chat_history.archive.cleanup_after_days`).
+- Duplicate keys at the same level: **last wins** (the later line
+  carries the value; the earlier entry is replaced).
+
+### Scalars (values)
+
+- Bare scalars: `enabled`, `42`, `true`, `~`, `null`, `None`.
+- Single-quoted strings: `'literal text'`.
+- Double-quoted strings: `"literal text"`.
+- Bools, ints, `~` / `null` / `None` are kept **verbatim** — the
+  parser does not normalise `True` → `true` or `null` → `~`.
+
+### Lists (sequences of scalars)
+
+- Block-style lists:
+  ```yaml
+  allowlist:
+    - foo
+    - bar
+  ```
+  Indent inside the list must be consistent.
+- Inline-flow lists, **flat only**: `[a, b, c]`.
+- List items are scalars only. Nested mappings inside a list item are
+  **not** supported (see below).
+
+### Comments and blank lines
+
+- `#`-comments — full-line and inline (`key: value  # comment`). Both
+  preserved verbatim, including leading whitespace and the gap before
+  `#`.
+- Blank lines preserved verbatim — the engine never collapses them.
+
+## Not supported (parser raises `ValueError` with a line number)
+
+The following YAML features are out of contract. A user file that uses
+any of them surfaces as `ValueError` from `scripts/sync_yaml_rt.py:sync`,
+which `scripts/sync_agent_settings.py` catches and reports as **exit
+code 2** with a line-numbered message.
+
+- **Anchors and aliases** — `&name`, `*name`.
+- **Multi-document streams** — `---` / `...` separators.
+- **Nested flow mappings** — `key: {nested: value}` inline. Block-style
+  nested mappings are fine; flow-style nested mappings are not.
+- **Nested mappings inside list items** — `- name: foo` followed by
+  indented children. Lists hold scalars only.
+- **Complex keys** — `? [composite, key]: value`.
+- **Tagged scalars** — `!!str 42`, `!Custom value`.
+- **Multiline scalar styles** — `|` (literal) and `>` (folded) block
+  scalars.
+- **Tabs in indent** — even one tab character in indent.
+- **Mixed indent inside a block** — every child of a parent must share
+  the same indent.
+
+Pinned by `tests/test_sync_round_trip.py` (34 tests) — every
+not-supported feature has at least one fixture that asserts the
+`ValueError` message.
+
+## Test pinning
+
+- Verbatim round-trip: `tests/test_sync_round_trip.py::test_user_block_round_trip_is_idempotent`, `::test_three_level_idempotent`.
+- Out-of-subset rejection: same file, fixtures under
+  `tests/fixtures/sync_yaml_rt/` named `bad_*.yml`.
+- CLI exit code on malformed input:
+  `tests/test_sync_agent_settings.py::test_malformed_user_yaml_exits_2_with_message`.
+
+Any parser change is gated on those tests staying green. New fixtures
+for new features land under `tests/fixtures/sync_yaml_rt/`.
+
+## Why this subset (and why it is fixed)
+
+The driving requirement from
+[`layered-settings`](../guidelines/agent-infra/layered-settings.md) is
+**verbatim user-line preservation**. `ruamel.yaml` and PyYAML both
+re-emit through their own emitters, which normalises whitespace,
+quoting, and blank-line placement. A stdlib parser limited to this
+subset gives byte-identity across two consecutive syncs — the property
+the merger relies on for additive insertion.
+
+Out-of-subset YAML therefore is not a parser bug; it is a contract
+violation by the user file. The friendly `ValueError` and exit code 2
+are the contract's failure surface.
+
+## Revisit triggers
+
+This subset is **fixed** until one of the
+[ADR revisit triggers](adr-settings-sync-engine.md#revisit-triggers)
+fires — namely:
+
+1. `.agent-settings.yml` schema gains a YAML feature outside the subset
+   (anchors, multi-doc, complex keys, nested flow mappings) — the cost
+   of extending the parser exceeds the cost of adopting `ruamel.yaml`.
+2. The verbatim-preservation contract is relaxed — the driver for the
+   custom parser is gone.
+3. The 0-dep posture for Python tooling is dropped at the package level
+   — the marginal cost of one more dep collapses.
+4. A maintenance bug surfaces in the engine that ruamel's mature spec
+   coverage would have prevented.
+
+A new ADR (with successor link) is required to change the subset; this
+document is updated in the same commit.
+
+## See also
+
+- [`docs/contracts/adr-settings-sync-engine.md`](adr-settings-sync-engine.md) — decision record for the stdlib-only engine.
+- [`docs/guidelines/agent-infra/layered-settings.md`](../guidelines/agent-infra/layered-settings.md) § Sync rules — the additive-merge-with-user-line-preservation contract this subset implements.
+- [`scripts/sync_yaml_rt.py`](../../scripts/sync_yaml_rt.py) — implementation; module docstring mirrors this file.
+- [`scripts/sync_agent_settings.py`](../../scripts/sync_agent_settings.py) — CLI driver and exit-code contract.

package/docs/guidelines/wing4-handoff.md

@@ -0,0 +1,127 @@
+# Wing-4 Handoff
+
+Wing-4-specific prose for the four load-bearing senior-skill chains
+in the Money / Strategy / Operations cluster. The mechanical contract
+— initiator → delegated(input) → output-artifact, lint rules, worktree
+boundary — lives in
+[`docs/contracts/cross-wing-handoff.md`](../contracts/cross-wing-handoff.md).
+The cross-wing routing prose (when to hand off at all, L4 / C8
+boundary, decision tree) lives in
+[`docs/guidelines/cross-role-handoff.md`](cross-role-handoff.md). The
+Wing-3 sibling — chains inside GTM / Growth — lives in
+[`docs/guidelines/gtm-handoff.md`](gtm-handoff.md). This guideline
+covers **what crosses each Wing-4 boundary**, **what the typed
+artifact looks like**, and **who owns the failure mode when the
+chain breaks**.
+
+Cycle / dangling / tier-mismatch enforcement is not duplicated here —
+`task lint-handoffs` (per cross-wing-handoff § 4) is the mechanical
+gate.
+
+## Chain 1 — money → strategy
+
+Three-step chain that turns unit-economics cognition into a
+build-buy-partner verdict. Finance cluster owns the first two steps;
+the cluster line crosses on the handoff to Strategy.
+
+```
+unit-economics (O1)
+  → scenario-modeling (O4)
+    → build-buy-partner (P1)
+```
+
+| Step | Hands off when | Typed artifact crossing the boundary | Failure-mode owner |
+|---|---|---|---|
+| O1 → O4 | CAC / LTV / contribution-margin / payback-period cognition locked for the segment. | `unit-economics-frame.md` — CAC / LTV ratio, contribution margin, payback band, burn-multiple verdict, segment scope. | O1 owns drift: a margin frame O4 cannot stress-test = O1's unit definition was wrong scope. |
+| O4 → P1 | Three-statement scenarios + sensitivity bands + optionality reasoning locked across at least two cases. | `scenario-set.md` — base / upside / downside cases, sensitivity table, decision-relevant variables, optionality cost per case. | O4 owns drift: scenarios without an optionality-cost row force P1 to re-derive build-vs-buy economics. |
+
+P1 self-closes against `build-buy-partner.md` — insource-vs-outsource-
+vs-acquire verdict, integration-cost band, dependency-risk score,
+exit-cost analysis.
+
+## Chain 2 — strategy → people
+
+Two-step chain that turns a build-buy-partner verdict into an
+org-design shape. Strategy cluster ships the verdict; People-Strategy
+cluster reads it as input and owns the structure decision.
+
+```
+build-buy-partner (P1)
+  → org-design (Q1)
+```
+
+| Step | Hands off when | Typed artifact crossing the boundary | Failure-mode owner |
+|---|---|---|---|
+| P1 → Q1 | Insource-vs-outsource verdict + dependency-risk profile + integration-cost band locked. | `build-buy-verdict.md` — verdict (build / buy / partner / acquire), capability scope, dependency-risk score, integration cost, exit cost, optionality preservation note. | P1 owns drift: a verdict without exit-cost reasoning leaves Q1 designing teams against an unowned constraint. |
+
+Q1 self-closes against `org-design-shape.md` — team-shape (functional /
+cross-functional / squad), span-of-control band, Conway's-law alignment
+note, reorg-cost ledger.
+
+## Chain 3 — people → EM
+
+Two-step chain that specializes a generalized hiring loop for
+engineering. People-Strategy cluster owns the generalized cognition;
+Engineering-Manager cluster owns the engineering specialization.
+
+```
+hiring-loop-design (Q-generalized, composed inside `org-design`)
+  → hiring-loop-design × eng-context (S2)
+```
+
+| Step | Hands off when | Typed artifact crossing the boundary | Failure-mode owner |
+|---|---|---|---|
+| Q → S2 | Generalized loop stages + calibration-design + signal-vs-noise audit locked at people-strategy level. | `hiring-loop-shape.md` — stage list, per-stage signal, calibration cadence, bar-raiser logic, signal-vs-noise findings. | Q owns drift: a generalized loop without a calibration cadence forces S2 to invent one for engineering and the cognition diverges from the rest of the org. |
+
+S2 self-closes against `eng-hiring-loop.md` — eng-specific stage
+specialization (screen → take-home / system-design / coding /
+behavioral / leadership), per-stage rubric, bar-raiser assignments,
+candidate-throughput target.
+
+## Chain 4 — finance → GTM
+
+Cross-wing chain — the only Wing-4 chain whose endpoint sits in
+Wing 3. Finance owns the **cognition**; RevOps owns the **call**.
+Interface-first-stub per iter-2 OQ4: O2-interface ships before the
+H10 sibling can start, parallel to O2 implementation.
+
+```
+forecasting (O2)
+  → forecast-accuracy (H10, Wing 3)
+```
+
+| Step | Hands off when | Typed artifact crossing the boundary | Failure-mode owner |
+|---|---|---|---|
+| O2 → H10 | `forecast-construction-shape` ADR locked: top-down vs bottom-up enum, confidence-band signature, retro-loop signature. | `forecast-band.json` — commit value, best-case value, pipeline value, confidence band, retro signature, construction-shape tag. | **Interface contract owned by O2** (per cross-wing-handoff § 5 / W4 chain): if the ADR drifts, O2 breaks the contract, not H10. Mirrors `gtm-handoff.md` Chain 2 H10 → O2 framing from the Wing-3 side. |
+
+H10's parallel-development rule (starts after O2-interface ≥ 100 %,
+runs in parallel with O2 implementation) is recorded in the
+`road-to-money-strategy-ops.md` O2 entry, the
+`road-to-gtm-and-growth.md` H10 entry, and the cross-wing-handoff
+contract — not duplicated here.
+
+## Reading the failure-mode column
+
+The column answers one question: **when a downstream skill cannot
+do its job, which upstream skill rewrites its artifact?** The owner
+is the **upstream** skill, not the consumer — drift is always a
+producer-side fix. This mirrors the W3 sibling and the W4 / W3
+forecasting chain in the contract (O2 owns the interface; H10 only
+consumes it).
+
+## See also
+
+- [`docs/contracts/cross-wing-handoff.md`](../contracts/cross-wing-handoff.md)
+  — typed-handoff mechanical contract; `task lint-handoffs` enforces
+  cycles, dangling references, and tier mismatches over the graph.
+- [`docs/guidelines/cross-role-handoff.md`](cross-role-handoff.md)
+  — when to hand off at all, how to phrase the routing, L4 / C8
+  boundary.
+- [`docs/guidelines/gtm-handoff.md`](gtm-handoff.md) — Wing-3 sibling
+  for the brand → channel, discovery → pipeline, and funnel →
+  retention chains.
+- [`docs/contracts/context-spine.md`](../contracts/context-spine.md)
+  § Wing-4 slots — `fiscal-period`, `org-stage`, `regulatory-regime`;
+  every chain step opts into ≥ 1 slot or carries an ADR opt-out.
+- [`docs/contracts/adr-wing4-context-spine.md`](../contracts/adr-wing4-context-spine.md)
+  — durable record for the Wing-4 slot extension.

package/docs/mcp-server.md

@@ -1,6 +1,6 @@
 # MCP Server
 
-> Status: **experimental** — Phase 1 + 2 + 3 shipped. No `tools/*` primitive yet (Phase 4, deferred behind a design call).
+> Status: **experimental** — Phase 1 + 2 + 3 shipped. No `tools/*` primitive yet (Phase 4, deferred behind a design call). Promotion to **beta** is gated on the six criteria in [`docs/contracts/mcp-beta-criteria.md`](contracts/mcp-beta-criteria.md); current gate status: `./agent-config doctor --check mcp-beta-readiness` (Phase 3 of `road-to-surface-discipline.md`).
 
 `agent-config` ships a built-in [Model Context Protocol](https://modelcontextprotocol.io)
 server that exposes the package's read-only governance surface to MCP-aware

package/docs/readme-split-plan.md

@@ -0,0 +1,102 @@
+# README three-audience split — plan
+
+Annotated outline for `P2.2a` in
+[`road-to-proof-not-features.md`](../agents/roadmaps/road-to-proof-not-features.md).
+Decides the **information architecture**, not the prose. No content
+rewrite happens in this step; `P2.2b` applies the mapping.
+
+## Target headings (top of README, in order)
+
+1. **Use it in your project** — anchor `#use-it`
+2. **Prove it** — anchor `#prove-it`
+3. **Contribute** — anchor `#contribute`
+
+Each branch opens with one paragraph + one primary CTA. AI Council is
+not mentioned in any branch (verified by `P3.4`).
+
+### Anchor-stability promise
+
+`P2.2b` must keep these existing anchors intact so external inbound
+links survive:
+
+| Anchor today | Lives under (new) | Why |
+|---|---|---|
+| `#quickstart` | `#use-it` | npm/composer search results, social links |
+| `#supported-tools` | `#use-it` | most-cited section on the web |
+| `#what-your-agent-is-asked-to-do` | `#prove-it` | linked from blog posts |
+| `#documentation` | `#use-it` | docs portal entry |
+| `#development` | `#contribute` | contributor guides |
+
+Other section anchors may be renamed; `lint-readme` checks the table
+above and the three new audience anchors only.
+
+## Block-by-block mapping
+
+Every existing top-of-README block, in source order, mapped to
+exactly one branch. "Drop" = block is retired; "Move" = relocated as-
+is; "Reframe" = block stays but its lead-in / CTA changes (still no
+copy rewrite in this step — the reframe direction is decided here,
+applied in `P2.2b`).
+
+| # | Block (current heading) | Lines | Branch | Action | Notes |
+|---|---|---|---|---|---|
+| 1 | Title + tagline + stats badge | 1–13 | — | Keep above branches | Survives unchanged; counts updated by `update_readme_counts`. |
+| 2 | `## Start here` (three-paths table) | 15–25 | — | **Drop** | Replaced by the three branch sections themselves; rows map cleanly: `/onboard` → Use, `task ci` → Contribute, `task generate-tools` → Use. |
+| 3 | `## Quickstart` lead-in | 27–39 | Use it | Move | Becomes the opening paragraph under `#use-it`. |
+| 4 | `### For teams (recommended)` | 40–79 | Use it | Move | Primary CTA for `#use-it`. |
+| 5 | `### Pick specific AIs` | 81–101 | Use it | Move | Stays under Quickstart subtree. |
+| 6 | `#### Global install` | 103–124 | Use it | Move | Subsection of Pick specific AIs. |
+| 7 | `### For individual use (optional)` | 126–144 | Use it | Move | Alternate install path. |
+| 8 | `### Self-hosted MCP on Cloudflare` | 146–226 | Use it | Move | Operator install path; deep but consumer-facing. |
+| 9 | `#### Lock your Worker behind Bearer` | 196–213 | Use it | Move | Subsection of MCP block; stays nested. |
+| 10 | `### Optional: persistent agent memory` | 228–247 | Use it | Move | Companion package install. |
+| 11 | `## 2-minute demo: /implement-ticket` | 251–285 | Prove it | Move | Flagship evidence surface. Primary CTA for `#prove-it`. |
+| 12 | `### Sibling entrypoint: /work` | 287–316 | Prove it | Move | Same engine, second envelope. |
+| 13 | `### Product UI track` | 318–347 | Prove it | Move | Third evidence surface. |
+| 14 | `## What your agent is asked to do` | 351–365 | Prove it | Move | Intent table — proof of behaviour, not features. |
+| 15 | `## What this package is — and what it isn't` | 369–398 | Prove it | Move | Scope-honesty surface; loadbearing for the "proof" framing. |
+| 16 | `## You don't need everything` (cost profiles) | 402–423 | Prove it | Reframe | Currently sits as "feature" prose; the new framing is "proof that the package shrinks to fit". |
+| 17 | `## Who this is for` (stack coverage) | 427–439 | Prove it | Move | Honest depth claim — also evidence-side. |
+| 18 | `## Featured Skills` | 443–462 | Use it | Move | Catalog teaser → consumer surface. |
+| 19 | `## Featured Commands` | 466–481 | Use it | Move | Catalog teaser → consumer surface. |
+| 20 | `## Supported Tools / Project-installed` | 487–527 | Use it | Move | Per-tool install matrix. |
+| 21 | `## Supported Tools / Plugin-installed` | 529–541 | Use it | Move | Subsection. |
+| 22 | `## Supported Tools / Cloud / Hosted-agent` | 543–558 | Use it | Move | Subsection. |
+| 23 | `## Core Principles` | 562–570 | Prove it | Move | Behavioural floor — proof-side. |
+| 24 | `## Documentation` (index table) | 574–589 | Use it | Move | Doc portal entry. |
+| 25 | `### Maintainer telemetry (opt-in)` | 591–608 | Contribute | Move | Engagement measurement — maintainer / contributor surface. |
+| 26 | `### Context-aware command suggestion` | 610–629 | Use it | Move | Consumer-facing feature toggle. |
+| 27 | `## Development` | 633–642 | Contribute | Move | Primary CTA for `#contribute`. |
+| 28 | `## Requirements` | 644–649 | Use it | Move | Install gate — Use-side, not Contribute. |
+| 29 | `## License` | 651–653 | — | Keep at bottom | Footer; outside the three branches. |
+
+## Branch outlines (post-migration shape)
+
+### `## Use it in your project`
+
+Opening paragraph: one-line "Two minutes from npx to a better-behaved
+agent." Primary CTA: `npx @event4u/agent-config init`. Children:
+Quickstart subtree (#3–#7), MCP operator path (#8–#9), optional memory
+(#10), Featured Skills + Commands (#18–#19), Supported Tools (#20–#22),
+Documentation (#24), Command suggestion (#26), Requirements (#28).
+
+### `## Prove it`
+
+Opening paragraph: one-line "What the agent actually does, with
+evidence." Primary CTA: `/implement-ticket` demo (#11). Children:
+`/work` (#12), Product UI track (#13), Intent table (#14), Scope
+statement (#15), Cost profiles reframed (#16), Stack coverage (#17),
+Core Principles (#23).
+
+### `## Contribute`
+
+Opening paragraph: one-line "Editing rules, skills, commands — the
+contributor loop." Primary CTA: `task ci` (#27). Children: Maintainer
+telemetry (#25). External links: `CONTRIBUTING.md`, `AGENTS.md`,
+`docs/development.md`.
+
+## Verification (P2.2c preview)
+
+Grep-based test asserts `## Use it in your project`, `## Prove it`,
+`## Contribute` appear in that order. `lint-readme` keeps anchor
+stability for the rows in the Anchor-stability promise table.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.8.0",
+    "version": "2.10.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,