@event4u/agent-config 2.8.0 → 2.9.0

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

@@ -41,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`.
 
@@ -73,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

@@ -52,6 +52,14 @@ locks the cross-wing slot count at 3. Per-wing extensions follow § 5.
 | `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

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/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/package.json

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