@event4u/agent-config 2.7.0 → 2.9.0

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

@@ -0,0 +1,125 @@
+---
+stability: beta
+---
+
+# ADR — Wing-4 context-spine: Money / Strategy / Ops slot extension
+
+> **Status:** Decided · 2026-05-13
+> **Builds on:** [`context-spine.md`](context-spine.md) — tri-slot cross-wing
+> contract (`product`, `team`, `repo`) locked at 3 by council Q1
+> (2026-05-05 KEEP-3, unified-senior-roles iter 1) plus the wing-scoped
+> track established by [`adr-gtm-context-spine.md`](adr-gtm-context-spine.md).
+> **Defers to:** [`cross-wing-handoff.md`](cross-wing-handoff.md) — typed
+> handoff contract; orthogonal to slot membership.
+
+## Decision
+
+The context-spine adds **three Wing-4-specific slots** under
+`agents/context-spine/`: `fiscal-period`, `org-stage`,
+`regulatory-regime`. The schema enum in
+[`scripts/schemas/skill.schema.json`](../../scripts/schemas/skill.schema.json)
+extends from
+`{product, team, repo, channel-stage, funnel-stage, customer-segment}`
+to additionally include
+`{fiscal-period, org-stage, regulatory-regime}`.
+
+The KEEP-3 lock from council Q1 still applies to **cross-wing slots**.
+The Wing-4 slots are **wing-scoped** under § 5 of the contract: they
+exist for the Money / Strategy / Ops cluster (Block O–S, 18 skills)
+and the Wing-4 personas (Block T, 4 personas). Engineering,
+Foundation, and GTM wings do not opt into them.
+
+| Slot | Path | Typical content |
+|---|---|---|
+| `fiscal-period` | `agents/context-spine/fiscal-period.md` | Reporting cadence (monthly · quarterly · annual · multi-year-plan), fiscal-year start, close-window timing. Read by O1 (`unit-economics`), O2 (`forecasting`), O3 (`runway-cognition`), O4 (`scenario-modeling`). |
+| `org-stage` | `agents/context-spine/org-stage.md` | Stage label (seed · series-A · series-B · growth · public), funding posture, headcount band, governance posture. Read by P1 (`build-buy-partner`), P4 (`vision-articulation`), Q1 (`org-design`), Q2 (`comp-banding`), S2 (`hiring-loop-design`). |
+| `regulatory-regime` | `agents/context-spine/regulatory-regime.md` | Active regimes (none · GDPR · HIPAA · SOC2 · PCI · CCPA), data-residency posture, breach-notification timer. Read by P5 (`contracts-cognition`), P6 (`privacy-review`), P7 (`data-handling-judgment`). |
+
+## Why this was a real question
+
+Three options were on the table:
+
+1. **Force-fit into existing slots.** Stuff fiscal cadence into
+   `team`, stage into `repo`, regulatory regime into `product`.
+   Rejected: each slab is owned by a different wing and Wing-4 reads
+   would mix tenant-of-record semantics (stage is not codebase
+   shape, regulatory regime is not product scope).
+2. **Wing-4-only frontmatter key.** Add `wing4_spine: [...]` parallel
+   to `context_spine`. Rejected for the same reason as Wing-3 ADR:
+   two spines duplicate the read-discipline mechanism, the lint
+   gate, and the skill-author cognitive load.
+3. **Extend the spine, scope the slots.** Accepted: same mechanism,
+   same lint gate, same opt-in discipline; slot names carry the
+   wing scope (`fiscal-period`, `org-stage`, `regulatory-regime`
+   are visibly Money / Strategy / Ops shaped).
+
+## Citation-evidence gating — prospective
+
+Per § 5 wing-scoped track, the citation chain is **prospective**: the
+roadmap (J1 → O / P / Q / S → T) ships citing skills in the same
+iteration. The ADR is the gating artefact (not the citations); each
+Block O / P / Q / S skill cites ≥ 1 of the three new slots in its
+frontmatter or carries a one-line ADR-opt-out comment in the skill
+body.
+
+The J2 linter (council Q7 boundary tests) enforces stage-agnosticism,
+which is orthogonal — a skill can cite `org-stage` for context
+without prescribing stage-specific thresholds (e.g. `runway-cognition`
+reads the stage to colour heuristics, but the procedure must remain
+readable across seed and public).
+
+## Migration plan for the existing senior catalog
+
+- **No retrofitting required.** Existing senior skills keep their
+  current `context_spine` declarations. Wing-3 skills MAY add a
+  Wing-4 slot if their cognition genuinely reads it (e.g. a Growth
+  PM reading `regulatory-regime` to scope activation experiments);
+  they MUST NOT be retrofitted mechanically.
+- **Opt-out for off-wing skills.** Engineering / Foundation senior
+  skills do not need to mention the Wing-4 slots in any way. The
+  schema accepts subsets — declaring only `[product, team]` remains
+  valid.
+- **Slot-file authoring is consumer-side.** The package ships the
+  contract; consumer projects fill
+  `agents/context-spine/fiscal-period.md` etc. when adopting Wing-4
+  skills. Missing slot file is graceful per § 4 of the contract.
+
+## Counter-evidence the agent should listen for
+
+Three signals that this decision is wrong and the ADR needs revisiting:
+
+1. **Off-wing skills start declaring Wing-4 slots.** If an
+   Engineering skill cites `org-stage`, the slot is misnamed or the
+   wing boundary is leaking. Re-scope the slot or rename it.
+2. **Wing-4 skills consistently ignore the slot they declared.** If
+   Block P privacy skills declare `regulatory-regime` but never
+   quote it in their procedure, the slot is decorative and should be
+   deleted.
+3. **A fourth Wing-4 slot is proposed within the same iteration.**
+   That is slot-sprawl on the same wing — Block J2 boundary tests
+   should reject the addition until a follow-up ADR documents why
+   three slots are insufficient.
+
+## Distinction from Wing-3 ADR
+
+`adr-gtm-context-spine.md` extends the spine with **flow-state slots**
+(funnel stage, channel stage, customer segment) — slabs that change
+*every quarter* as the GTM motion evolves. Wing-4 extends the spine
+with **constraint slots** (fiscal cadence, org stage, regulatory
+regime) — slabs that change *every fundraise / audit / boundary
+expansion*. Both extensions follow § 5 wing-scoped track; their
+combined accept means the spine schema now declares 9 slots (3
+cross-wing + 3 Wing-3 + 3 Wing-4). Any fourth slot at any wing
+re-opens the slot-sprawl risk and needs a separate ADR.
+
+## See also
+
+- [`context-spine.md`](context-spine.md) § 2 (slot table — extended),
+  § 5 (slot-add policy — wing-scoped track).
+- [`adr-gtm-context-spine.md`](adr-gtm-context-spine.md) — Wing-3
+  reference ADR this one composes against.
+- [`scripts/schemas/skill.schema.json`](../../scripts/schemas/skill.schema.json)
+  — `context_spine.items.enum` extended in this ADR.
+- [`.agent-src.uncompressed/rules/skill-quality.md`](../../.agent-src.uncompressed/rules/skill-quality.md)
+  § Senior-Tier Required Structure — the four blocks every senior
+  skill ships independently of spine opt-in.

package/docs/contracts/command-clusters.md

@@ -194,7 +194,48 @@ future cluster expansion.
   steps, `## Migration` notice, `## Rules` block.
 - Fails CI if a new cluster invents a different dispatch shape.
 
+## Tier-usage signal contract
+
+Empirical retiering needs evidence; evidence needs a signal. The minimum signal the package collects to validate command tiering, with **zero new external surface** and the same privacy floor as artefact-engagement telemetry:
+
+| Field | Type | Source | Notes |
+|---|---|---|---|
+| `ts_bucket` | str (ISO-8601 UTC, hour-resolution) | clock at invocation | hour-bucket, not raw timestamp — limits re-identification |
+| `command` | str | dispatcher | the cluster + sub-command (`fix:ci`, `commit`, `work`) — never argv |
+| `tier` | int (0/1/2/3) | `command-surface-tiers.md` lookup at invocation | the tier the command had **at the time of the call** |
+| `outcome` | str | dispatcher exit shape | one of `success` / `error` / `blocked` — no message bodies |
+| `user_hash` | str (sha256 first 16 hex chars) | hash of `$USER` + machine-id salt | distinct-user counting **without** identity recovery — never raw login |
+
+**Forbidden — never recorded, enforced at the four privacy layers:**
+
+- argv, flags, file paths, file contents.
+- error messages, stdout, stderr.
+- tickets, branch names, repo slugs.
+- exact timestamps (only hour-buckets), exact env-var values.
+- the user's name, email, or IP.
+
+**Storage.** Append to `.agent-tier-usage.jsonl` (consumer-project root; configurable via `telemetry.tier_usage.output.path`). Separate file from `.agent-engagement.jsonl` — orthogonal signals, separate retention defaults, separate opt-in.
+
+**Settings gate.** `telemetry.tier_usage.enabled` (default `false`, same opt-in posture as artefact-engagement). When disabled, the dispatcher records nothing and incurs zero file IO — the default-off doctrine carries over.
+
+**Aggregation.** Local-only, hour-bucketed counts: `(command, tier) → invocation_count` and `(command, tier) → distinct_user_count`. No remote upload anywhere in scope.
+
+## Empirical retiering rule
+
+A command **stays at Tier-0** at the next minor release only if **both** floors clear:
+
+- **Frequency floor.** ≥ N invocations across the trailing W-day window — defaults `N = 20`, `W = 30` (tunable via `.agent-settings.yml` `telemetry.tier_usage.retier`).
+- **Distinct-user floor.** ≥ K distinct `user_hash` values across the same window — default `K = 3`.
+
+A command that fails either floor drops to **Tier-1** at the next minor release; the release notes cite the floor that failed. Promotion the other way (Tier-1 → Tier-0) follows the same rule symmetrically and additionally requires explicit listing in `command-surface-tiers.md`.
+
+**Authority.** This is a maintainer decision aid, not an autonomous rule — the dispatcher records, `scripts/telemetry/tier_usage_report.py` reports, the maintainer files the move in the next minor release. No runtime tier-flipping.
+
+**Floor governance.** N / W / K live in `.agent-settings.yml`; bumping them is a contract change (this file), not a settings change.
+
 ## See also
 
 - [`docs/migrations/commands-1.15.0.md`](../migrations/commands-1.15.0.md) — user-facing migration notes.
 - [`docs/contracts/STABILITY.md`](STABILITY.md) — `beta` level rules apply.
+- [`docs/contracts/command-surface-tiers.md`](command-surface-tiers.md) — what each tier means and what `--help` surfaces.
+- [`.agent-src.uncompressed/contexts/contracts/artifact-engagement-flow.md`](../../.agent-src.uncompressed/contexts/contracts/artifact-engagement-flow.md) — sibling telemetry surface; same privacy floor and four-layer enforcement model.

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

@@ -1,3 +1,8 @@
+---
+stability: beta
+---
+
+
 # Command Surface Tiers
 
 > **Status:** Active. Defines the tiering contract for the two
@@ -36,17 +41,15 @@ The path a new contributor walks on day one. Visible in
    commitment to two-release stability).
 3. **No prerequisite tooling beyond `bash` + `python3`.** Docker,
    GPG, jq, gh CLI, npm globals are all Tier-1+ territory.
-4. **Cited in the `init → sync → validate → work` outcome path**
-   OR cited by a Hard-Floor safety rule
-   (`commit`, `keys:install-*`) OR is the AI-Council entry point
-   that the daily workflow depends on (`council:*`).
+4. **Cited in the `init → sync → validate → work` outcome path.**
+   Setup helpers (`first-run`, `keys:install-*`) and AI-Council entry
+   points (`council:*`) are **not** Tier-0 — they are run once-per-
+   project or on-demand, not in the daily loop. They live at Tier-1.
 
-**Canonical Tier-0 members (2026-05-13):**
+**Canonical Tier-0 members (2026-05-13, post-`road-to-surface-discipline`):**
 
-- CLI: `init`, `sync`, `validate`, `work`, `first-run`,
-  `keys:install-anthropic`, `keys:install-openai`,
-  `council:estimate`, `council:run`, `council:render`,
-  `implement-ticket`, `help`, `--version`.
+- CLI: `init`, `sync`, `validate`, `work`, `implement-ticket`,
+  `help`, `--version`.
 - Slash: `/onboard`, `/commit`, `/work`, `/implement-ticket`,
   `/agent-status`, `/agent-handoff`.
 
@@ -68,6 +71,24 @@ view. Documented in the same surface as Tier-0.
 3. **Orchestrator dispatch surface.** Top-level slash orchestrators
    whose children carry the actual work (`/roadmap`, `/feature`,
    `/fix`, `/judge`, `/memory`, `/optimize`, `/council`).
+4. **Once-per-project or on-demand setup helper.** Commands invoked
+   to bootstrap or rotate credentials, not in the daily loop
+   (`first-run`, `keys:install-anthropic`, `keys:install-openai`,
+   `council:estimate`, `council:run`, `council:render`).
+
+**Canonical Tier-1 CLI members (2026-05-13, post-`road-to-surface-discipline`):**
+
+`update`, `versions`, `global`, `export`, `uninstall`, `prune`,
+`doctor`, `migrate`, `first-run`, `keys:install-anthropic`,
+`keys:install-openai`, `council:estimate`, `council:run`,
+`council:render`.
+
+**Surface-trim changelog (2026-05-13):** Six CLI commands moved
+Tier-0 → Tier-1: `first-run` (run once per project), `keys:install-anthropic` /
+`keys:install-openai` (one-time credential setup), `council:estimate` /
+`council:run` / `council:render` (on-demand review tool, not daily
+driver). Commands stay invokable by full name; only `--help`
+surfacing changed.
 
 ### Tier-2 — maintenance / internal
 

package/docs/contracts/context-spine.md

@@ -32,8 +32,11 @@ Three failure modes the spine prevents:
 
 ## § 2 — Slot definitions
 
-The spine has **exactly three slots**. Council Q1 verdict (2026-05-05,
-KEEP-3): slot count is locked; extensions require an ADR (§ 5).
+The spine has **three cross-wing slots** plus **per-wing extension
+slots** authorized via ADR. Council Q1 verdict (2026-05-05, KEEP-3)
+locks the cross-wing slot count at 3. Per-wing extensions follow § 5.
+
+### Cross-wing slots (locked at 3)
 
 | Slot | Path under `agents/context-spine/` | Owner | Typical content |
 |---|---|---|---|
@@ -41,6 +44,22 @@ KEEP-3): slot count is locked; extensions require an ADR (§ 5).
 | `team` | `team.md` | RevOps / maintainer wing | Who **maintains** this codebase, how decisions are made, review-routing conventions, cadence (release rhythm, planning ritual). Read by review-routing, finishing-a-development-branch, persona overrides. |
 | `repo` | `repo.md` | Engineering wing | What the codebase **is** at the file-tree level: stack one-liner, primary languages, top-level module map, deploy target. Read by analysis skills, blast-radius-analyzer, project-analysis-* skills. |
 
+### Wing-3 slots (GTM and Growth — added 2026-05-13 per [`adr-gtm-context-spine.md`](adr-gtm-context-spine.md))
+
+| Slot | Path under `agents/context-spine/` | Owner | Typical content |
+|---|---|---|---|
+| `channel-stage` | `channel-stage.md` | GTM / Marketing wing | Which channels the GTM motion uses (awareness · consideration · decision · retention · expansion), per-channel maturity, channel-cost band. Read by `positioning-strategy`, `messaging-architecture`, `gtm-launch`, `editorial-calendar`. |
+| `funnel-stage` | `funnel-stage.md` | Growth / RevOps wing | Funnel topology (top / mid / bottom / activation / retention), per-stage definition, exit-criteria for each. Read by `pipeline-strategy`, `funnel-analysis`, `activation-design`, `onboarding-design`. |
+| `customer-segment` | `customer-segment.md` | Sales / CS wing | ICP, persona-by-segment, ARR-band-by-segment. Read by `ICP`, `pipeline-strategy`, `MEDDIC`, `retention-loops`. |
+
+### Wing-4 slots (Money / Strategy / Ops — added 2026-05-13 per [`adr-wing4-context-spine.md`](adr-wing4-context-spine.md))
+
+| Slot | Path under `agents/context-spine/` | Owner | Typical content |
+|---|---|---|---|
+| `fiscal-period` | `fiscal-period.md` | Finance wing | Reporting cadence (monthly · quarterly · annual · multi-year-plan), fiscal-year start, close-window timing. Read by `unit-economics`, `forecasting`, `runway-cognition`, `scenario-modeling`. |
+| `org-stage` | `org-stage.md` | Strategy / People wing | Stage label (seed · series-A · series-B · growth · public), funding posture, headcount band, governance posture. Read by `build-buy-partner`, `vision-articulation`, `org-design`, `comp-banding`, `hiring-loop-design`. |
+| `regulatory-regime` | `regulatory-regime.md` | Strategy wing (legal-absorbed) | Active regimes (none · GDPR · HIPAA · SOC2 · PCI · CCPA), data-residency posture, breach-notification timer. Read by `contracts-cognition`, `privacy-review`, `data-handling-judgment`. |
+
 Slots are markdown files. Each is **≤ 200 lines**; longer means the
 slot is doing two jobs and the author should split or trim. Empty /
 missing slot is allowed — the citing skill MUST handle absence
@@ -64,9 +83,10 @@ Rules:
 
 - The key is **optional**. Senior skills MAY ship without it; the
   default (`[]`) means the skill does not read the spine.
-- Values are restricted to the literal slot names: `product`, `team`,
-  `repo`. Unknown values fail `task lint-skills` with
-  `unknown_context_spine_slot`.
+- Values are restricted to the slot names in § 2: cross-wing
+  (`product`, `team`, `repo`) plus wing-scoped extensions
+  (`channel-stage`, `funnel-stage`, `customer-segment`). Unknown
+  values fail `task lint-skills` with `unknown_context_spine_slot`.
 - Reads MUST be opt-in and explicit. A skill body that says *"reads
   `agents/context-spine/product.md` if present"* without declaring
   the slot in frontmatter is **incorrect** — it bypasses the lint
@@ -91,8 +111,13 @@ file does not break the skill).
 
 ## § 5 — Slot-add policy
 
-Adding a fourth slot is **structurally allowed but procedurally
-expensive**. Two preconditions:
+Two tracks: **cross-wing** (locked at 3, citations-first) and
+**wing-scoped** (per-wing ADR, citations prospective).
+
+### Cross-wing track — citations-first
+
+Adding a fourth **cross-wing** slot (one every wing might read) is
+**structurally allowed but procedurally expensive**. Two preconditions:
 
 1. **Citation evidence.** ≥ 2 shipped senior skills declare the new
    slot in their frontmatter and cite it in the body, with PRs
@@ -103,21 +128,42 @@ expensive**. Two preconditions:
    the migration plan for the existing senior catalog (do they
    declare the new slot, do they ignore it, do they get retrofitted).
 
+### Wing-scoped track — per-wing ADR, prospective citations
+
+A wing may add **its own slots** for cognition specific to that wing
+(e.g. Wing-3 `channel-stage`, `funnel-stage`, `customer-segment`).
+Preconditions:
+
+1. **Per-wing ADR.** One ADR under `docs/contracts/` named
+   `adr-<wing>-context-spine.md` names the slots, the cognition gap,
+   the citing-skill chain in the same iteration, and the off-wing
+   migration plan (off-wing skills do **not** retrofit).
+2. **Prospective citations.** The ADR-naming iteration must ship
+   ≥ 2 skills citing each new slot before the iteration closes.
+   Drafts and roadmap items inside the same iteration **do** count
+   for prospective gating; cross-iteration citations do not.
+
+Existing wing-3 reference: [`adr-gtm-context-spine.md`](adr-gtm-context-spine.md).
+
+### Schema and changelog rules — both tracks
+
 The ADR ships with the schema bump (`scripts/schemas/skill.schema.json`
 extends the `context_spine` enum) and a CHANGELOG entry under
 `### Breaking` if the new enum value tightens an existing skill's
 declaration.
 
-This policy mitigates the slot-sprawl failure mode: "tri-slot locked
-at 3 + ADR-gated growth" is the brake. The ADR is the single growth
-lever; no consumer-side override exists.
+This policy mitigates the slot-sprawl failure mode: "cross-wing
+locked at 3 + wing-scoped via per-wing ADR" is the brake. ADRs are
+the single growth lever; no consumer-side override exists.
 
 ## § 6 — Author checklist
 
 Before shipping a senior skill that opts into the spine:
 
-- [ ] Frontmatter declares `context_spine:` with values from
-      `{product, team, repo}`.
+- [ ] Frontmatter declares `context_spine:` with values from the
+      cross-wing slots (`product`, `team`, `repo`) and/or wing-scoped
+      slots authorized via per-wing ADR (e.g. Wing-3:
+      `channel-stage`, `funnel-stage`, `customer-segment`).
 - [ ] Skill body cites `agents/context-spine/<slot>.md` near the top
       (one link per declared slot).
 - [ ] Procedure handles missing-slot gracefully — falls back to the

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

@@ -101,10 +101,10 @@ mirrors `lint_skills` (`file:line:reason`).
 
 Three shipped chains across the suite illustrate the contract:
 
-### W3 launch chain — `positioning` → `messaging-architecture` → `gtm-launch`
+### W3 launch chain — `positioning-strategy` → `messaging-architecture` → `gtm-launch`
 
-- `positioning` (H1) owns category framing.
-- `messaging-architecture` (H2) **composes** `positioning` — primary
+- `positioning-strategy` (H1) owns category framing.
+- `messaging-architecture` (H2) **composes** `positioning-strategy` — primary
   message + supporting proofs derive from H1's point-of-view output.
 - `gtm-launch` (H3) **composes** `messaging-architecture` plus
   `release-comms` (unified-senior-roles Block L) — launch sequencing

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/persona-schema.md

@@ -22,6 +22,7 @@ tiers, a 5-section spine for Core, and a 7-section spine for Specialist
 | `role` | string | yes | human-readable role name |
 | `description` | string | yes | one sentence, ≤ 160 chars |
 | `tier` | enum | yes | `core` \| `specialist` |
+| `wing` | int | optional | `1`\|`2`\|`3`\|`4` — cognition cluster per [`package-self-orientation § The four wings`](package-self-orientation.md#the-four-wings); raises the specialist size cap for denser wings |
 | `mode` | string | optional | advisory link to a role-contract workflow mode |
 | `version` | string | yes | semver; bump on breaking changes |
 | `source` | enum | yes | `package` \| `project` |
@@ -77,13 +78,28 @@ beyond the global line cap).
 
 ## § 4 — Size budgets
 
+Base caps by tier:
+
 | Tier | Section count | Line cap | Rationale |
 |---|---|---|---|
 | `core` | 5 | ≤ 120 | always-loaded, stay lean |
 | `specialist` | 7 | ≤ 100 | opt-in, denser per section |
 
-The line cap is enforced by `lint-skills` against the full file
-including frontmatter and trailing blank line.
+Wing-scoped overrides for the `specialist` tier (Wings 3 and 4 carry
+denser cognition than Wings 1 and 2 — funnel × channel × lifecycle for
+GTM, finance × org × strategy for Money/Ops — so the seven-section
+spine needs more room to land without amputating Workflows):
+
+| Tier | Wing | Line cap |
+|---|---|---|
+| `specialist` | 1 (Engineering) | ≤ 100 |
+| `specialist` | 2 (Product + Foundation) | ≤ 100 |
+| `specialist` | 3 (GTM + Growth) | ≤ 140 |
+| `specialist` | 4 (Money + Strategy + Ops) | ≤ 140 |
+
+Personas without a `wing:` field fall back to the tier baseline. The
+line cap is enforced by `lint-skills` against the full file including
+frontmatter and trailing blank line.
 
 ## § 5 — Schema enforcement
 
@@ -91,8 +107,9 @@ The linter (A2 work) enforces:
 
 - frontmatter shape (table in § 1)
 - tier enum
+- wing enum (when present)
 - required sections per tier (§ 3)
-- size budget per tier (§ 4)
+- size budget per tier — wing override applied when `wing:` is set (§ 4)
 - ≥ 3 bullets in `Unique Questions`
 - `id` matches filename stem
 - description ≤ 160 chars