@event4u/agent-config 2.6.1 → 2.8.0

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

@@ -0,0 +1,145 @@
+---
+stability: beta
+---
+
+
+# Command Surface Tiers
+
+> **Status:** Active. Defines the tiering contract for the two
+> command surfaces this package ships:
+>
+> - **CLI commands** rendered by `./agent-config --help`.
+> - **Slash commands** under `.agent-src.uncompressed/commands/**`.
+>
+> Per Phase 4 of `agents/roadmaps/road-to-distribution-maturity.md`.
+
+## Why tiering
+
+`./agent-config --help` currently prints 45 CLI commands; the slash
+surface ships 106 files (52 root + 54 orchestrator children). A new
+contributor running `--help` reads a wall of operational, hook, and
+maintenance commands before they find `init / sync / validate / work`.
+Tiering separates **the path a new contributor walks** (Tier-0) from
+**power-user workflows** (Tier-1) from **hook / maintenance / internal**
+(Tier-2).
+
+## The three tiers
+
+### Tier-0 — daily-driver
+
+The path a new contributor walks on day one. Visible in
+`./agent-config --help` by default. Visible at the top of any
+`/agents audit` listing.
+
+**Membership criteria — ALL must hold:**
+
+1. **First-week need.** A solo contributor hitting the package for
+   the first time will run this within their first five sessions
+   without being told.
+2. **Stable surface.** The command name + flag set has not changed
+   in the last two minor releases (or is brand-new with a
+   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:*`).
+
+**Canonical Tier-0 members (2026-05-13):**
+
+- CLI: `init`, `sync`, `validate`, `work`, `first-run`,
+  `keys:install-anthropic`, `keys:install-openai`,
+  `council:estimate`, `council:run`, `council:render`,
+  `implement-ticket`, `help`, `--version`.
+- Slash: `/onboard`, `/commit`, `/work`, `/implement-ticket`,
+  `/agent-status`, `/agent-handoff`.
+
+### Tier-1 — power-user
+
+Workflows a contributor reaches for in week two or beyond, or
+release / review / audit paths the maintainer team uses. Visible in
+`./agent-config --help --tier=1` and in `/agents audit`'s expanded
+view. Documented in the same surface as Tier-0.
+
+**Membership criteria — ANY suffices:**
+
+1. **Repeat workflow, not first-week.** Used by every contributor
+   eventually but not on day one (`/create-pr`, `/review-changes`,
+   `/optimize`).
+2. **Maintainer-team gate.** Release-shape commands, audits,
+   migration helpers (`update`, `versions`, `prune`, `doctor`,
+   `export`, `migrate`, `uninstall`).
+3. **Orchestrator dispatch surface.** Top-level slash orchestrators
+   whose children carry the actual work (`/roadmap`, `/feature`,
+   `/fix`, `/judge`, `/memory`, `/optimize`, `/council`).
+
+### Tier-2 — maintenance / internal
+
+Default for new commands. Hidden from `./agent-config --help`
+unless `--tier=all`. Reachable by full name; not advertised.
+
+**Membership criteria — ANY suffices:**
+
+1. **Hook entry point.** `*-hook` commands wired by the platform
+   (`chat-history:hook`, `dispatch:hook`,
+   `roadmap-progress:hook`, `onboarding-gate:hook`,
+   `context-hygiene:hook`, `hooks:install`, `hooks:status`).
+2. **Internal / programmatic.** Called by other scripts or by the
+   work-engine, never typed by a human (`memory:*`,
+   `proposal:check`, `refine-ticket:detect`, `migrate-state`,
+   `telemetry:*`, `mcp:render`, `mcp:check`, `mcp:setup`,
+   `mcp:run`, `roadmap:progress-check`).
+3. **Sub-command of a slash orchestrator** — the orchestrator is
+   Tier-1; the children are Tier-2 because they are invoked via
+   the orchestrator's menu, not by name.
+4. **Anything else.** Default for new commands; promotion is the
+   harder direction.
+
+## Promotion gate (Tier-2 → Tier-1, Tier-1 → Tier-0)
+
+Promotion is **not implicit**. Each promotion requires:
+
+1. A short ADR under `docs/decisions/` citing this contract and
+   the specific criterion satisfied.
+2. The frontmatter `tier:` change in the same commit as the ADR.
+3. CI green (`tests/test_command_surface_tiers.py` + `task ci`).
+
+Demotion is allowed without ADR (Tier-0 → Tier-1, Tier-1 → Tier-2)
+but must update this contract's canonical list.
+
+## Tagging shape
+
+Slash commands carry tier in YAML frontmatter:
+
+```yaml
+---
+name: commit
+tier: 0
+description: Stage and commit all uncommitted changes …
+---
+```
+
+CLI commands carry tier in the `agent-config` heredoc, by section —
+the help text groups commands under `## Tier 0`, `## Tier 1`,
+`## Tier 2 (hidden by default)` headings rendered by
+`./agent-config --help --tier=all`.
+
+## Drift / lint
+
+`scripts/lint_command_tiers.py` enforces:
+
+1. Every file under `.agent-src.uncompressed/commands/**.md` has
+   a `tier:` frontmatter key whose value is `0`, `1`, or `2`.
+2. Every command listed under `## Tier 0` / `## Tier 1` /
+   `## Tier 2` in this contract resolves to a real command file or
+   a real CLI command name.
+3. No command appears in two tier lists in this contract.
+
+Hooked into `task lint-skills` so it runs in CI.
+
+## See also
+
+- `agents/roadmaps/road-to-distribution-maturity.md` — Phase 4.
+- `docs/contracts/command-clusters.md` — orchestrator → child wiring.
+- `docs/contracts/STABILITY.md` — surface-stability commitments.

package/docs/contracts/context-spine.md

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

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

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

package/docs/contracts/mcp-cloud-scope.md

@@ -1,5 +1,6 @@
 ---
 stability: experimental
+mcp_scope: lite
 ---
 
 # MCP Server — Cloud Scope (A0-cloud Hard Contract)
@@ -26,6 +27,88 @@ not a sub-process), and (2) no HMAC for MVP-1 (content is OSS and
 read-only; the appendix pattern's `verifyRequest` is deferred to MVP-2
 alongside auth).
 
+## MCP scope: Lite vs Full
+
+The package ships **two MCP surfaces** governed by named scopes. Every
+MCP-related doc, ADR, and code path carries `mcp_scope: lite|full|deferred`
+in its frontmatter (Phase 1 Step 6 of
+`agents/roadmaps/road-to-distribution-maturity.md`) so the boundary is
+machine-checkable, not prose-only.
+
+### `mcp_scope: lite` — hosted, read-only knowledge surfaces
+
+- **What it serves:** the governance content as MCP `prompts` and
+  `resources` — skills (`.agent-src/skills/<name>/SKILL.md`), commands
+  (`.agent-src/commands/**/*.md`), rules (`.agent-src/rules/*.md`),
+  guidelines (`docs/guidelines/`), and the docs index. Plus a small
+  set of **read-only tools** (`memory_lookup`, `chat_history_read`,
+  `list_*`, `read_resource_body`) that touch the content blob only.
+- **What it never does:** execute Python scripts, shell out, spawn
+  runtimes, touch consumer FS, write to R2, mutate consumer state,
+  call upstream LLM APIs, or read `.agent-src.uncompressed/`.
+- **Owner code path:** `workers/mcp/` (TypeScript, Cloudflare Worker).
+  This contract is the normative spec.
+- **Auth model:** `public` (default) or `bearer-auth` (operator opt-in)
+  per `## Auth surface`. HMAC and CF Access are declared but deferred.
+- **Invariant 8 binding:** **layered, mode-aware ingress protection**
+  (edge cache + Cloudflare DDoS shielding + per-request bearer when
+  set) is the **only** access control. Anything that would require a
+  finer-grained policy — per-tool ACLs, per-tenant scoping, mutation
+  authorization — is **out of `lite` scope by construction**, and
+  per `## A0-cloud invariants § 8` would require a contract amendment,
+  not a Worker code change.
+
+### `mcp_scope: full` — local stdio kernel, MVP-2+ execution
+
+- **What it serves:** the full local kernel — `prompts/list`,
+  `prompts/get`, `resources/list`, `resources/read` **plus**
+  execution-side tools (`lint_skills`, `chat_history_append`, and
+  the MVP-2 deferred tool set). Reads from the live worktree
+  (`.agent-src/` projection), not a release-pinned blob.
+- **What it requires:** a local install per Quickstart (`npx
+  @event4u/agent-config init` or `task mcp:setup`) — Python runtime,
+  the package's ~112 scripts on disk, and a consumer-side
+  `.agent-settings.yml`.
+- **Owner code path:** `scripts/mcp_server/` (Python stdio). Governed
+  by [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md), not this
+  contract — the two surfaces are siblings, not parent / child.
+- **Auth model:** filesystem-trusted (stdio child of the consumer
+  agent). No network surface, so no per-request auth applies.
+- **Invariant 8 binding:** the hosted-surface ingress protection
+  declared in `## A0-cloud invariants § 8` **does not apply** to
+  `mcp_scope: full` — the trust boundary is the local FS, not the
+  Cloudflare edge. Promotion of a `full`-scope tool into the hosted
+  Worker is a **scope migration** (lite ← full), gated on the wake-up
+  triggers in `## MVP-2 wake-up triggers` plus a security review per
+  `## A0-cloud invariants § 1 + § 6`.
+
+### `mcp_scope: deferred` — declared, not yet shipped
+
+- Modes named in this contract (`hmac-deferred`, `cf-access-deferred`)
+  and tools listed as deprecated stubs (`lint_skills`,
+  `chat_history_append` on the hosted Worker) carry `mcp_scope:
+  deferred` until their wake-up triggers fire. README MUST NOT
+  recommend a `deferred` mode or tool — the bidirectional drift
+  test enforces this per `## Auth surface § Bidirectional contract ↔
+  README drift`.
+
+### Boundary properties
+
+- **README citations are normative.** The README MCP section names
+  `mcp_scope: lite` and `mcp_scope: full` as canonical scopes (see
+  [`README.md`](../../README.md) § "Self-hosted MCP on Cloudflare").
+  The bidirectional drift test ensures the names this contract
+  declares match the names the README cites.
+- **No scope inheritance.** A `lite`-scope code path may not assume a
+  `full`-scope capability is available (e.g., the Worker may not
+  assume `lint_skills` is reachable via a fallback to the local
+  server). Each scope is self-contained.
+- **Scope migration is a contract event.** Moving a tool from
+  `full` to `lite` (e.g., restoring `lint_skills` on the hosted
+  Worker in MVP-2+) requires this contract's `## In-scope (MVP-1)` /
+  `## Deprecated tool stub contract` sections to be updated in the
+  same PR that lands the implementation — not a follow-up.
+
 ## In-scope (MVP-1)
 
 - **Transport:** HTTP + SSE (Cloudflare Worker `fetch` handler). The
@@ -74,12 +157,90 @@ alongside auth).
 - **Chat history persistence** — the local kernel writes to
   `agents/.agent-chat-history`; the Worker has no equivalent. Listed
   as a deprecated stub per above.
-- **Authentication / multi-tenancy.** MVP-1 is open (OSS content,
-  read-only). Bearer / CF Access / HMAC moves to MVP-2 alongside
-  tool restoration.
+- **HMAC request signing.** Deferred to MVP-2 alongside tool
+  restoration — see `## Auth surface` § `hmac-deferred`.
+- **Cloudflare Access integration.** Deferred to MVP-2 — see
+  `## Auth surface` § `cf-access-deferred`.
+- **Multi-tenancy.** No per-tenant content, no tenant routing,
+  no tenant-scoped tokens. Future scope.
 - **Network egress from the Worker** beyond an **explicit subrequest
   allowlist** — see invariants below.
 
+## Auth surface
+
+The Worker ships with **two MVP-1 modes** (operator-selectable at deploy
+time) and **two deferred modes**. The mode in effect is determined by
+which Wrangler secrets are set on the deployed Worker — there is no
+runtime mode switch.
+
+### Mode `public` (MVP-1 default)
+
+- **Trigger:** `MCP-Token` Wrangler secret is **unset**.
+- **Ingress protection:** edge cache (Invariant 4) + Cloudflare
+  account-level anti-abuse + DDoS shielding (Invariant 8). No
+  per-request auth check.
+- **README allowed to recommend:** mode `public` for OSS,
+  read-only deploys where the catalog URL is shared widely.
+- **Out of scope:** any guarantee of privacy. The content is OSS;
+  the URL is the gate, the catalog is not.
+
+### Mode `bearer-auth` (MVP-1 operator opt-in)
+
+- **Trigger:** `MCP-Token` Wrangler secret is **set** (via
+  `task mcp:cloud:secret-put` → `wrangler secret put MCP-Token`).
+  The secret value is the bearer token clients must present.
+- **Enforcement:** every `POST /` request must carry
+  `Authorization: Bearer <MCP-Token>`. On mismatch the Worker
+  returns HTTP `401` with a JSON-RPC error envelope (code `-32001`,
+  message `"Unauthorized"`) and the RFC 6750
+  `WWW-Authenticate: Bearer realm="agent-config-mcp"` header.
+  Implementation: `workers/mcp/src/index.ts` § auth gate (the
+  `if (requiredToken) { … }` block).
+- **Liveness carve-out:** the `GET /` liveness probe is
+  unauthenticated by design — health checks and `curl` smoke tests
+  keep working without the token. Only `POST /` (the JSON-RPC
+  surface) is gated.
+- **Token handling:** the secret is prompted for interactively by
+  `wrangler` — never accepted via argv per
+  [`tool-safety`](../../.agent-src/rules/tool-safety.md). The
+  Worker never logs the secret, never echoes it in error bodies,
+  and never includes it in telemetry sinks.
+- **README allowed to recommend:** mode `bearer-auth` for private
+  deploys where the catalog URL must be unguessable but a shared
+  token is acceptable.
+- **Out of scope:** per-client token rotation, token expiry,
+  token-scoped tool subsets, OAuth flows. Operators rotate the
+  secret by re-running `task mcp:cloud:secret-put` and updating
+  client config — there is no in-band rotation path.
+
+### Mode `hmac-deferred` (MVP-2)
+
+- **Status:** deferred. Wake-up triggers per `## MVP-2 wake-up
+  triggers` below.
+- **Shape (if and when restored):** request signing per
+  [`mcp-request-signing`](../guidelines/agent-infra/mcp-request-signing.md)
+  § HMAC pattern. Replaces `bearer-auth` for the same operator
+  cohort; not additive in MVP-2.
+- **README allowed to recommend:** none until the mode ships. A
+  README that names `hmac-deferred` as available is a contract
+  violation.
+
+### Mode `cf-access-deferred` (MVP-2)
+
+- **Status:** deferred. Same wake-up triggers as `hmac-deferred`.
+- **Shape (if and when restored):** Cloudflare Access policy in
+  front of the Worker — SSO-fronted, per-identity. Replaces
+  `bearer-auth` for the corporate-SSO operator cohort.
+- **README allowed to recommend:** none until the mode ships.
+
+### Bidirectional contract ↔ README drift
+
+The README MCP section may **only** name modes that this `## Auth
+surface` section declares. This contract must declare every mode the
+README names. The drift test
+`tests/test_mcp_contract_readme_sync.py` enforces both directions
+per Phase 1 Step 4 of `agents/roadmaps/road-to-distribution-maturity.md`.
+
 ## A0-cloud invariants
 
 The Worker code must satisfy all of:
@@ -112,22 +273,30 @@ The Worker code must satisfy all of:
    Concurrent deployments are not supported; the release pipeline
    serializes through `release: published` + `workflow_dispatch`
    hotfix paths.
-8. **Ingress protection = edge cache + platform rate limit.** MVP-1
-   is auth-less by design; the public surface is shielded by two
-   layers Cloudflare provides without code: (a) edge caching per
-   invariant 4 (1 h on pinned URLs, 5 min on `latest`) absorbs
-   read-loop traffic before it reaches the Worker, and (b)
-   Cloudflare's account-level anti-abuse + DDoS shielding caps
-   per-IP burst on `*.workers.dev`. These two together **are** the
-   MVP-1 auth surrogate. **Promotion triggers** — any of these
-   flips HMAC (currently MVP-2 §Out-of-scope) from deferred to
-   active before the wake-up triggers below would otherwise fire:
-   sustained 429 spikes from origin (cache miss storm), Workers
-   request-cost line item exceeding the free-tier budget for two
-   consecutive billing periods, or a CVE-class abuse report
-   against the endpoint. A per-Worker `[[unsafe.bindings]]`
-   rate-limiter in `wrangler.toml` is **not** configured in MVP-1
-   — adding one is a contract amendment, not a free hand.
+8. **Ingress protection — layered, mode-aware.** MVP-1's default
+   mode is `public` (`## Auth surface` § `public`); operators may
+   opt into `bearer-auth` by setting the `MCP-Token` Wrangler secret.
+   Two infrastructure layers apply unconditionally and one
+   per-request layer applies only in `bearer-auth`:
+   - (a) **Edge cache** per invariant 4 (1 h on pinned URLs, 5 min
+     on `latest`) absorbs read-loop traffic before it reaches the
+     Worker.
+   - (b) **Cloudflare account-level anti-abuse + DDoS shielding**
+     caps per-IP burst on `*.workers.dev`.
+   - (c) **Per-request bearer check** when `MCP-Token` is set:
+     `POST /` mismatches return HTTP 401 + JSON-RPC error +
+     RFC 6750 `WWW-Authenticate`; `GET /` liveness is exempt.
+   Layers (a)+(b) are the **public-mode** auth surrogate. Layer
+   (c) is the **bearer-auth-mode** narrowing. **Promotion triggers**
+   — any of these flips HMAC (currently `hmac-deferred` per
+   `## Auth surface`) from deferred to active before the wake-up
+   triggers below would otherwise fire: sustained 429 spikes from
+   origin (cache miss storm), Workers request-cost line item
+   exceeding the free-tier budget for two consecutive billing
+   periods, or a CVE-class abuse report against the endpoint. A
+   per-Worker `[[unsafe.bindings]]` rate-limiter in `wrangler.toml`
+   is **not** configured in MVP-1 — adding one is a contract
+   amendment, not a free hand.
 
 ## Deprecated tool stub contract
 
@@ -154,14 +323,17 @@ deprecation message. No other tool name is reachable.
 ## MVP-2 wake-up triggers
 
 The Phase-7 deferred items in the roadmap (tool restoration, history
-persistence, auth) wake up only when **all** of these fire:
+persistence, `hmac-deferred` / `cf-access-deferred` from `## Auth
+surface`) wake up only when **all** of these fire:
 
 - A named consumer (internal or external) requests hosted lint or
   history.
 - A security review has approved the validation layer for
   `lint_skills` (URI regex allowlist, size limits, timeout,
   concurrency cap).
-- An auth model has been selected (bearer vs. CF Access vs. HMAC).
+- A second auth model beyond `bearer-auth` has been selected
+  (HMAC or CF Access). Bearer is already MVP-1 per `## Auth
+  surface` § `bearer-auth`; the wake-up gates the **second** mode.
 - The server stability label has been promoted from *experimental*
   to *beta*.
 

package/docs/contracts/mcp-phase-1-scope.md

@@ -1,5 +1,6 @@
 ---
 stability: experimental
+mcp_scope: full
 ---
 
 # MCP Server — Phase 1–6 Scope (A0 Hard Contract)

package/docs/contracts/persona-schema.md

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

package/docs/decisions/ADR-007-agent-discovery-scopes.md

@@ -262,6 +262,73 @@ maintainer manifest).
   road-to-simplicity-and-everywhere" is **never built**. Roadmap
   entry should be updated to point at `export` instead.
 
+## Amendment 2026-05-13 — Augment global-only
+
+**Status:** Accepted · 2026-05-13 · signed off by Matze.
+
+### Trigger
+
+Real install measurement: the full body of every file in
+`~/.augment/rules/` counts against Augment's **49,512-char
+workspace-guidelines limit** (not just the description stubs that
+`scripts/measure_augment_budget.py` assumes for `type: auto` rules).
+A populated `~/.augment/rules/` deterministically exceeds the budget
+on every workspace (~138k chars observed — ~89k over limit).
+
+The competing pressure: a per-project deploy of the same content
+would still overflow Augment's limit (the limit is per-workspace,
+not per-scope) **and** would scatter the content across every repo
+the developer opens, multiplying the maintenance surface.
+
+### Decision
+
+`augment` becomes **global-only** in `SCOPE_SUPPORT`:
+
+- `npx @event4u/agent-config init --tools=augment --global` — supported.
+- `npx @event4u/agent-config init --tools=augment` (project) — **rejected**
+  with a directive error pointing at this amendment.
+- `npx @event4u/agent-config init` (default `--tools=all` at project
+  scope) — silently filters `augment` out (matching the
+  `claude-desktop` / `jetbrains` pattern).
+
+Project-scope `init` still writes `.augment/settings.json` as a
+substrate bridge (plugin activation marker for the workspace) — but
+**no** rules, skills, commands, contexts, personas, or templates are
+written into `.augment/` at project scope.
+
+### Trade-off accepted
+
+The Augment workspace-guidelines overflow is a **known, surfaced
+trade-off**, not a defect to fix. The package owner accepts that the
+IDE will report the budget exceeded; the content shape is the
+source of value, and chunking it to fit the limit would dilute that
+value below the threshold that justifies the tool. The overflow
+warning is documented in
+[`docs/setup/per-ide/augment.md`](../setup/per-ide/augment.md#troubleshooting).
+
+### Supersedes
+
+The earlier `fix/augment-project-scope-only` branch (commit
+`158f9912`, never merged) — which inverted the scope to
+**project-only** — is hereby superseded. The project-only direction
+solved the overflow at the cost of fragmenting content across every
+repo; this amendment trades that cost for a single global surface
+plus an explicit overflow tolerance.
+
+### Consequences
+
+- `GLOBAL_DEPLOY_SOURCES['augment']` carries the 6 source-to-dest
+  mappings (rules, skills, commands, contexts, personas, templates)
+  and remains the canonical Augment install surface.
+- `_validate_scope` hard-rejects explicit `augment` at project scope
+  and silently filters under `--tools=all --project`.
+- Tests: `test_augment_rejects_project`,
+  `test_all_silent_filters_augment_under_project`, and the existing
+  `test_install_global_deploys_augment_content` pin the contract.
+- The Supported Tools table in `README.md` moves Augment out of the
+  project-installed category into the global-only (marker-in-project)
+  category, alongside Claude Desktop.
+
 ## Implementation Plan (deferred to roadmap)
 
 Out of scope for this ADR. Sequencing target for a separate roadmap: