@event4u/agent-config 2.6.1 → 2.7.0

package/docs/contracts/CHANGELOG-conventions.md

@@ -0,0 +1,121 @@
+---
+stability: stable
+---
+
+# Changelog Conventions
+
+> **Status:** Active · governs the shape of [`CHANGELOG.md`](../../CHANGELOG.md)
+> and the per-era archive files under [`docs/archive/`](../archive/).
+> Cited from the CHANGELOG header and enforced by
+> `tests/test_changelog_eras.py`.
+
+## Purpose
+
+Locks the entry shape, the breaking-change rules, and the era-split
+discipline for `event4u/agent-config`. Auto-generated entries (e.g.
+release-please) and hand-written entries follow the same shape so the
+file remains uniform across automated and manual releases.
+
+## Entry shape
+
+Each released version is a level-2 heading with a compare link and a
+release date:
+
+```md
+## [X.Y.Z](https://github.com/event4u-app/agent-config/compare/PREV...X.Y.Z) (YYYY-MM-DD)
+```
+
+Inside the version block, group changes under level-3 headings using
+the Conventional Commits family the entry came from:
+
+- `### Features` — `feat:` commits.
+- `### Bug Fixes` — `fix:` commits.
+- `### Chores` — `chore:`, `build:`, `ci:` commits a user might want
+  to see (silent infra-only chores stay out).
+- `### Docs` — `docs:` commits that change user-facing behaviour or
+  surface (otherwise drop them).
+- `### BREAKING CHANGES` — see [What counts as breaking](#what-counts-as-breaking).
+- `### Reverts` — `revert:` commits, with the SHA of the original commit.
+
+Each bullet is one line, scope-prefixed, with the short SHA linked:
+
+```md
+* **scope:** imperative-mood summary ([abc1234](https://github.com/event4u-app/agent-config/commit/abc1234...))
+```
+
+Optional trailers — a free-form paragraph for the release narrative
+(only for non-trivial releases), followed by a single-line test count
+delta:
+
+```md
+Tests: NNNN (+M since X.Y.(Z-1))
+```
+
+The test-count line is enforced for any release that ships changes to
+`scripts/`, `workers/`, or `.agent-src/` content; it can be omitted for
+pure-docs releases.
+
+## What counts as breaking
+
+A change is **breaking** (and MUST appear under `### BREAKING CHANGES`
+**and** bump the major version) when it changes:
+
+1. **Public CLI surface** — `agent-config <cmd>` flags / subcommands at
+   Tier-0 or Tier-1 (Tier-2 is internal per
+   [`command-surface-tiers.md`](command-surface-tiers.md) and may shift
+   without a major bump).
+2. **Install scopes** — adding / removing a scope (`global`, `project`,
+   `mcp_scope: lite|full`) or changing its default discovery path per
+   [`ADR-007`](../decisions/ADR-007-agent-discovery-scopes.md).
+3. **MCP Worker contracts** — anything that breaks
+   [`mcp-cloud-scope.md`](mcp-cloud-scope.md) or
+   [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md) (tool shape, prompt
+   ids, resource URIs).
+4. **Generated tree shape** — removing or renaming top-level
+   directories under `.agent-src/`, `.augment/`, `.claude/`,
+   `.cursor/`, `.clinerules/`, or `.windsurfrules`.
+5. **Settings keys** — removing / renaming a key in
+   `.agent-settings.yml` that consumer projects may rely on. Adding a
+   new key with a default is **not** breaking.
+6. **AGENTS.md / kernel rules** — removing or renaming an Iron-Law
+   rule, or changing the kernel-membership contract per
+   [`kernel-membership.md`](kernel-membership.md).
+
+Internal refactors, doc rewrites, test changes, and any change to
+files under `.agent-src.uncompressed/` that round-trip through
+`task sync` unchanged are **not** breaking.
+
+## Era splits
+
+`CHANGELOG.md` keeps only the **current era** inline; prior eras live
+under [`docs/archive/`](../archive/) and are read-only.
+
+Drift gate — `tests/test_changelog_eras.py` fails when the current
+era's body (lines between `# Era: X.Y.x — current` and the next era
+header) exceeds **200 lines**. When that happens:
+
+1. Pick the next major or significant minor boundary at the bottom of
+   the current era (typically the last `X.Y.0` release).
+2. Move every entry at or below that boundary into
+   `docs/archive/CHANGELOG-pre-<boundary>.md`, prepending the standard
+   archive header.
+3. Replace the moved entries in `CHANGELOG.md` with a single collapsed
+   `# Era: pre-<boundary> — archived` section that links to the
+   archive file.
+4. Rename the active era header to `# Era: <new-current>.x — current`.
+5. Update the `## [Unreleased]` placeholder unchanged.
+
+Each era split lands as its own `chore(changelog): split era X.Y.x →
+pre-X.Y.x` commit — never bundled with a feature release.
+
+## Cross-references
+
+- [`../../CHANGELOG.md`](../../CHANGELOG.md) — active era + Unreleased.
+- [`../archive/CHANGELOG-pre-2.2.0.md`](../archive/CHANGELOG-pre-2.2.0.md) —
+  frozen pre-2.2.0 entries.
+- [`command-surface-tiers.md`](command-surface-tiers.md) — Tier-0/1/2
+  split that governs CLI-surface breaking-change classification.
+- [`mcp-cloud-scope.md`](mcp-cloud-scope.md) ·
+  [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md) — MCP contract bounds.
+- [`../decisions/ADR-007-agent-discovery-scopes.md`](../decisions/ADR-007-agent-discovery-scopes.md) —
+  install scope discovery.

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

@@ -0,0 +1,140 @@
+# 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/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/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: