@event4u/agent-config 2.8.0 → 2.9.0

package/CHANGELOG.md

@@ -18,6 +18,78 @@ Entry-shape contract: [`docs/contracts/CHANGELOG-conventions.md`](docs/contracts
 
 Four roadmaps land in this release.
 
+**Tier-0 trim (`road-to-surface-discipline` Phase 1)** — six CLI
+commands moved from Tier-0 to Tier-1 in `./agent-config --help` to
+collapse the daily-driver surface down to the seven commands a new
+contributor actually needs in their first session. Commands stay
+fully invokable by full name — only the default `--help` view
+changed. Source of truth: `docs/contracts/command-surface-tiers.md`.
+
+Pre/post diff of `./agent-config --help` Tier-0 block:
+
+| Command | Pre | Post | Rationale |
+|---|:-:|:-:|---|
+| `init` | Tier-0 | Tier-0 | daily-driver entrypoint |
+| `sync` | Tier-0 | Tier-0 | daily-driver entrypoint |
+| `validate` | Tier-0 | Tier-0 | daily-driver entrypoint |
+| `work` | Tier-0 | Tier-0 | daily-driver entrypoint |
+| `implement-ticket` | Tier-0 | Tier-0 | daily-driver entrypoint |
+| `help` | Tier-0 | Tier-0 | help meta-command |
+| `--version` | Tier-0 | Tier-0 | help meta-command |
+| `first-run` | Tier-0 | **Tier-1** | one-time setup; not in daily loop |
+| `keys:install-anthropic` | Tier-0 | **Tier-1** | one-time credential setup |
+| `keys:install-openai` | Tier-0 | **Tier-1** | one-time credential setup |
+| `council:estimate` | Tier-0 | **Tier-1** | on-demand review tool |
+| `council:run` | Tier-0 | **Tier-1** | on-demand review tool |
+| `council:render` | Tier-0 | **Tier-1** | on-demand review tool |
+
+Net surface delta: **0 new commands, 0 removed commands.** Only the
+`--help` surfacing changed. Run `./agent-config --help --tier=1` for
+the full power-user view (15 commands) or `--tier=all` for
+maintenance / hooks / MCP / telemetry (26 additional commands).
+
+**Diagnostic Hub (`road-to-surface-discipline` Phase 2)** — the
+existing `./agent-config doctor` is repositioned as the single
+entrypoint for health checks. New `CHECK_IDS` registry plus
+`doctor --check <id>` filter; `--list-checks` enumerates every
+runner; failing checks print the literal command line that
+reproduces the failure. Surface delta: **0 new commands** — only
+flags and registry plumbing.
+
+**MCP beta gating (`road-to-surface-discipline` Phase 3)** — MCP
+promotion criteria pinned in
+[`docs/contracts/mcp-beta-criteria.md`](docs/contracts/mcp-beta-criteria.md)
+with a four-gate contract (offline-readiness, scope, drift, runtime).
+`doctor --check mcp-beta-readiness` enforces the gates; failing tests
+under `tests/test_mcp_beta_gates.py` codify the promotion bar.
+Cloud-scope behaviour cross-referenced from
+[`docs/contracts/mcp-cloud-scope.md`](docs/contracts/mcp-cloud-scope.md).
+
+**Architecture refresh (`road-to-surface-discipline` Phase 4)** —
+[`docs/architecture.md`](docs/architecture.md) and
+[`docs/mcp-server.md`](docs/mcp-server.md) re-anchor the 6-layer
+system model (consumer → tools → installer → package → kernel →
+runtime). `AGENTS.md` re-trimmed to honour the Thin-Root contract
+(< 3,000 chars). No code churn — docs only.
+
+**Tier-usage telemetry (`road-to-surface-discipline` Phase 5)** —
+empirical retiering signal added behind a default-off opt-in. New
+`telemetry.tier_usage` namespace in `.agent-settings.yml`; signal
+contract pinned in
+[`docs/contracts/command-clusters.md`](docs/contracts/command-clusters.md)
+§ tier-usage (whitelist: `ts_bucket`, `command`, `tier`, `outcome`,
+`user_hash`; hourly time buckets; 16-char salted user hash; no paths,
+no argv). Retiering thresholds (≥ 20 invocations and ≥ 3 distinct
+users over 30 days) live in the same contract. A new
+`tier_usage_report.py` template script aggregates the local log into
+a frequency table and refuses to render rows that violate the
+privacy floor. The existing `doctor` gains a `tier-usage-readiness`
+check (warn when disabled or empty; fail when every record is
+poisoned; ok when ≥ 1 record passes the floor). Surface delta: **0
+new commands, 0 new skills, 0 new personas** — telemetry rides on
+the existing dispatcher and the existing `doctor` entrypoint.
+
+
 **Package consolidation** — the standalone wrapper package
 `@event4u/create-agent-config` is retired. `npx @event4u/agent-config init`
 is now the canonical one-shot entrypoint; the bundle package gains an
@@ -357,6 +429,40 @@ 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.9.0](https://github.com/event4u-app/agent-config/compare/2.8.0...2.9.0) (2026-05-13)
+
+### Features
+
+* tier-usage telemetry settings + report template ([22172f2](https://github.com/event4u-app/agent-config/commit/22172f2a59b530034633ff72226506006c5fd81b))
+* mcp beta-readiness criteria with pending gate tests ([3653788](https://github.com/event4u-app/agent-config/commit/36537880e03546e9baf424b2fdd70aa69d41eb03))
+* expand doctor diagnostic hub to 10 checks ([372c193](https://github.com/event4u-app/agent-config/commit/372c19362f8037c76f919a2d918780ae5ec9cb40))
+* **roadmap:** add road-to-surface-discipline (council-reviewed) ([d9da987](https://github.com/event4u-app/agent-config/commit/d9da9870989ccdb7594cd693e9b18608b957ab79))
+* **linter:** wing-4 cognition-boundary checks + spine slot vocab ([c4d9a4b](https://github.com/event4u-app/agent-config/commit/c4d9a4ba8e5c7184b9be0a58d4d8b220a60cab7c))
+
+### Bug Fixes
+
+* **skills:** clear missing_inspect_step + bare_noun warnings ([0c88c6e](https://github.com/event4u-app/agent-config/commit/0c88c6ee45873e47fd8c7d356ec82b28b63b12c5))
+* **docs:** drop roadmap-file pointers from wing-4 ADRs and handoff ([ccd7624](https://github.com/event4u-app/agent-config/commit/ccd7624127094d0a01eda0901fa41c31319f7bc5))
+* **template:** bump agent_config_version pin to 2.8.0 ([f21e916](https://github.com/event4u-app/agent-config/commit/f21e916c6bb793fa6efe7d264a1e069e11ab4c62))
+* **skills:** spine slot citations + finance-partner polish ([9072783](https://github.com/event4u-app/agent-config/commit/90727831b223bd970d8425d158940bf3e3bc104f))
+
+### Documentation
+
+* archive surface-discipline roadmap + 2.8.0 changelog ([551e306](https://github.com/event4u-app/agent-config/commit/551e306e43fa82fffda9178bdaa690b19d8bec4e))
+* 6-layer architecture refresh + thin-root sync ([91d25a8](https://github.com/event4u-app/agent-config/commit/91d25a80b37fb1c1782c2d5f00f23925ba6ec1b3))
+* **roadmap:** complete road-to-money-strategy-ops phase 1 ([83cf9fe](https://github.com/event4u-app/agent-config/commit/83cf9fe99c034b71e146099eddc9ce5b3137f434))
+* **contracts:** register wing-4 spine slots + marketplace entries ([75b829d](https://github.com/event4u-app/agent-config/commit/75b829d162bc18ab3dc2dda6614d15a087a4f32a))
+
+### Refactoring
+
+* trim tier-0 surface from 13 to 7 commands ([a9eafd1](https://github.com/event4u-app/agent-config/commit/a9eafd1c5226c10209e3dee2b972f38d9c0f3dd9))
+
+### Chores
+
+* **generated:** regenerate derived outputs for wing-4 additions ([54f3779](https://github.com/event4u-app/agent-config/commit/54f3779a6d2161ed06bfb327c3e416ec107b4016))
+
+Tests: 3603 (+26 since 2.8.0)
+
 ## [2.8.0](https://github.com/event4u-app/agent-config/compare/2.7.0...2.8.0) (2026-05-13)
 
 ### Features

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>189 Skills</strong> · <strong>61 Rules</strong> · <strong>106 Commands</strong> · <strong>71 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>206 Skills</strong> · <strong>61 Rules</strong> · <strong>106 Commands</strong> · <strong>72 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -244,7 +244,7 @@ Install in the same project (dev-only):
 npm install --save-dev @event4u/agent-memory
 ```
 
-→ [Memory contract & retrieval API](docs/contracts/agent-memory-contract.md) (beta) · [Built-in MCP server](docs/mcp-server.md) (experimental — local stdio access from Claude Desktop / Cursor / Zed / Continue, install with `task mcp:setup`)
+→ [Memory contract & retrieval API](docs/contracts/agent-memory-contract.md) (beta) · [Built-in MCP server](docs/mcp-server.md) (experimental — local stdio access from Claude Desktop / Cursor / Zed / Continue, install with `task mcp:setup`; promotion to beta gated on [`mcp-beta-criteria.md`](docs/contracts/mcp-beta-criteria.md))
 
 ---
 
@@ -510,7 +510,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 + 189 skills + 106 native commands); Augment Code gets the
+> package (rules + 206 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

package/docs/architecture.md

@@ -4,22 +4,44 @@
 
 ## System overview
 
+Six layers, ordered from "how the package reaches a consumer" down to "what a consumer's agent actually executes". Each layer names its canonical contract under [`docs/contracts/`](contracts/) — the overview is a router, not a re-statement.
+
 ```
-Rules               → Behavior enforcement (always active)              ← stable
-Skills              → Execution logic (on-demand expertise)             ← stable
-Runtime Dispatcher  → Single-skill shell execution (pilot skills)       ← stable (mechanism)
-Work Engine         → Multi-step orchestration for /work + /implement   ← beta
-Tool Adapters       → External integrations (GitHub, Jira)              ← experimental
+Distribution         → npx-only runtime · install.sh · lockfile pin        ← stable
+Governance           → Kernel rules · tier-1/2 routing · command clusters  ← stable
+Router-Kernel        → router.json · always-loaded Iron Laws · char caps   ← stable
+Projection           → Compression · augment / multi-tool / cloud bundles  ← stable
+Execution Contracts  → Skills · commands · work-engine · roadmap engine    ← stable / beta
+MCP Lite/Full        → Hosted read-only (Lite) · local stdio (Full)        ← experimental
 ```
 
+| Layer | Canonical contract | Tier |
+|---|---|---|
+| **Distribution** | [`installed-tools-lockfile.md`](contracts/installed-tools-lockfile.md) + the "Distribution model" subsection below | stable |
+| **Governance** | [`command-clusters.md`](contracts/command-clusters.md) + [`command-surface-tiers.md`](contracts/command-surface-tiers.md) | stable |
+| **Router-Kernel** | [`kernel-membership.md`](contracts/kernel-membership.md) + [`rule-router.md`](contracts/rule-router.md) | stable |
+| **Projection** | [`architecture/compression.md`](architecture/compression.md), [`augment-projection.md`](architecture/augment-projection.md), [`multi-tool-projection.md`](architecture/multi-tool-projection.md), [`claude-bundle.md`](architecture/claude-bundle.md) | stable |
+| **Execution Contracts** | [`implement-ticket-flow.md`](contracts/implement-ticket-flow.md), [`orchestration-dsl-v1.md`](contracts/orchestration-dsl-v1.md), [`adr-product-ui-track.md`](contracts/adr-product-ui-track.md) | stable (skills · commands) / beta (work-engine · roadmap engine) |
+| **MCP Lite/Full** | [`mcp-phase-1-scope.md`](contracts/mcp-phase-1-scope.md), [`mcp-cloud-scope.md`](contracts/mcp-cloud-scope.md), [`mcp-beta-criteria.md`](contracts/mcp-beta-criteria.md) | experimental — promotion to beta gated on `mcp-beta-criteria.md` (six artefact gates, monitored by `agent-config doctor --check mcp-beta-readiness`) |
+
 Stability tiers follow [`docs/contracts/STABILITY.md`](contracts/STABILITY.md):
 
 - **stable** = shipped, documented, exercised by the default (`minimal`) profile or by CI on every PR; SemVer-major for breaks.
 - **beta** = shipped and load-bearing for one or more flows, but the surface is expected to evolve; minor-version breaks allowed under a `### Breaking` CHANGELOG note.
 - **experimental** = scaffold or pilot status; breaks allowed in any release.
 
+### What changed since 2.2.2
+
+Four load-bearing additions reshaped the top of the model between 2.2.2 and the current release. They are listed here so the diagram above reads as the *current* package, not a historical accumulation:
+
+1. **Router-Kernel** — the always-loaded Iron Laws collapsed into a 9-rule kernel with explicit per-rule character budgets enforced by `task lint-rule-budget`; everything else routes via tier-1/2 (`.agent-src/router.json`). Contract: [`kernel-membership.md`](contracts/kernel-membership.md) + [`rule-router.md`](contracts/rule-router.md).
+2. **MCP Lite/Full** — replaces the old "Tool Adapters" layer at the top level. Lite is the hosted read-only surface (Claude.ai, Cloud agents); Full is the local stdio server consumers self-host. Promotion to beta is gated on six falsifiable artefacts in [`mcp-beta-criteria.md`](contracts/mcp-beta-criteria.md); the old GitHub / Jira adapters remain as an internal detail of the Execution Contracts layer (see Tool Adapters subsection below).
+3. **npx distribution** — Composer and `npm install` paths retired in favour of `npx @event4u/agent-config`, with the lockfile-equivalent role played by `agent_config_version` in `.agent-settings.yml`. Full rationale in the "Distribution model" subsection below.
+4. **Command tiering** — `/`-commands now declare a `tier:` (0 / 1 / 2 / 3) that maps to invocation frequency and surface budget; tier-0 is the trimmed Tier-0 set surfaced in `agent-config --help` after the 2.7.x surface-discipline pass. Contract: [`command-surface-tiers.md`](contracts/command-surface-tiers.md) + [`command-clusters.md`](contracts/command-clusters.md).
+
 > The previous "observability, feedback, lifecycle" layers were removed in
-> 1.5 — they were scaffolds without production consumers.
+> 1.5 — they were scaffolds without production consumers. The "Tool
+> Adapters" top-level layer was demoted in 2.7 — see point 2 above.
 
 ## Content pipelines
 
@@ -119,16 +141,18 @@ note, package-internal path-swap, description budget, and the
 
 | Layer | Count | Purpose |
 |---|---|---|
-| **Skills** | 189 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
+| **Skills** | 206 | 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** | 71 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
+| **Guidelines** | 72 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |
 
 ---
 
-## Layers
+## Execution-layer detail
+
+> The six layers in the System overview are the top-level model. This section provides depth on the **Governance**, **Router-Kernel**, and **Execution Contracts** layers — the three a host agent interacts with on every turn. Distribution and Projection live in their own sub-pages ([`architecture/`](architecture/) and the "Distribution model" subsection above); MCP Lite/Full lives in [`docs/mcp-server.md`](mcp-server.md).
 
 ### 1. Governance Layer
 
@@ -137,7 +161,7 @@ note, package-internal path-swap, description budget, and the
 - **Guidelines** → reference-only documentation
 - **Commands** → workflow orchestration
 
-Ensures: no guessing, analysis before action, real verification, consistent outputs.
+Ensures: no guessing, analysis before action, real verification, consistent outputs. Canonical contracts: [`kernel-membership.md`](contracts/kernel-membership.md), [`rule-router.md`](contracts/rule-router.md), [`command-clusters.md`](contracts/command-clusters.md), [`command-surface-tiers.md`](contracts/command-surface-tiers.md).
 
 ### 2. Runtime Dispatcher — stable mechanism, pilot coverage
 
@@ -222,7 +246,9 @@ The Work Engine **uses** the Runtime Dispatcher when a phase needs
 to execute a single skill (e.g. lint, refs check), but the two are
 independent components with separate stability tiers.
 
-### 4. Tool Adapters — experimental
+### 4. Tool Adapters — experimental (internal detail; superseded at the top level by MCP)
+
+> **Position in the new model.** Tool Adapters no longer occupy a top-level layer — that slot is now **MCP Lite/Full**. The adapter classes still ship as the internal mechanism the Work Engine uses for inline GitHub/Jira reads, but external integration is meant to land via MCP going forward. See [`mcp-phase-1-scope.md`](contracts/mcp-phase-1-scope.md), [`mcp-cloud-scope.md`](contracts/mcp-cloud-scope.md), and [`mcp-beta-criteria.md`](contracts/mcp-beta-criteria.md) for the surface that replaces this layer at the top level.
 
 > **Status: scaffold + read-only GitHub calls.** With a `GITHUB_TOKEN` the
 > GitHub adapter performs real read calls; without one it returns scaffold

package/docs/catalog.md

@@ -1,13 +1,13 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **424 public artefacts** shipped by
+Consumer-facing catalog of all **442 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
 > **Regenerate:** `python3 scripts/generate_index.py`
 > Auto-generated — do not edit manually.
 
-## Skills (189)
+## Skills (206)
 
 | kind | name | extra | description |
 |---|---|---|---|
@@ -31,23 +31,28 @@ are excluded.
 | skill | [`blade-ui`](../.agent-src/skills/blade-ui/SKILL.md) |  | Use when the project's frontend stack is Blade — dispatched by `directives/ui/{apply,review,polish}.py`. Covers views, components, partials, layouts, and view logic. |
 | skill | [`blast-radius-analyzer`](../.agent-src/skills/blast-radius-analyzer/SKILL.md) |  | Use BEFORE editing shared code — enumerates every call site, event consumer, queue worker, API client, migration, and test that a planned change will touch, with a file:line citation per dependency. |
 | skill | [`bug-analyzer`](../.agent-src/skills/bug-analyzer/SKILL.md) |  | Use when the user shares a Sentry error, Jira bug ticket, or error description and wants root cause analysis. Also for proactive bug hunting and code audits for hidden bugs. |
+| skill | [`build-buy-partner`](../.agent-src/skills/build-buy-partner/SKILL.md) |  | Use when deciding insource vs outsource vs acquire — integration-cost analysis, dependency-risk, optionality preservation. Triggers on 'should we build', 'buy vs partner'. |
 | skill | [`check-refs`](../.agent-src/skills/check-refs/SKILL.md) |  | Use when verifying cross-references between skills, rules, commands, guidelines, and context documents are not broken after edits, renames, or deletions. |
 | skill | [`churn-prevention`](../.agent-src/skills/churn-prevention/SKILL.md) |  | Use when designing churn defence — health-score signals, churn-cause split (involuntary / value / relationship / fit), early-warning loop. Triggers on 'why are accounts leaving'. |
 | skill | [`code-refactoring`](../.agent-src/skills/code-refactoring/SKILL.md) |  | Use when the user says "refactor this", "rename class", or "move method". Safely refactors PHP code — finds all callers, updates downstream dependencies, and verifies with quality tools. |
 | skill | [`code-review`](../.agent-src/skills/code-review/SKILL.md) |  | Use when the user says "review this", "check my code", or wants feedback on changes. Reviews for correctness, quality, security, and coding standards. |
 | skill | [`command-routing`](../.agent-src/skills/command-routing/SKILL.md) |  | Use when the user invokes a slash command like /create-pr, /commit, /fix-ci, or pastes command file content — routes to the right command with context inference and GitHub API patterns. |
 | skill | [`command-writing`](../.agent-src/skills/command-writing/SKILL.md) |  | Use when creating or editing a slash command in .agent-src.uncompressed/commands/ — frontmatter, numbered steps, safety gates — even when the user just says 'add a /command for X'. |
+| skill | [`comp-banding`](../.agent-src/skills/comp-banding/SKILL.md) |  | Use when designing levels, comp bands, equity-vs-cash, geo adjustments, or raise vs promotion vs market correction. Triggers on 'set our comp bands', 'is this raise market'. |
+| skill | [`competitive-moat-analysis`](../.agent-src/skills/competitive-moat-analysis/SKILL.md) |  | Use when mapping competitors, naming defensibility, and finding white-space — moat reasoning, where-to-play, where-not-to-play. Triggers on 'who are we competing with', 'what's our moat'. |
 | skill | [`competitive-positioning`](../.agent-src/skills/competitive-positioning/SKILL.md) |  | Use when comparing this package to a peer / competitor — ours-vs-theirs verdict table, axis selection, adoption queue. Triggers on 'how do we compare to X', 'should we adopt their pattern'. |
 | skill | [`composer-packages`](../.agent-src/skills/composer-packages/SKILL.md) |  | Use when building or maintaining a Composer library — versioning, Laravel integration, autoloading, publishing to private registries — even when the user says 'release a new version'. |
 | skill | [`content-funnel-design`](../.agent-src/skills/content-funnel-design/SKILL.md) |  | Use when mapping funnel-stage to content shape — conversion-pathway, content-as-system, leverage-point selection. Triggers on 'design our content funnel', 'why does mid-funnel leak'. |
 | skill | [`context-authoring`](../.agent-src/skills/context-authoring/SKILL.md) |  | Use when filling in knowledge-layer context files — auth-model, tenant-boundaries, data-sensitivity, deployment-order, observability — interactive walkthrough that turns templates into reviewer fuel. |
 | skill | [`context-document`](../.agent-src/skills/context-document/SKILL.md) |  | Use when the user says "create context", "document this area", or wants a structured snapshot of a codebase area for agent orientation. |
+| skill | [`contracts-cognition`](../.agent-src/skills/contracts-cognition/SKILL.md) |  | Use when reading a contract for risk and constraint — clause shape, redline priority, what the contract actually binds. Triggers on 'review this contract', 'what does this MSA constrain'. |
 | skill | [`conventional-commits-writing`](../.agent-src/skills/conventional-commits-writing/SKILL.md) |  | Use when writing commit messages or squash-merge titles — `feat:`, `fix:`, `chore:`, scopes, breaking changes — even when the user just says 'commit this' without naming Conventional Commits. |
 | skill | [`copilot-agents-optimization`](../.agent-src/skills/copilot-agents-optimization/SKILL.md) |  | Use when optimizing AGENTS.md or copilot-instructions.md — deduplicates against .augment/ content, enforces line budgets, and focuses each file on its audience. |
 | skill | [`copilot-config`](../.agent-src/skills/copilot-config/SKILL.md) |  | Use when configuring GitHub Copilot — copilot-instructions.md, PR review patterns, output optimization — even when the user just says 'tune Copilot' or 'why is Copilot commenting on X'. |
 | skill | [`customer-research`](../.agent-src/skills/customer-research/SKILL.md) |  | Use when shaping a discovery slice — JTBD-framed interview guide, switch-event focus, verbatim quotes not summaries. Triggers on 'talk to users', 'why did they cancel', 'before we build X'. |
 | skill | [`dashboard-design`](../.agent-src/skills/dashboard-design/SKILL.md) |  | Use when designing monitoring dashboards — visualization selection, layout principles, observability strategies (RED/USE/Golden Signals), and data storytelling. |
 | skill | [`data-flow-mapper`](../.agent-src/skills/data-flow-mapper/SKILL.md) |  | Use BEFORE editing code that touches user data — traces the value from entry → validation → transformation → storage → egress, every hop cited with file:line. |
+| skill | [`data-handling-judgment`](../.agent-src/skills/data-handling-judgment/SKILL.md) |  | Use when classifying data, setting retention, judging cross-border transfer, or shaping DSR workflow. Triggers on 'how long do we keep this', 'can this data go to the US'. |
 | skill | [`database`](../.agent-src/skills/database/SKILL.md) |  | Use when working with database architecture, MariaDB/MySQL tuning, indexing strategies, slow queries, or multi-connection patterns — even when the user just says 'this query is slow'. |
 | skill | [`dcf-modeling`](../.agent-src/skills/dcf-modeling/SKILL.md) |  | Wing-4 valuation cognition for a CFO / finance-partner. Use when a deal, internal investment, or board ask names DCF, intrinsic value, WACC, terminal value, or 'what's it worth on a 5-year hold'. |
 | skill | [`deal-qualification-meddic`](../.agent-src/skills/deal-qualification-meddic/SKILL.md) |  | Use when qualifying or disqualifying a single deal — MEDDIC slots with evidence, inversion test, disqualification heuristic. Triggers on 'is this deal real', 'should we walk away'. |
@@ -74,6 +79,7 @@ are excluded.
 | skill | [`finishing-a-development-branch`](../.agent-src/skills/finishing-a-development-branch/SKILL.md) |  | Use when the feature is implementation-complete and the next step is 'ship it' — verifies, cleans up, and routes to merge/PR/park/discard — even when the user just says 'I'm done, what now?'. |
 | skill | [`flux`](../.agent-src/skills/flux/SKILL.md) |  | Use when the project uses `livewire/flux` — dispatched by `directives/ui/{apply,review,polish}.py`. Covers Flux components, slots, variants, and form primitives. |
 | skill | [`forecast-accuracy`](../.agent-src/skills/forecast-accuracy/SKILL.md) |  | Use when constructing the forecast call — commit / best-case / pipeline categorisation, deal-level evidence test, accuracy retro-loop. Triggers on 'build the forecast', 'why does our commit miss'. |
+| skill | [`forecasting`](../.agent-src/skills/forecasting/SKILL.md) |  | Use when constructing the finance-side forecast — top-down vs bottom-up shape, confidence bands, retro-loop. Triggers on 'build the forecast model', 'reconcile top-down with bottom-up'. |
 | skill | [`form-handler`](../.agent-src/skills/form-handler/SKILL.md) |  | Use when designing or reviewing a form — validation timing, error display, submission lifecycle, optimistic UI, dirty/pristine state, idempotency — even on 'why does submit double-fire?'. |
 | skill | [`fundraising-narrative`](../.agent-src/skills/fundraising-narrative/SKILL.md) |  | Use when shaping a capital-raise pitch — why-now / why-us / why-this framing, market-size reasoning, traction-story construction. Triggers on 'tighten the pitch', 'why-now is weak'. |
 | skill | [`funnel-analysis`](../.agent-src/skills/funnel-analysis/SKILL.md) |  | Use when diagnosing where a SaaS or product funnel leaks — visitor → signup → activation → paid → retained — channel-agnostic, conversion-rate-driven. |
@@ -82,6 +88,7 @@ are excluded.
 | skill | [`grafana`](../.agent-src/skills/grafana/SKILL.md) |  | Use when working with Grafana — dashboards, Loki LogQL queries, alerting rules, monitoring panels — even when the user just says 'build me a dashboard' or 'query the logs' without naming Grafana. |
 | skill | [`gtm-launch`](../.agent-src/skills/gtm-launch/SKILL.md) |  | Use when sequencing a launch — alpha / beta / GA waves, audience-by-wave logic, narrative beats per wave, engineering-readiness gates. Triggers on 'plan the launch', 'sequence GA'. |
 | skill | [`guideline-writing`](../.agent-src/skills/guideline-writing/SKILL.md) |  | Use when creating or editing a guideline in docs/guidelines/ — reference material cited by skills, no auto-triggers — even when the user just says 'write up our naming conventions'. |
+| skill | [`hiring-loop-design`](../.agent-src/skills/hiring-loop-design/SKILL.md) |  | Use when shaping an engineering hiring loop — stages, take-home vs live, calibration, bar-raiser, signal-vs-noise audit. Triggers on 'design our interview loop', 'audit our hiring bar'. |
 | skill | [`incident-commander`](../.agent-src/skills/incident-commander/SKILL.md) |  | Use during or right after an incident — frames severity, sets comms cadence, drafts the post-mortem skeleton — even when the user just says 'production is down' or 'wir haben einen Vorfall'. |
 | skill | [`jira-integration`](../.agent-src/skills/jira-integration/SKILL.md) |  | Use when the user says "check Jira", "create ticket", "update issue", or needs JQL queries, ticket transitions, or branch-to-ticket linking. |
 | skill | [`jobs-events`](../.agent-src/skills/jobs-events/SKILL.md) |  | Use when creating Laravel jobs, queued workflows, events, or listeners. Covers clear responsibilities, safe serialization, and retry/failure handling. |
@@ -105,6 +112,7 @@ are excluded.
 | skill | [`livewire`](../.agent-src/skills/livewire/SKILL.md) |  | Use when the project's frontend stack is Livewire — dispatched by `directives/ui/{apply,review,polish}.py`. Covers reactive state, events, lifecycle hooks, and component/view separation. |
 | skill | [`livewire-architect`](../.agent-src/skills/livewire-architect/SKILL.md) |  | Use when shaping a Livewire component before code — full-page vs partial, parent/child split, event flow, state-vs-props boundary, hydration cost — even on 'add this Livewire component'. |
 | skill | [`logging-monitoring`](../.agent-src/skills/logging-monitoring/SKILL.md) |  | Use when working with logging or monitoring — Sentry error tracking, Grafana/Loki log aggregation, structured logging channels, or monitoring helpers. |
+| skill | [`market-entry-analysis`](../.agent-src/skills/market-entry-analysis/SKILL.md) |  | Use when sequencing market entry — geo / segment / vertical, beachhead selection, regulatory-delta. Triggers on 'should we enter market X', 'which segment first'. |
 | skill | [`markitdown`](../.agent-src/skills/markitdown/SKILL.md) |  | Use when converting PDF, DOCX, XLSX, PPTX, EPUB, images, or audio to Markdown for LLM ingestion via the upstream markitdown-mcp server — 'extract this PDF', 'OCR this image', 'transcribe this audio'. |
 | skill | [`mcp`](../.agent-src/skills/mcp/SKILL.md) |  | Use when working with MCP (Model Context Protocol) servers — their tools, capabilities, and best practices for effective agent workflows. |
 | skill | [`mcp-builder`](../.agent-src/skills/mcp-builder/SKILL.md) |  | Use when building an MCP server in Python (FastMCP) or Node/TypeScript (MCP SDK) — agent-centric tool design, input schemas, error handling, and the 10-question evaluation harness. |
@@ -119,8 +127,12 @@ are excluded.
 | skill | [`multi-tenancy`](../.agent-src/skills/multi-tenancy/SKILL.md) |  | Use when working with the multi-tenant architecture — customer DB switching, FQDN routing, tenant isolation, or cross-tenant operations. |
 | skill | [`okr-tree-modeling`](../.agent-src/skills/okr-tree-modeling/SKILL.md) |  | Use when decomposing a company objective into team OKRs, auditing a draft OKR tree, or stress-testing an existing one for measurability and laddering. |
 | skill | [`onboarding-design`](../.agent-src/skills/onboarding-design/SKILL.md) |  | Use when designing customer onboarding — time-to-first-value, milestone design, friction audit, drop-off diagnosis. Triggers on 'fix onboarding', 'why do new accounts churn fast'. |
+| skill | [`onboarding-program`](../.agent-src/skills/onboarding-program/SKILL.md) |  | Use when shaping employee onboarding — time-to-productivity, role-by-role program, mentor pairing, 30/60/90 milestones. Triggers on 'design our onboarding', 'why are new hires ramping slow'. |
+| skill | [`one-on-one-cadence`](../.agent-src/skills/one-on-one-cadence/SKILL.md) |  | Use when designing engineering 1:1s — cadence, agenda mix, growth-vs-blocker-vs-trust shape, cancellation anti-patterns. Triggers on 'fix my 1:1s', 'should I cancel 1:1s this week'. |
 | skill | [`openapi`](../.agent-src/skills/openapi/SKILL.md) |  | Use when documenting APIs — OpenAPI/Swagger, PHP attributes, Redocly validation, versioned specs — even when the user just says 'document this endpoint' without naming OpenAPI. |
+| skill | [`org-design`](../.agent-src/skills/org-design/SKILL.md) |  | Use when shaping team structure — functional vs squad, span-of-control, reorg cost, Conway-aware boundaries. Triggers on 'should we reorg', 'how do we split this team'. |
 | skill | [`override-management`](../.agent-src/skills/override-management/SKILL.md) |  | Creates and manages project-level overrides for shared skills, rules, and commands — extending or replacing originals from .augment/ with project-specific behavior in agents/overrides/. |
+| skill | [`perf-feedback-craft`](../.agent-src/skills/perf-feedback-craft/SKILL.md) |  | Use when shaping feedback — situation-behavior-impact, growth-vs-corrective split, cadence design, ladder-of-inference checks. Triggers on 'how do I give this feedback', 'perf review shape'. |
 | skill | [`performance`](../.agent-src/skills/performance/SKILL.md) |  | Use when optimizing application performance — caching strategies, eager loading, query optimization, Redis patterns, or background job design. |
 | skill | [`performance-analysis`](../.agent-src/skills/performance-analysis/SKILL.md) |  | ONLY when user explicitly requests: performance audit, bottleneck analysis, or N+1 query detection. NOT for regular feature work. |
 | skill | [`persona-writing`](../.agent-src/skills/persona-writing/SKILL.md) |  | Use when creating or editing a persona in .agent-src.uncompressed/personas/ — voice / focus / unique questions / output expectations — even when the user just says 'add a reviewer voice for X'. |
@@ -133,6 +145,7 @@ are excluded.
 | skill | [`playwright-testing`](../.agent-src/skills/playwright-testing/SKILL.md) |  | Use when writing Playwright E2E tests — browser automation, visual regression testing, Page Objects, fixtures, and reliable test patterns. |
 | skill | [`po-discovery`](../.agent-src/skills/po-discovery/SKILL.md) |  | Use when shaping a fuzzy product ask into a refined backlog item — problem framing, user-story rewrite, AC tightening — even if the user just says 'help me write this ticket'. |
 | skill | [`positioning-strategy`](../.agent-src/skills/positioning-strategy/SKILL.md) |  | Use when locking the market frame — category, segment, alternative, point-of-view — before messaging, launch, or pricing rides on it. Triggers on 'who are we for', 'opposable audit'. |
+| skill | [`privacy-review`](../.agent-src/skills/privacy-review/SKILL.md) |  | Use when reviewing data flows for GDPR / CCPA / HIPAA fit — regulatory-regime delta, consent shape, breach-impact triage. Triggers on 'is this GDPR-safe', 'do we need a DPA'. |
 | skill | [`project-analysis-core`](../.agent-src/skills/project-analysis-core/SKILL.md) |  | Use for the universal deep-analysis workflow: project discovery, version resolution, docs loading, architecture mapping, execution flow, and package research. |
 | skill | [`project-analysis-hypothesis-driven`](../.agent-src/skills/project-analysis-hypothesis-driven/SKILL.md) |  | Use when a bug has multiple plausible causes across layers — competing hypotheses, validation loops, evidence-based conclusions — even when the user just says 'why is this happening?'. |
 | skill | [`project-analysis-laravel`](../.agent-src/skills/project-analysis-laravel/SKILL.md) |  | Use for deep Laravel project analysis: boot flow, request lifecycle, container usage, Eloquent/data flow, async systems, and Laravel-specific failure patterns. |
@@ -165,6 +178,8 @@ are excluded.
 | skill | [`roadmap-writing`](../.agent-src/skills/roadmap-writing/SKILL.md) |  | Use when authoring or rewriting a roadmap in agents/roadmaps/ — phase prose, goal sentence, acceptance criteria, council notes — even when the user just says 'write a plan for X' or 'draft a roadmap'. |
 | skill | [`rtk-output-filtering`](../.agent-src/skills/rtk-output-filtering/SKILL.md) |  | Use when running verbose CLI commands — wraps them with rtk (Rust Token Killer) for 60-90% token savings. Covers installation, configuration, and usage patterns. |
 | skill | [`rule-writing`](../.agent-src/skills/rule-writing/SKILL.md) |  | Use when creating or editing a rule in .agent-src.uncompressed/rules/ — trigger wording, always vs auto classification, size budget — even when the user just says 'add a rule for X'. |
+| skill | [`runway-cognition`](../.agent-src/skills/runway-cognition/SKILL.md) |  | Use when reasoning about cash runway — burn shape, fundraise triggers, layoff-vs-cut-vs-grow decisions. Triggers on 'how long do we have', 'should we raise', 'cut or grow'. |
+| skill | [`scenario-modeling`](../.agent-src/skills/scenario-modeling/SKILL.md) |  | Use when constructing base / upside / downside scenarios — three-statement modeling, sensitivity analysis, optionality reasoning. Triggers on 'model the scenarios', 'what if growth halves'. |
 | skill | [`script-writing`](../.agent-src/skills/script-writing/SKILL.md) |  | Use when adding or editing any script under `scripts/` — `--quiet` flag, `_lib/script_output` helpers, silent Taskfile wiring, Iron-Law carve-outs — even when you just say 'add a check script for X'. |
 | skill | [`secrets-management`](../.agent-src/skills/secrets-management/SKILL.md) |  | Use when picking a secrets store, designing rotation, or wiring scanning gates — multi-cloud (Vault, AWS, Azure, GCP), CI, and Kubernetes — decision framework, provider deep-dives externalized. |
 | skill | [`security`](../.agent-src/skills/security/SKILL.md) |  | Use when applying security best practices — authentication, authorization via Policies, CSRF protection, input sanitization, rate limiting, or secure coding. |
@@ -188,15 +203,17 @@ are excluded.
 | skill | [`test-performance`](../.agent-src/skills/test-performance/SKILL.md) |  | Use when optimizing test suite performance — database setup, seeder optimization, parallel testing, CI pipeline efficiency, or RefreshDatabase alternatives. |
 | skill | [`testing-anti-patterns`](../.agent-src/skills/testing-anti-patterns/SKILL.md) |  | Use BEFORE writing or changing tests, adding mocks, or putting test-only methods on production classes — five Iron Laws and gates against mocking-the-mock, production pollution, silent partial mocks. |
 | skill | [`threat-modeling`](../.agent-src/skills/threat-modeling/SKILL.md) |  | Use when adding auth, webhooks, uploads, queues, secrets, tenant boundaries, or public endpoints — produces trust boundaries + abuse cases mapped to files, BEFORE implementation. |
+| skill | [`throughput-vs-morale-tradeoff`](../.agent-src/skills/throughput-vs-morale-tradeoff/SKILL.md) |  | Use when balancing eng-team velocity vs quality vs burnout — on-call load, focus fragmentation, reorg shock. Triggers on 'team is burning out', 'why is velocity dropping'. |
 | skill | [`token-optimizer`](../.agent-src/skills/token-optimizer/SKILL.md) |  | Use BEFORE any verbose CLI run, large file read, doc conversion, or near-context handoff — single decision tree keyed by intent that cites the canonical token-saving asset. Consult before the action. |
 | skill | [`traefik`](../.agent-src/skills/traefik/SKILL.md) |  | Use when setting up Traefik as a local reverse proxy — real domains on 127.0.0.1, trusted HTTPS via mkcert, automatic service discovery, and multi-project routing. |
 | skill | [`ui-component-architect`](../.agent-src/skills/ui-component-architect/SKILL.md) |  | Use when shaping a UI component tree — composition vs inheritance, slot patterns, prop API design, controlled vs uncontrolled, polymorphic — even on 'split this component'. |
-| skill | [`unit-economics-modeling`](../.agent-src/skills/unit-economics-modeling/SKILL.md) |  | Use when modeling CAC, LTV, gross-margin payback, or contribution margin per customer — for SaaS, marketplace, or transactional businesses. |
+| skill | [`unit-economics-modeling`](../.agent-src/skills/unit-economics-modeling/SKILL.md) |  | Use when modeling CAC, LTV, payback, contribution margin, or burn-multiple per customer — SaaS, marketplace, or transactional. Triggers on 'are we unit-economic', 'what is our LTV/CAC'. |
 | skill | [`universal-project-analysis`](../.agent-src/skills/universal-project-analysis/SKILL.md) |  | ONLY when user explicitly requests: full project analysis, deep codebase audit, or comprehensive architecture review. Routes to core and framework-specific analysis skills. |
 | skill | [`upstream-contribute`](../.agent-src/skills/upstream-contribute/SKILL.md) |  | Use when a learning, new skill, rule improvement, or bug fix from a consumer project should be contributed back to the shared agent-config package. |
 | skill | [`using-git-worktrees`](../.agent-src/skills/using-git-worktrees/SKILL.md) |  | Use when starting parallel work in isolation from the current branch — spawn a git worktree with ignore-safety checks and a clean test baseline — even when the user says 'try this on the side'. |
 | skill | [`validate-feature-fit`](../.agent-src/skills/validate-feature-fit/SKILL.md) |  | Validate whether a feature request fits the existing codebase — check for duplicates, contradictions, scope creep, and architectural misfit |
 | skill | [`verify-completion-evidence`](../.agent-src/skills/verify-completion-evidence/SKILL.md) |  | Use when claiming 'done', suggesting a commit, push, or PR — runs the evidence gate so completion claims come from fresh output in this message, not memory or earlier runs. |
+| skill | [`vision-articulation`](../.agent-src/skills/vision-articulation/SKILL.md) |  | Use when articulating internal vision — where we're going / why now / why us, founder-mode anchor, distinct from fundraising pitch. Triggers on 'what's our vision', 'why are we doing this'. |
 | skill | [`voc-extract`](../.agent-src/skills/voc-extract/SKILL.md) |  | Use when extracting Voice-of-Customer themes from existing artefacts — GH issues, PR threads, Sentry patterns. Triggers on 'what are users saying', 'recurring complaints', 'top themes'. |
 | skill | [`voice-and-tone-design`](../.agent-src/skills/voice-and-tone-design/SKILL.md) |  | Use when shaping brand voice — voice attributes, tone-by-context matrix, consistency review. Triggers on 'define our voice', 'why does our copy sound different on every surface'. |
 | skill | [`websocket`](../.agent-src/skills/websocket/SKILL.md) |  | Use when building real-time features — WebSocket broadcasting, live updates, presence channels, connection state — even when the user just says 'push this to the client live'. |
@@ -375,7 +392,7 @@ are excluded.
 | command | [`upstream-contribute`](../.agent-src/commands/upstream-contribute.md) |  | Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package |
 | command | [`work`](../.agent-src/commands/work.md) |  | Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, confidence-band gated, no auto-git. |
 
-## Guidelines (71)
+## Guidelines (72)
 
 | kind | name | category | description |
 |---|---|---|---|
@@ -450,6 +467,7 @@ are excluded.
 | guideline | [`sql`](../docs/guidelines/php/sql.md) | php |  |
 | guideline | [`validations`](../docs/guidelines/php/validations.md) | php |  |
 | guideline | [`websocket`](../docs/guidelines/php/websocket.md) | php |  |
+| guideline | [`wing4-handoff`](../docs/guidelines/wing4-handoff.md) | (root) |  |
 
 ---
 

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

@@ -0,0 +1,89 @@
+---
+stability: beta
+---
+
+# ADR — `forecast-construction-shape`: the O2 ↔ H10 interface
+
+> **Status:** Decided · 2026-05-13
+> **Builds on:** [`cross-wing-handoff.md`](cross-wing-handoff.md) § 5 W4 chain;
+> [`wing4-handoff.md`](../guidelines/wing4-handoff.md) § Chain 4;
+> [`gtm-handoff.md`](../guidelines/gtm-handoff.md) § Chain 2 (H10 side).
+
+## Decision
+
+`forecasting` (O2, Wing-4, finance-partner) and `forecast-accuracy`
+(H10, Wing-3, RevOps) compose through a **typed interface**, not a
+shared implementation. O2 owns the cognition of *how a forecast is
+constructed*; H10 owns the cognition of *which deals belong in
+commit*. The interface is the only contract that crosses the wing.
+
+Interface payload (the `forecast-band.json` artifact):
+
+| Field | Type | Meaning |
+|---|---|---|
+| `construction_shape` | enum `top-down` · `bottom-up` · `hybrid` | Which construction shape the forecast was built from. Top-down anchors against TAM × penetration × motion; bottom-up sums deal-level conviction; hybrid is the explicit two-call reconciliation. |
+| `commit_value` | money | Sum of commit-categorised deals × in-window close-rate, or top-down commit-band lower bound. |
+| `best_case_value` | money | Commit + best-case-tagged, or top-down best-case-band upper bound. |
+| `pipeline_value` | money | Population from which commit / best-case are drawn. Not a forecast category, included for ratio reasoning. |
+| `confidence_band` | `{plus_pct: float, minus_pct: float}` | Historical-deviation-derived band around commit. **MUST** be present; a forecast without a band has no honesty about its prior miss-rate. |
+| `retro_signature` | `{horizon: enum, last_two_actual_vs_predicted: [pct, pct]}` | The accuracy retro this band was calibrated against. Horizon = `quarterly` · `monthly` · `annual`. |
+| `segment_scope` | string list | Customer-segment slots the forecast covers (from spine). Empty list = blended; explicit list = per-segment. |
+| `fiscal_period` | string | Reporting cadence slot from `fiscal-period` spine: `monthly` · `quarterly` · `annual` · `multi-year-plan`. |
+| `construction_inputs` | object | Shape-specific inputs: top-down → `{tam, penetration_band, motion_band}`; bottom-up → `{commit_count, best_case_count, evidence_floor}`; hybrid → both. |
+
+## Why this was a real question
+
+Three options were on the table:
+
+1. **Shared implementation in one wing.** Forecasting lives entirely
+   in Wing-3 (RevOps) or Wing-4 (Finance). Rejected: forecasting is
+   constructed from finance fundamentals and consumed from deal-level
+   evidence — collapsing it into one wing forces the other to
+   re-derive cognition.
+2. **Free-form text handoff.** O2 emits prose; H10 reads prose.
+   Rejected: prose drifts every quarter, the linter cannot catch
+   contract breaks, and the retro loop loses the comparison shape.
+3. **Typed interface, owned by O2.** Accepted: O2 owns the shape so
+   that drift is a producer-side fix. H10 consumes against the
+   contract and never re-derives forecasting cognition.
+
+## Citation-evidence gating
+
+This ADR is the gating artefact. O2 cites the ADR in its frontmatter
+and procedure. H10 cites the ADR in its `Related Skills` carve-out
+and validates its `commit-list.md` against the `forecast-band.json`
+shape. `task lint-handoffs` (Phase 3.2) walks the cross-wing graph
+and rejects a contract break.
+
+## Parallel-development rule
+
+O2 ships an **interface-first stub** (this ADR + a stub procedure
+that emits the typed artifact from a single bottom-up case). The
+stub counts as ≥ 100 % of `O2-interface`. H10 starts after the
+interface lands, parallel to O2 implementation. O2 cannot break the
+contract without an ADR revision and a co-ordinated H10 update.
+
+## Counter-evidence the agent should listen for
+
+Three signals that this ADR is wrong and needs revisiting:
+
+1. **H10 re-derives forecasting cognition.** If `forecast-accuracy`
+   starts shipping top-down vs bottom-up reasoning, the interface
+   leaked and one of the two skills is mis-scoped. Re-cut the
+   boundary.
+2. **A third consumer reads `forecast-band.json`.** A new skill
+   composing the interface means the contract is load-bearing for
+   the broader spine and should graduate from beta to stable.
+3. **The confidence-band is consistently absent.** Forecasts that
+   ship without a band are using the interface as a shape but
+   skipping the calibration; the field should become required-on-
+   parse, not required-on-cognition.
+
+## See also
+
+- [`wing4-handoff.md`](../guidelines/wing4-handoff.md) § Chain 4 —
+  finance → GTM prose around this contract.
+- [`gtm-handoff.md`](../guidelines/gtm-handoff.md) § Chain 2 — H10
+  side prose; identical contract, opposite consumer.
+- [`cross-wing-handoff.md`](cross-wing-handoff.md) § 5 — wing-scoped
+  contract policy this ADR follows.

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.