@event4u/agent-config 8.2.0 → 8.4.0

package/dist/mcp/registry-manifest.json

@@ -3,13 +3,13 @@
     "artefact_count": 527,
     "scanner_version": "6f13c4a07cc0"
   },
-  "generated_at": "2026-07-07",
+  "generated_at": "2026-07-08",
   "package": {
     "description": "Universal AI Agent OS \u2014 audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "homepage": "https://github.com/event4u-app/agent-config#readme",
     "name": "@event4u/agent-config",
     "repository": "https://github.com/event4u-app/agent-config",
-    "version": "8.2.0"
+    "version": "8.4.0"
   },
   "registries": [
     {

package/docs/contracts/CHANGELOG-conventions.md

@@ -110,17 +110,20 @@ pre-X.Y.x` commit — never bundled with a feature release.
 
 ### Gate-vs-script contract
 
-- **Canonical splitter** — `scripts/release.py`. When a release crosses
-  a minor/major boundary and the current era body is at or over the
-  250-line cap, the release pipeline writes the
+- **Canonical splitter** — `src/scripts/release.ts`, run via `task release`
+  or the `release`-labeled-PR CI path
+  (`.github/workflows/release.yml`, see
+  [`ADR-113`](../decisions/ADR-113-ci-native-release-label-trigger.md)).
+  When a release crosses a minor/major boundary and the current era body
+  is at or over the 250-line cap, the release pipeline writes the
   `chore(changelog): split era …` commit **first**, then the
   `release: X.Y.Z` commit. The maintainer does not run the split by
   hand for the release path.
-- **Backstop** — `tests/test_changelog_eras.py::test_current_era_body_under_cap`
+- **Backstop** — `tests/lib/changelog_eras.test.ts` (`test_current_era_body_under_cap`)
   catches entries written **outside** the release script (hand-edited
   Unreleased section, agent-authored hotfix entries, doc patches). The
   failure message names `task release` as the auto-split path.
-- **Shared cap constant** — `scripts/_lib/changelog_eras.py` owns
+- **Shared cap constant** — `src/scripts/_lib/changelog_eras.ts` owns
   `CURRENT_ERA_BODY_CAP` and the era-header regex. Both the test and
   the release script import from there; no parallel copies.
 - **Patch-release overflow** — a `patch` bump cannot cross an era

package/docs/contracts/branch-protection-policy.md

@@ -54,7 +54,14 @@ per branch name.
 - **Feature PR** — head branch does not match `release/X.Y.Z` (the default).
 - **Release PR** — head branch matches `^release/\d+\.\d+\.\d+$` AND the
   diff stays within the version-bump allowlist (see `release-pr-gating.md`).
-  Either condition failing falls the PR back to feature-PR mode.
+  Either condition failing falls the PR back to feature-PR mode. Author is
+  either a maintainer (`task release`) or `github-actions[bot]` (the
+  `release`-labeled-PR CI path, `.github/workflows/release.yml`) — the
+  shape checks are author-agnostic. Verified live: this repo's branch
+  protection requires zero approving reviews and exactly one status check
+  (`Sync + Generate Tools Consistency`); the bot path's real friction is
+  GitHub's separate bot-created-PR approval gate, not a review requirement
+  — see [`ADR-113`](../decisions/ADR-113-ci-native-release-label-trigger.md).
 - **Docs-only PR** — diff is entirely inside `docs/**` or matches only
   top-level Markdown (`README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`,
   `AGENTS.md`). No code, tests, workflows, or scripts. This shape is
@@ -65,7 +72,7 @@ per branch name.
 ## Failure mode — the cut never silently lifts
 
 If a release-PR's diff exits the allowlist mid-stream (e.g. a last-minute
-CHANGELOG fixup that also touches `scripts/release.py`):
+CHANGELOG fixup that also touches `src/scripts/release.ts`):
 
 1. `Release Validation / release-shape` exits non-zero.
 2. The required-check set for the PR effectively flips back to the
@@ -125,6 +132,8 @@ its own protection rules:
 - [`ci-cost-budget.md`](ci-cost-budget.md) — measured baseline durations
   per job + quarterly review cadence (Phase C).
 - `.github/workflows/release-validation.yml` — the three release-PR jobs.
-- `scripts/check_release_pr_shape.py` — the shape detector.
-- `scripts/release.py` — emits release PRs; release cadence stays driven
-  by Conventional Commits, not CI cost.
+- `src/scripts/check_release_pr_shape.ts` — the shape detector.
+- `src/scripts/release.ts` — emits release PRs (both entry points); release
+  cadence stays driven by Conventional Commits, not CI cost.
+- [`ADR-113`](../decisions/ADR-113-ci-native-release-label-trigger.md) — the
+  CI-native (`release`-label) entry point and the bot-PR-approval finding.

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

@@ -181,6 +181,81 @@ does not introduce a new tool, resource type, or protocol surface.
   process per stdio session. Multi-tenancy lives with the future
   bridge, not the kernel.
 
+## Amendment — MCP Full Power (accepted 2026-07-07)
+
+> **Status: Accepted.** Recorded by `road-to-mcp-full-power.md` Phase 3.
+> User signoff on the `a0-amendment-signoff` blocker plus the council
+> verdict in `agents/decisions/mcp-write-exec-cut-2026-07-07.md` both
+> landed 2026-07-07. Existing Phase 1–6 sections above predate the TS
+> migration (they still reference `scripts/mcp_server/*.py` and a
+> two-tool allowlist) and are known-stale beyond what this amendment
+> covers; a full contract refresh is a separate follow-up, out of scope
+> here.
+
+**Named consumer ask.** Operator, 2026-07-07: expose the CLI/script long
+tail (roadmap, telemetry, capabilities, doctor, council, memory, …) through
+MCP in safety tiers, not just the current 9-tool read-only/single-write set.
+
+**Safety-tier model** (full classification:
+[`agents/settings/contexts/mcp-tool-tier-map.md`](../../agents/settings/contexts/mcp-tool-tier-map.md)):
+
+| Tier | Contract treatment |
+|---|---|
+| `read-only` | May be implemented without further gate — same bar as the existing 9 tools. |
+| `fs-write-in-tree` | May be implemented once path-guarded via `_validateInTreePath` — same pattern as `chat_history_append`. |
+| `shell-exec` | Requires the safety envelope: fixed argv (no shell interpolation of caller-supplied strings), timeout, output truncation, no network access from the spawned process. Implementation requires the Phase 3 council verdict naming it in the cut list. |
+| `network` | Never silent-default. Every call surfaces cost/consequence before executing; billable calls (e.g. `council:run`) require the caller to pass an explicit confirmation flag echoed back in the tool result, not just be callable. |
+| `long-running` | Structurally excluded — not tool-call-shaped (blocks or starts a server). |
+| `hard-floor-never` | **Permanently excluded.** Secrets (`keys:install-*`), the global/outside-repo install (`upgrade`, `global`, `refresh`, `settings:migrate`), and bulk-destructive commands (`uninstall`, `prune`) are never reachable via any MCP tool, bridge, or allowlist entry, under any settings value. This list only grows, never shrinks, without a fresh A0 amendment of its own. |
+
+**Deny-by-default, build-time only.** No consumer-settings allowlist ships
+(a `mcp.tools.allow` runtime setting was considered and **rejected** by
+the Phase 3 council — see below). A tool is reachable if and only if it
+was generated into the build from an approved tier-map entry. Enabling a
+new tool is a code change (add the entry, rebuild), never a settings
+edit. `hard-floor-never` tier entries are never generated — the
+exclusion is structural (the tool does not exist in `tools/list`), not a
+runtime rejection.
+
+**Bridge shape (Phase 5) — decided: pure build-time codegen.** Every
+approved tool, in every tier including `shell-exec`, is generated at
+build time from `src/cli/registry.ts` metadata plus the tier map — one
+MCP tool per approved command, each with its own JSON Schema. A generic
+`agent_config_cli` tool with a runtime-validated `subcommand` argument
+was considered and rejected: the package's existing `chat_history_append`
+pattern is already a compiled tool with a hardcoded path guard, not a
+generic bridge gated by an editable setting, and the council verdict
+(`agents/decisions/mcp-write-exec-cut-2026-07-07.md`) found the
+runtime-allowlist approach strictly weaker on security grounds for no
+countervailing benefit. Shell-exec tools additionally compile in their
+safety envelope (fixed argv, timeout, output cap, no network) as
+constants, not configuration.
+
+**Shell-exec safety review (Phase 5, shipped pilot: `run_tests`).**
+Lethal-trifecta pass for the one approved exec-tier tool:
+
+- *Untrusted-content ingestion:* the tool's inputs (`filter`, `path`) come
+  from the MCP caller — the same principal that already holds the chat
+  surface; no fetched/external content selects what runs. Caller strings
+  become literal argv elements via
+  `src/scripts/mcp_exec/safety_envelope.ts` (`execFile`, no shell) — a
+  hostile string cannot become a second command.
+- *Private-data access:* the spawned vitest run sees the consumer tree,
+  same as every fs tool; no credential paths are added to its env.
+- *Egress:* the envelope adds no network I/O of its own. Arbitrary test
+  code MAY use the network — that is a property of the project's tests,
+  not of the tool; the envelope's guarantees are spawn-surface guarantees
+  (no shell, `SIGKILL` timeout, per-stream byte caps), stated as such and
+  never marketed as network isolation.
+- *Compiled constants:* 120s timeout, 64KB per-stream cap — code-review
+  events, not settings.
+
+**Long-running policy (Phase 5) — decided: synchronous truncation.** No
+async job/poll pattern ships: an exec call that exceeds its compiled
+timeout returns `timed_out: true` with the captured, capped output.
+Revisit only if a council-approved tool genuinely cannot fit a
+synchronous budget (e.g. a future `council:run`).
+
 ## Revision policy
 
 This contract is **experimental** — breaking changes are allowed in any

package/docs/contracts/mcp-tool-inventory.md

@@ -14,21 +14,21 @@ keep-beta-until: 2026-08-14
 
 ## Summary
 
-- **Total tools:** 20
-- **By transport:** stdio=9
-- **By side-effect:** fs-write=5, ro=12, shell=3
-- **Discovery-only stubs (no implementation):** 11
+- **Total tools:** 27
+- **By transport:** stdio=18
+- **By side-effect:** fs-write=8, ro=16, shell=3
+- **Discovery-only stubs (no implementation):** 9
 
 ## Tools
 
 | Tool | Side-effect | Transports | Catalog | Handler |
 |---|---|---|---|---|
-| `lint_skills` | `ro` | stdio | [`consumer_tool_catalog.json:7`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L7) | [`tools.ts:575`](../../src/scripts/mcp_server/tools.ts#L575) |
-| `chat_history_append` | `fs-write` | stdio | [`consumer_tool_catalog.json:24`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L24) | [`tools.ts:603`](../../src/scripts/mcp_server/tools.ts#L603) |
-| `chat_history_read` | `ro` | stdio | [`consumer_tool_catalog.json:43`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L43) | [`tools.ts:664`](../../src/scripts/mcp_server/tools.ts#L664) |
-| `memory_lookup` | `ro` | stdio | [`consumer_tool_catalog.json:59`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L59) | [`tools.ts:706`](../../src/scripts/mcp_server/tools.ts#L706) |
-| `memory_signal` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:75`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L75) | _stub-only_ |
-| `memory_status` | `ro` | stdio | [`consumer_tool_catalog.json:91`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L91) | [`tools.ts:748`](../../src/scripts/mcp_server/tools.ts#L748) |
+| `lint_skills` | `ro` | stdio | [`consumer_tool_catalog.json:7`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L7) | [`tools.ts:1102`](../../src/scripts/mcp_server/tools.ts#L1102) |
+| `chat_history_append` | `fs-write` | stdio | [`consumer_tool_catalog.json:24`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L24) | [`tools.ts:1130`](../../src/scripts/mcp_server/tools.ts#L1130) |
+| `chat_history_read` | `ro` | stdio | [`consumer_tool_catalog.json:43`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L43) | [`tools.ts:1191`](../../src/scripts/mcp_server/tools.ts#L1191) |
+| `memory_lookup` | `ro` | stdio | [`consumer_tool_catalog.json:59`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L59) | [`tools.ts:1233`](../../src/scripts/mcp_server/tools.ts#L1233) |
+| `memory_signal` | `fs-write` | stdio | [`consumer_tool_catalog.json:75`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L75) | [`tools.ts:1360`](../../src/scripts/mcp_server/tools.ts#L1360) |
+| `memory_status` | `ro` | stdio | [`consumer_tool_catalog.json:91`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L91) | [`tools.ts:1275`](../../src/scripts/mcp_server/tools.ts#L1275) |
 | `skill_trigger_eval` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:98`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L98) | _stub-only_ |
 | `suggest_command` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:114`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L114) | _stub-only_ |
 | `suggest_skill_for_task` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:129`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L129) | _stub-only_ |
@@ -36,13 +36,20 @@ keep-beta-until: 2026-08-14
 | `update_form_request_messages` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:158`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L158) | _stub-only_ |
 | `sync_gitignore` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:173`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L173) | _stub-only_ |
 | `sync_agent_settings` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:186`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L186) | _stub-only_ |
-| `run_tests` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:200`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L200) | _stub-only_ |
+| `run_tests` | `shell` | stdio | [`consumer_tool_catalog.json:200`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L200) | [`tools.ts:1535`](../../src/scripts/mcp_server/tools.ts#L1535) |
 | `run_quality_checks` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:214`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L214) | _stub-only_ |
-| `list_skills` | `ro` | stdio | [`consumer_tool_catalog.json:227`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L227) | [`tools.ts:762`](../../src/scripts/mcp_server/tools.ts#L762) |
-| `list_commands` | `ro` | stdio | [`consumer_tool_catalog.json:234`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L234) | [`tools.ts:777`](../../src/scripts/mcp_server/tools.ts#L777) |
-| `list_rules` | `ro` | stdio | [`consumer_tool_catalog.json:241`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L241) | [`tools.ts:792`](../../src/scripts/mcp_server/tools.ts#L792) |
+| `list_skills` | `ro` | stdio | [`consumer_tool_catalog.json:227`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L227) | [`tools.ts:1289`](../../src/scripts/mcp_server/tools.ts#L1289) |
+| `list_commands` | `ro` | stdio | [`consumer_tool_catalog.json:234`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L234) | [`tools.ts:1304`](../../src/scripts/mcp_server/tools.ts#L1304) |
+| `list_rules` | `ro` | stdio | [`consumer_tool_catalog.json:241`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L241) | [`tools.ts:1319`](../../src/scripts/mcp_server/tools.ts#L1319) |
 | `compile_router` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:248`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L248) | _stub-only_ |
-| `read_resource_body` | `ro` | stdio | [`consumer_tool_catalog.json:261`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L261) | [`tools.ts:808`](../../src/scripts/mcp_server/tools.ts#L808) |
+| `read_resource_body` | `ro` | stdio | [`consumer_tool_catalog.json:261`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L261) | [`tools.ts:1335`](../../src/scripts/mcp_server/tools.ts#L1335) |
+| `roadmap_progress` | `fs-write` | stdio | [`consumer_tool_catalog.json:275`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L275) | [`tools.ts:1394`](../../src/scripts/mcp_server/tools.ts#L1394) |
+| `roadmap_archive` | `fs-write` | stdio | [`consumer_tool_catalog.json:288`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L288) | [`tools.ts:1417`](../../src/scripts/mcp_server/tools.ts#L1417) |
+| `capabilities_index` | `fs-write` | stdio | [`consumer_tool_catalog.json:295`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L295) | [`tools.ts:1433`](../../src/scripts/mcp_server/tools.ts#L1433) |
+| `doctor_report` | `ro` | stdio | [`consumer_tool_catalog.json:308`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L308) | [`tools.ts:1456`](../../src/scripts/mcp_server/tools.ts#L1456) |
+| `conformance_check` | `ro` | stdio | [`consumer_tool_catalog.json:315`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L315) | [`tools.ts:1470`](../../src/scripts/mcp_server/tools.ts#L1470) |
+| `telemetry_report` | `ro` | stdio | [`consumer_tool_catalog.json:322`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L322) | [`tools.ts:1484`](../../src/scripts/mcp_server/tools.ts#L1484) |
+| `council_estimate` | `ro` | stdio | [`consumer_tool_catalog.json:335`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L335) | [`tools.ts:1506`](../../src/scripts/mcp_server/tools.ts#L1506) |
 
 ## Glossary
 

package/docs/contracts/release-pr-gating.md

@@ -5,7 +5,14 @@ keep-beta-until: 2026-09-04
 
 # Release-PR Gating Contract
 
-> **Status:** active · **Owner:** maintainer (`scripts/release.py`) · **Opened:** 2026-05-26
+> **Status:** active · **Owner:** maintainer (`src/scripts/release.ts`) · **Opened:** 2026-05-26
+>
+> Release PRs are opened by either entry point into `release.ts`: `task
+> release` (interactive, local) or `.github/workflows/release.yml` (the
+> `release`-labeled-PR CI path, author `github-actions[bot]`) — see
+> [`ADR-113`](../decisions/ADR-113-ci-native-release-label-trigger.md).
+> This contract's shape checks are author-agnostic by design; both entry
+> points produce the identical PR shape below.
 >
 > Source: `road-to-optimized-ci-and-release-gates.md` Phase A Step 1. Measured
 > baseline (`gh run list --branch main --limit 50`): `Public Install Smoke`
@@ -22,21 +29,23 @@ A pull request qualifies as a **release PR** when **both** of the following
 hold:
 
 1. **Head branch matches** `^release/\d+\.\d+\.\d+$` — same regex as
-   `scripts/release.py` § `_RELEASE_BRANCH_RE`.
+   `src/scripts/release.ts` § `_RELEASE_BRANCH_RE`.
 2. **Diff file set is a subset of the version-bump allowlist:**
    - `package.json`
    - `CHANGELOG.md`
    - `.claude-plugin/marketplace.json`
    - `packages/*/pack.yaml`
    - `packages/*/README.md`
-   - `docs/archive/CHANGELOG-pre-*.md` — emitted by `scripts/release.py`'s
+   - `docs/archive/CHANGELOG-pre-*.md` — emitted by `release.ts`'s
      automatic CHANGELOG era split (see `docs/contracts/CHANGELOG-conventions.md`
      § Era splits) when the current era crosses its line cap on an
      era-boundary release.
 
-Both predicates are enforced by `scripts/check_release_pr_shape.py`
-(stdlib-only, ≤ 150 LOC). The script exits 0 when both hold; non-zero with
-a per-file diff naming any out-of-allowlist entry otherwise.
+Both predicates are enforced by `src/scripts/check_release_pr_shape.ts`.
+The script exits 0 when both hold; non-zero with a per-file diff naming any
+out-of-allowlist entry otherwise. It reads the diff shape only — it does
+not check the PR author, so it passes identically for a `task
+release`-opened PR and a `release.yml`-opened one.
 
 ## Cut surface — heavy jobs that skip on release PRs
 
@@ -76,10 +85,10 @@ the feature-PR floor by adding:
 
 The optimisation is **opt-in by shape, not by branch name**. A release-PR
 whose diff contains a stray file outside the allowlist (e.g. a last-minute
-CHANGELOG fixup that also touches `scripts/release.py`) trips the shape
+CHANGELOG fixup that also touches `src/scripts/release.ts`) trips the shape
 detector:
 
-1. `check_release_pr_shape.py` exits non-zero with a per-file diff.
+1. `check_release_pr_shape.ts` exits non-zero with a per-file diff.
 2. The CI dashboard surfaces "release-shape" red.
 3. The maintainer either narrows the diff (move the script edit to a
    separate PR) or accepts the heavy matrix re-running on the next push.
@@ -95,7 +104,7 @@ name alone never bypasses the heavy matrix.
 - **Not a coverage-reduction contract.** The release-validation jobs are
   additive, not substitutive.
 - **Not a release-velocity contract.** Release cadence is driven by
-  Conventional Commits in `scripts/release.py`, not by CI cost.
+  Conventional Commits in `src/scripts/release.ts`, not by CI cost.
 - **Not a Hard-Floor lift.** No security check is removed.
   `release-guard.yml`'s `assert-version-matches-tag` job is independent of
   `Tests` / `Public Install Smoke` and stays mandatory on every tag.
@@ -108,6 +117,8 @@ name alone never bypasses the heavy matrix.
   cadence (Phase C).
 - `.github/workflows/release-validation.yml` — the tight release-shape
   validation workflow (Phase B).
-- `scripts/check_release_pr_shape.py` — the shape detector (Phase A).
-- `scripts/release.py` § `_RELEASE_BRANCH_RE` — source of truth for the
+- `src/scripts/check_release_pr_shape.ts` — the shape detector (Phase A).
+- `src/scripts/release.ts` § `_RELEASE_BRANCH_RE` — source of truth for the
   release-branch naming convention.
+- [`ADR-113`](../decisions/ADR-113-ci-native-release-label-trigger.md) — the
+  CI-native (`release`-label) entry point into the same script.

package/docs/contracts/surface-matrix.md

@@ -0,0 +1,103 @@
+# Surface Matrix — per-tool canonical-surface contract
+
+> Machine-checked inventory of which install surface is canonical per tool,
+> which alternates are legitimate, what counts as a duplicate surface, and
+> how a duplicate converges. One data file replaces 23 hand-maintained
+> special cases (council Q3, 2026-07-07 — see
+> `agents/settings/contexts/claude-code-single-surface-decision.md` for the
+> parent decision).
+
+## The file
+
+`src/config/surface-matrix.yml` — ships in the npm package, resolved at
+runtime relative to the package root (works from both the tsx dev path and
+the bundled CLI).
+
+```yaml
+schema_version: 1
+tools:
+  <tool-id>:                # must exist in install.ts::USER_SCOPE_PATHS
+    surface: projection | plugin | bundles | export-only
+    scope_path: "~/..."     # must equal USER_SCOPE_PATHS[tool-id]
+    hooks: managed-settings-block | settings-hooks-opt-in | plugin | none
+    alternates:             # optional — legitimate secondary surfaces
+      - id: <slug>
+        role: <why it is legitimate>
+        detail: <prose>
+    duplicate:              # optional — the duplicate-surface class
+      description: <prose>
+      detect:
+        all_of: [<path>, …] # ~/ = user scope, ./ = package-relative;
+                            # ALL present ⇒ duplicate surface exists
+      # OR, when suspected but unverified:
+      pending_evidence: <prose + pointer to the evidence gate>
+    converge:               # required when detect is defined
+      action: <slug>
+      command: "<copy-paste fix>"
+      reaps: [<path>, …]    # package-tagged locations converge may remove
+    notes: <provenance>
+```
+
+## Semantics
+
+- **`surface`** — `projection` (installer writes content into the user
+  scope path; that projection is canonical), `plugin` (the tool's own
+  plugin channel is canonical — e.g. Copilot, where no user-scope
+  projection exists), `bundles` (manual import artifacts, e.g.
+  Claude Desktop ZIPs), `export-only` (config/marker export, no content
+  tree).
+- **`duplicate.detect.all_of`** — existence checks only, never content
+  reads. All paths present ⇒ the duplicate class is live. Tools without a
+  `detect` block are never flagged.
+- **`pending_evidence`** — documents a *suspected* class that MUST NOT be
+  acted on (doctor ignores it, converge refuses it) until an evidence gate
+  defines real detect paths. Current example: Augment
+  (`agents/settings/contexts/augment-surface-parity.md`).
+- **`converge`** — the consented cleanup. `converge.reaps` is the
+  exhaustive allowlist of what `agent-config converge` may remove for this
+  tool; anything outside it is refused (hard floor: never user-authored
+  files).
+
+## Consumers
+
+| Consumer | What it reads | Behavior |
+|---|---|---|
+| `agent-config doctor` (`surface-state` check) | `duplicate.detect.all_of` | Existence-checks every declared duplicate class; `fail` names the tool + the `converge.command` as copy-paste remedy. The legacy `claude-plugin` check stays as the named first consumer with richer version diagnostics. |
+| `agent-config converge` (+ `upgrade --converge`) | `converge.*` | Performs the per-tool cleanup, only on matrix-declared, package-tagged paths (`converge.reaps`), after consent (`install.auto_converge` or interactive y/N). |
+| `dispatch:hook` `surface-probe` concern | `duplicate.detect.all_of` | Once-per-day SessionStart existence probe; one-line nudge naming the duplicate + the converge command. Fail-open, never blocking. |
+| CI (`task lint-surface-matrix` → `src/scripts/lint_surface_matrix.ts`) | whole file | Set equality with `USER_SCOPE_PATHS`, scope-path drift, enum validity, detect-path resolution, converge-command presence, plugin-id drift guard. |
+
+## Onboarding a new tool
+
+1. Add the tool to `install.ts::USER_SCOPE_PATHS` (and `SCOPE_SUPPORT`,
+   deploy sources) as usual.
+2. Add the matrix entry in the same commit — `lint-surface-matrix` fails
+   the build on a missing entry (that is the point: no tool ships without
+   a declared canonical surface).
+3. Default shape for a plain projection with no plugin channel:
+   `surface: projection`, `hooks: none`, no `duplicate` block.
+4. Only add a `duplicate` block when a second install channel actually
+   exists for the tool — and only add `detect.all_of` once the class has
+   been reproduced on a real setup (evidence gate; until then use
+   `pending_evidence`).
+
+## Consent model (converge)
+
+- First `agent-config converge` run persists `install.auto_converge: true`
+  into the **global** settings file
+  (`~/.event4u/agent-config/agent-settings.yml`). The key is read directly
+  by the CLI (converge/upgrade); it is intentionally NOT part of the
+  `MERGEABLE_KEYS` whitelist — it never merges into project-level agent
+  settings and never reaches session context.
+- Plain `upgrade` without the key keeps the print-only prompt (no silent
+  mutation of a user-owned surface — council Q2, 2026-07-07).
+- `converge --dry-run` prints the exact actions without touching anything.
+
+## See also
+
+- `agents/settings/contexts/claude-code-single-surface-decision.md` —
+  parent decision (single surface for Claude Code).
+- `agents/settings/contexts/augment-surface-parity.md` — the Augment
+  evidence gate that keeps its duplicate class `pending_evidence`.
+- `docs/contracts/skill-distribution-channels.md` — canonical-channel
+  contract the matrix operationalizes.

package/docs/decisions/ADR-111-canonical-glama-listing.md

@@ -0,0 +1,97 @@
+---
+adr: 111
+status: accepted
+date: 2026-07-07
+decision: canonical-glama-listing
+supersedes: —
+superseded_by: —
+phase: road-to-mcp-full-power
+type: standing
+---
+
+# ADR-111 — the kernel stdio server is the canonical Glama listing; the turnkey server stays unlisted
+
+## Status
+
+**Accepted** · 2026-07-07 · maintainer decision, Phase 2 of
+`road-to-mcp-full-power.md`.
+
+## Context
+
+The package now ships two distinct stdio MCP servers with different
+audiences and capability shapes:
+
+1. **Kernel stdio server** (`src/scripts/mcp_server/`, started via
+   `agent-config mcp:run`) — requires a repo checkout (or the glama build
+   step), exposes 430 prompts / 232 resources / 27 catalogued tools (9
+   implemented as of Phase 1/4 of this roadmap). This is the server glama.ai
+   currently indexes and lists at
+   `glama.ai/mcp/servers/event4u-app/agent-config`.
+2. **Turnkey stdio-lite server** (`src/cli/mcp/`, started via
+   `agent-config mcp-server`) — zero-setup, reads the bundled
+   `dist/agent-src/` + `docs/guidelines/` directly from the installed npm
+   package, no repo clone required. Read-only by design (ADR-085): zero
+   tools, prompts/resources only.
+
+`road-to-glama-registry-listing.md` (archived) already converged on listing
+only the stdio server for a contributor/agent-developer audience, before the
+turnkey server existed in its current form. This ADR re-confirms that choice
+now that both servers are live, and records why a second listing is not
+added.
+
+## Decision
+
+1. **Glama lists the kernel server only.** `glama.json` and the committed
+   `internal/glama/{build,run}` scripts continue to target
+   `src/scripts/mcp_server/__main__.ts`. No change to the glama admin
+   configuration.
+2. **The turnkey server is not submitted to glama.** Rationale:
+   - Glama's value proposition (repo-aware introspection, contributor
+     discovery) matches the kernel server's audience — people extending or
+     debugging the package itself.
+   - The turnkey server's audience (end users who `npx @event4u/agent-config
+     mcp-server` for zero-setup client config) is served better by direct
+     per-IDE config snippets (`docs/setup/mcp-client-config.md`,
+     `docs/getting-started-local-stdio.md`) than by a registry listing that
+     would advertise a read-only, tool-less server next to the fuller
+     kernel listing under the same package name — a likely source of
+     consumer confusion ("why does the glama listing show tools I don't
+     get?").
+   - Glama's schema (`glama.ai/mcp/schemas/server.json`) supports exactly one
+     manifest field (`maintainers`); there is no per-listing scoping
+     mechanism to distinguish two servers from the same repo without a
+     second, separately-hosted manifest — not worth the maintenance surface
+     for a zero-tool server.
+3. **Revisit trigger.** Reopen this decision if either: (a) the turnkey
+   server gains tools (Phase 6 of this roadmap may bundle the kernel tool
+   surface into the npm package, per the ADR-085 revisit), making its
+   capability shape worth discovering separately; or (b) a named consumer
+   asks to discover the turnkey server via a registry specifically (not
+   just via npm/README).
+
+## Consequences
+
+- No glama configuration change required by this roadmap.
+- `docs/mcp-registries.md` and `docs/setup/mcp-client-config.md` document
+  both entry points, but only one (the kernel server) appears in the glama
+  registry — this asymmetry is intentional, not an oversight.
+- Official MCP-registry submission (Phase 2 Step 5 of this roadmap) is
+  free to list either or both servers, since that registry's schema is not
+  glama's single-manifest-per-repo constraint — evaluated separately.
+
+## Alternatives
+
+- **List both as separate glama entries.** Rejected — no such thing as
+  "the second manifest field" in glama's schema for this repo; would need a
+  second cloned/forked registration, disproportionate for a read-only
+  zero-tool server.
+- **Drop the kernel listing, list only turnkey.** Rejected — the kernel
+  server's tool surface is the entire reason glama's introspection is
+  valuable here; a tool-less listing loses that value.
+
+## References
+
+- `road-to-glama-registry-listing.md` (archived) — original listing decision.
+- `road-to-mcp-stdio-end-user-packaging.md` (archived) — turnkey server origin, ADR-085.
+- `agents/settings/contexts/mcp-tool-tier-map.md` — capability-shape evidence for both servers.
+- `internal/glama/README.md` — the build/run scripts this decision keeps unchanged.

package/docs/decisions/ADR-112-stdio-lite-stays-read-only.md

@@ -0,0 +1,92 @@
+---
+adr: 112
+status: accepted
+date: 2026-07-07
+decision: stdio-lite-stays-read-only
+supersedes: —
+superseded_by: —
+phase: road-to-mcp-full-power
+type: standing
+---
+
+# ADR-112 — the turnkey stdio-lite server stays read-only; tool users route to the kernel server
+
+## Status
+
+**Accepted** · 2026-07-07 · maintainer decision, Phase 6 of
+`road-to-mcp-full-power.md`. Resolves the ADR-085 revisit trigger
+("full-kernel bundling deferred — no demand"), which fired via this
+roadmap's named consumer ask.
+
+## Context
+
+ADR-085 shipped `agent-config mcp-server` (stdio-lite, `src/cli/mcp/`) as
+a read-only, zero-setup surface: prompts + resources from the bundled
+`dist/agent-src/` + `docs/guidelines/`, `tools/list` empty, execution
+deferred until demand existed. Demand now exists — but for the *kernel*
+server: Phases 4–5 of this roadmap shipped 18 implemented tools
+(write-tier + one shell-exec pilot) on `src/scripts/mcp_server/`, all
+requiring a repo checkout and the full script tree
+(`src/agent-src/scripts/`, `src/scripts/_cli/`, the council pricing
+stack, the exec safety envelope).
+
+The A1 option (bundle the kernel tool surface into the npm package so
+`agent-config mcp-server` gains tools) was re-evaluated against that
+shipped reality.
+
+## Decision
+
+1. **Stdio-lite stays read-only.** `agent-config mcp-server` keeps its
+   ADR-085 shape: prompts + resources, zero tools, zero setup. No kernel
+   bundling.
+2. **Tool users route to the kernel server** (`agent-config mcp:run` on a
+   repo checkout). The per-IDE docs present this as the explicit
+   trade-off: zero-setup content surface vs. checkout-required execution
+   surface.
+3. **Rationale:**
+   - The Phase 4/5 handlers import live repo modules (dashboard
+     regenerator, archival sweep, doctor/conformance internals, council
+     pricing, the exec envelope). Bundling them means shipping and
+     version-locking effectively the whole `src/` tree inside the npm
+     tarball — the "turnkey" story would inherit the kernel's full
+     dependency and drift surface while losing its one virtue:
+     nothing-to-break simplicity.
+   - The tools mutate the consumer's `agents/` tree and spawn vitest.
+     A zero-setup binary that writes and executes on first contact is
+     the wrong default posture for the entry-level surface; the kernel
+     path's checkout requirement is a natural consent step.
+   - Maintaining one execution surface (kernel) instead of two keeps the
+     A0 contract, the test suite, and the telemetry story single-homed.
+4. **Revisit trigger:** a named end-user ask for MCP tools *without* a
+   repo checkout (e.g. a Claude Desktop user who wants `memory_signal`
+   but will not clone). That reopens A1 as its own roadmap with a fresh
+   council round — not a silent scope creep on this ADR.
+
+## Consequences
+
+- `docs/setup/mcp-client-config.md`'s two-entry-point table stays
+  accurate as written (local turnkey = read-only content; tools =
+  kernel).
+- ADR-111 (Glama lists the kernel only) is reinforced — the listed
+  server is also the only tool-bearing one.
+- The Worker remains read-only per `docs/contracts/mcp-cloud-scope.md`;
+  nothing in this ADR changes cloud scope.
+
+## Alternatives
+
+- **A1 full-kernel bundling** — rejected above (dependency surface,
+  write/exec-by-default posture, dual maintenance).
+- **Partial bundling (read-only tools only in stdio-lite)** — rejected:
+  splits the tool catalog across two servers with different subsets,
+  making `implemented_on` client-visible behaviour diverge per entry
+  point; the discovery-first catalog would need a third transport
+  dimension for marginal gain.
+
+## References
+
+- ADR-085 — original stdio-lite shape (read-only, execution deferred).
+- ADR-111 — canonical Glama listing (kernel only).
+- `agents/decisions/mcp-write-exec-cut-2026-07-07.md` — the tool cut that
+  created the demand this ADR routes.
+- `docs/contracts/mcp-phase-1-scope.md` § Amendment — the execution
+  surface this decision keeps single-homed.