@event4u/agent-config 2.8.0 → 2.10.0

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.

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