@event4u/agent-config 8.2.0 → 8.4.0

package/docs/decisions/ADR-113-ci-native-release-label-trigger.md

@@ -0,0 +1,201 @@
+---
+adr: 113
+status: accepted
+date: 2026-07-08
+decision: ci-native-release-label-trigger
+supersedes: —
+superseded_by: —
+phase: road-to-ci-native-release · Phase 1
+---
+
+# ADR-113 — CI-native release path, triggered by a `release` label on a merged PR
+
+## Status
+
+**Accepted** · 2026-07-08.
+
+## Context
+
+`task release` (`src/scripts/release.ts`) is a fully interactive, local
+9-step pipeline: preflight → plan → confirm → branch+bump → commit/push+PR →
+wait for CI → merge → tag → GitHub Release. The back half is already CI
+(`publish-npm.yml`, `cloud-release.yml`, `release-guard.yml` all trigger on
+the pushed numeric tag), but a maintainer must run the front half from a
+terminal. This ADR adds an unattended, CI-native entry point alongside
+`task release` — not a replacement.
+
+## Decision
+
+1. **Trigger: a `release` / `release:major` / `release:minor` /
+   `release:patch` label on a PR, checked at merge time**
+   (`pull_request: types: [closed]`, job-guarded on `merged == true` +
+   an exact label match). `release` auto-detects the bump from
+   Conventional Commits since the last tag (same logic `task release`
+   uses); the `release:*` variants force the bump. `workflow_dispatch`
+   (with `bump` / `version` / `dry_run` / `resume` inputs) is the
+   manual/recovery entry for a release not tied to a PR merge.
+
+2. **The numeric `X.Y.Z` tag stays the pipeline's *output*, never its
+   input.** `publish-npm.yml`, `cloud-release.yml`, and
+   `release-guard.yml` all trigger on `push: tags:
+   [0-9]+.[0-9]+.[0-9]+` and assume the tagged commit already carries
+   the bumped `package.json` / `marketplace.json` / regenerated
+   projections. A tag-shaped trigger (hand-pushed numeric tag, or a
+   `cut-*` intent tag) was considered and rejected — see Alternatives.
+
+3. **One orchestration workflow (`release.yml`), not a prepare/finalize
+   split.** GitHub's `GITHUB_TOKEN` recursion guard means events caused
+   by the default token do not start new workflow runs (with narrow,
+   documented exceptions — see the bot-PR finding below). A
+   bot-auto-merged release PR would never trigger a separate
+   merge-listening "finalize" workflow. `release.yml` instead runs the
+   whole chain synchronously in one job, calling
+   `src/scripts/release.ts --ci` end-to-end — the exact same pipeline
+   `task release` runs locally, just non-interactively.
+
+4. **`release.ts` gains a `--ci` mode, not a rewrite.** `--ci` changes
+   exactly three things relative to the existing interactive path:
+   - the `gh`-auth preflight probe (`gh api repos/{slug} --jq .id`
+     instead of `gh api user --jq .login` — the default `GITHUB_TOKEN`
+     is an installation token and `gh api user` returns 403 for it even
+     when perfectly valid);
+   - a `nothing_to_release_ci` short-circuit (empty commits + no
+     explicit bump/version override → exit 0) so firing the label path
+     twice in a row is a clean no-op, not a spurious empty release;
+   - explicit post-release dispatch of `release-guard.yml`,
+     `publish-npm.yml`, and `cloud-release.yml` via their `tag` input,
+     because a `GITHUB_TOKEN`-pushed tag does not fire their
+     `push: tags:` trigger either.
+
+   Every other code path (bump inference, changelog-era rendering, the
+   10-step `execute()` sequence, all idempotent-resume probes) is
+   shared, unmodified, between `task release` and `release.yml`.
+
+5. **Token: `secrets.RELEASE_PR_TOKEN` with a `GITHUB_TOKEN` fallback.**
+   `release.yml` uses `${{ secrets.RELEASE_PR_TOKEN || secrets.GITHUB_TOKEN
+   }}` for checkout, git push, and `gh` auth. See the bot-PR-approval
+   finding below for why this matters and why the fallback is safe to
+   ship without the secret configured.
+
+## Finding — bot-created PRs need a manual "Approve workflows to run" click (no PAT)
+
+Verified against GitHub's own changelog and community docs (2026-06-11,
+["Bot-created pull requests can run workflows if
+approved"](https://github.blog/changelog/2026-06-11-bot-created-pull-requests-can-run-workflows-if-approved/)):
+when a workflow uses the default `GITHUB_TOKEN` to open or update a PR,
+the resulting `pull_request` events (`opened` / `synchronize` /
+`reopened`) DO create workflow runs for other `pull_request`-triggered
+workflows — but those runs sit in an **approval-required** state until a
+repo collaborator with write access clicks **Approve workflows to run**
+in the PR's merge box. This is a deliberate GitHub security control
+(distinct from, but related to, the fork-first-time-contributor approval
+gate), not a bug in this design.
+
+This repo's branch-protection ruleset (verified live via `gh api
+repos/event4u-app/agent-config/rulesets/17749383`) requires
+**zero** approving reviews (`required_approving_review_count: 0`) and
+exactly **one** required status check, `Sync + Generate Tools
+Consistency` (from `consistency.yml`, `pull_request`-triggered). That
+check does not run automatically on a `GITHUB_TOKEN`-opened release PR
+without the one-time approval click — so without `RELEASE_PR_TOKEN`, a
+release via the label path pauses at "waiting for checks" until a
+maintainer approves the run once per release.
+
+**Accepted as the default**, not worked around, because:
+
+- It requires zero new secrets and zero change to repo-wide security
+  settings (disabling the org-wide first-time-contributor approval
+  setting would lower security posture for every fork/bot PR, not just
+  release PRs — out of proportion to this problem).
+- A release is a production action; per this repo's own engineering
+  safety floor (`engineering-safety-floor` rule) and Hard-Floor stance
+  on deploys, a single human checkpoint before a release's own CI even
+  runs is arguably a feature, not friction.
+- `RELEASE_PR_TOKEN` (a fine-grained PAT or GitHub App installation
+  token with `contents: write` + `pull-requests: write` on this repo)
+  removes the approval requirement entirely — documented as the
+  zero-friction upgrade path in `release.yml`'s header comment. Adding
+  it is a maintainer action, not part of this ADR.
+
+## Verified facts (not assumed)
+
+- Branch protection ruleset `main protection` (id `17749383`):
+  `required_approving_review_count: 0`; required check =
+  `Sync + Generate Tools Consistency`; `bypass_actors` includes a
+  repository-role bypass. No human-review gate blocks a bot merge once
+  checks are green.
+- `consistency.yml` triggers on `pull_request` with path filters that
+  match every file a release PR touches (`package.json`,
+  `.claude-plugin/marketplace.json`, `CHANGELOG.md`, `dist/agent-src/**`,
+  `.augment/**`) — the required check fires (subject to the approval
+  gate above), it is not silently skipped.
+- No `RELEASE_PR_TOKEN`-shaped secret exists in the repo today (`gh
+  secret list`) — the fallback path is the one that ships by default.
+- `softprops/action-gh-release@v2`'s `overwrite_files` input defaults to
+  `true` — re-attaching the same-named cloud-release assets on a
+  dispatch-chain re-run is idempotent by construction, no extra guard
+  needed.
+- `npm publish` hard-rejects re-publishing an existing version — added a
+  `npm view @event4u/agent-config@<tag> version` pre-check to
+  `publish-npm.yml` so a double-dispatch (native tag-push trigger racing
+  the explicit dispatch, when `RELEASE_PR_TOKEN` IS configured) is a
+  clean skip, not a red run.
+
+## Consequences
+
+- Releasing needs exactly one human action: label a PR `release` (or a
+  `release:*` variant) and merge it. Without `RELEASE_PR_TOKEN`, one
+  additional "Approve workflows to run" click is needed once per
+  release on the auto-created release PR.
+- `task release` is unaffected — same script, same flags, same tests.
+  It remains the interactive/local path and the documented fallback if
+  the CI path misbehaves.
+- Three existing workflows (`release-guard.yml`, `publish-npm.yml`)
+  gained a `workflow_dispatch` input / idempotency guard respectively;
+  `cloud-release.yml` needed no change (already idempotent).
+- A future maintainer who configures `RELEASE_PR_TOKEN` gets a fully
+  unattended release with zero code changes required — the fallback
+  expression already prefers it.
+
+## Alternatives considered
+
+- **Hand-pushed numeric tag as the trigger.** Rejected: the tag-triggered
+  workflows require the tagged commit to already carry the bump: a
+  hand-pushed `X.Y.Z` on plain main fires them against the *un-bumped*
+  tree (red `release-guard`, wrong npm tarball), and the tag would then
+  have to be deleted and re-pushed onto the eventual bump-PR merge
+  commit — mutable tags are an anti-pattern (stale fetches, npm
+  provenance binds to the tag commit).
+- **A `cut-*` intent tag** (`cut-X.Y.Z` / `cut-auto` / `cut-major` / …)
+  in a separate namespace from the numeric tags. Functionally workable
+  (does not collide with the publish/guard tag patterns), but the
+  release label keeps the intent visible on the PR itself — reviewable,
+  revocable pre-merge, no second git-tag vocabulary to teach.
+- **`workflow_dispatch` as the sole/primary trigger**, no label. Loses
+  the "the intent to release lives on the PR, and is revocable until
+  merge" property that the label gives for free; kept as the
+  manual/recovery entry, not the primary path.
+- **Prepare + finalize workflow split** (one workflow opens the release
+  PR, a second listens for its merge and finalizes). Needs a
+  `RELEASE_PR_TOKEN`-class token as a *hard* requirement — under plain
+  `GITHUB_TOKEN`, the bot-merged PR's `pull_request: closed` event is
+  the SAME kind of GITHUB_TOKEN-caused event subject to the same
+  approval/recursion nuance, and splitting the pipeline across two
+  workflow boundaries adds a second place idempotency can drift. The
+  single-workflow design collapses this into one synchronous run using
+  the already-battle-tested `execute()` sequence.
+- **Disable the org-wide "require approval for first-time contributors"
+  setting** to remove the bot-PR approval gate without a PAT. Rejected:
+  it is an org-wide security posture change affecting every fork/bot PR
+  in the organization, not scoped to releases — disproportionate to
+  this problem; `RELEASE_PR_TOKEN` is the properly-scoped fix.
+
+## References
+
+- `.github/workflows/release.yml` — the orchestration workflow.
+- `src/scripts/release.ts` — the shared pipeline (`--ci` mode).
+- `docs/contracts/release-pr-gating.md`,
+  `docs/contracts/branch-protection-policy.md` — release-PR shape and
+  required-check contracts this design must keep satisfying.
+- [GitHub Changelog — Bot-created pull requests can run workflows if
+  approved (2026-06-11)](https://github.blog/changelog/2026-06-11-bot-created-pull-requests-can-run-workflows-if-approved/)

package/docs/decisions/INDEX.md

@@ -114,6 +114,9 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-108](ADR-108-open-source-forever-no-commercial-tier.md) | Open Source Forever No Commercial Tier | accepted | 2026-06-24 | — |
 | [ADR-109](ADR-109-subagent-v1-contract.md) | Subagent V1 Contract | accepted | 2026-07-04 | — |
 | [ADR-110](ADR-110-discipline-profile-resolution-locus.md) | Discipline Profile Resolution Locus | accepted | 2026-07-07 | — |
+| [ADR-111](ADR-111-canonical-glama-listing.md) | Canonical Glama Listing | accepted | 2026-07-07 | — |
+| [ADR-112](ADR-112-stdio-lite-stays-read-only.md) | Stdio Lite Stays Read Only | accepted | 2026-07-07 | — |
+| [ADR-113](ADR-113-ci-native-release-label-trigger.md) | Ci Native Release Label Trigger | accepted | 2026-07-08 | — |
 | [ADR-200](ADR-200-python-to-typescript-migration.md) | Python To Typescript Migration | accepted | 2026-06-11 | — |
 
 ## Unnumbered (legacy)

package/docs/distribution/registry-submissions.md

@@ -34,7 +34,7 @@ the submission shape evolves; this file accumulates history.
 
 | # | Registry | Submission shape | Status | PR / form URL | Date | Maintainer notes |
 |---|---|---|---|---|---|---|
-| 1 | `punkpeye/awesome-mcp-servers` | One-line entry under agent-tooling section; PR via `scripts/mcp_registry_submit.sh` | `pending` | — | — | Scaffold ready. Run `bash scripts/mcp_registry_submit.sh --dry-run` once before live; the live path needs the maintainer's GitHub identity. |
+| 1 | `punkpeye/awesome-mcp-servers` | One-line entry under agent-tooling section; PR via `scripts/mcp_registry_submit.sh` | `submitted` | <https://github.com/punkpeye/awesome-mcp-servers/pull/9607> | 2026-07-07 | PR opened via the submit script (two script bugs fixed on the way: idempotent upstream remote, `--head OWNER:branch` format). Awaiting upstream review. |
 | 2 | `mcp.so` | Directory form submission (web form, no programmatic API) | `pending` | — | — | Form URL: <https://mcp.so/>. Submission shape: same one-line entry, paste into the form's `description` field. |
 | 3 | `mcpservers.org` | Directory form submission (web form, verify URL at submission time) | `pending` | — | — | Form URL: <https://mcpservers.org/>. Submission shape: one-line entry; check the site is live before posting. |
 

package/docs/getting-started.md

@@ -37,16 +37,18 @@ The suite is global-only (ADR-020) — refresh the global install and every
 project sees the new skills, rules, and hooks at once, no per-repo bump:
 
 ```bash
-agent-config upgrade            # fetch + install the latest globally (binary + plugin)
-agent-config refresh --global   # idempotent re-install, same version (root + plugin)
+agent-config upgrade            # fetch + install the latest globally (content + hooks)
+agent-config refresh --global   # idempotent re-install, same version
 agent-config refresh --project  # refresh a project's minimal surface — bridge
                                 # marker, agents/overrides/, .gitignore (no wizard)
-agent-config doctor             # PATH, binary↔plugin version drift, bridge presence
+agent-config doctor             # PATH, hook wiring, duplicate surfaces, bridge presence
 ```
 
-The Claude marketplace plugin updates on Claude Code's own cadence,
-independent of npm; `doctor` surfaces binary↔plugin drift so you know when to
-update the plugin from the marketplace.
+Claude Code is single-surface: the file projection carries content AND the
+managed hooks in `~/.claude/settings.json` — there is no marketplace plugin
+to keep in sync anymore. A leftover plugin from an older install is flagged
+by `doctor` as `claude-plugin: duplicate surface` (fix:
+`claude plugin uninstall agent-config@event4u-agent-config`).
 
 ## Project CLI — `./agent-config`
 

package/docs/installation.md

@@ -413,25 +413,24 @@ This is additional to project-installed mode, not a replacement.
 auggie plugin install agent-config@event4u-agent-config
 ```
 
-### Claude Code
+### Claude Code — plugin deprecated (single-surface model)
 
-Two equivalent paths — pick whichever surface you're already in:
+**Do not install the marketplace plugin for Claude Code.** The npx/npm
+global install (`npx -y @event4u/agent-config init`) is the single supported
+surface: it deploys skills/commands/rules to `~/.claude/` **and** registers
+the deterministic hooks in a managed `~/.claude/settings.json` block. The
+plugin would only duplicate every skill/command listing while its git-SHA
+snapshot silently lags each release.
 
-```bash
-# From your shell (CLI)
-claude plugin install agent-config@event4u-agent-config
-```
+Already have the plugin from an earlier install?
 
-```text
-# From inside Claude Code (slash command)
-/plugin marketplace add event4u-app/agent-config
-/plugin install agent-config@event4u-agent-config
+```bash
+claude plugin uninstall agent-config@event4u-agent-config
 ```
 
-The slash-command path is the canonical Claude Code Plugin Marketplace
-flow ([reference](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces)).
-It pulls the repo via git-clone and reads the skills directly from
-`.claude/skills/` — no separate ZIP download.
+Hooks keep firing after removal (they live in `settings.json`, not the
+plugin); `agent-config doctor` verifies via the `hook-wiring` check and
+flags a leftover plugin as `claude-plugin: duplicate surface`.
 
 ### Copilot CLI
 

package/docs/mcp-server.md

@@ -1,6 +1,6 @@
 # MCP Server
 
-> Status: **experimental** — Phase 1 + 2 + 3 shipped. No `tools/*` primitive yet (Phase 4, deferred behind a design call). Promotion to **beta** is gated on the six criteria in [`docs/contracts/mcp-beta-criteria.md`](contracts/mcp-beta-criteria.md); current gate status: `./agent-config doctor --check mcp-beta-readiness` (Phase 3 of `road-to-surface-discipline.md`).
+> Status: **experimental** — read-only prompts + resources plus a growing `tools/*` surface (stub-by-default: every catalogued tool name resolves, unimplemented ones return a structured `not_implemented` envelope). Tool coverage and the write/exec unlock path are governed by [`agents/settings/contexts/mcp-coverage-strategy.md`](../agents/settings/contexts/mcp-coverage-strategy.md). Promotion to **beta** is gated on the six criteria in [`docs/contracts/mcp-beta-criteria.md`](contracts/mcp-beta-criteria.md); current gate status: `./agent-config doctor --check mcp-beta-readiness`.
 
 `agent-config` ships a built-in [Model Context Protocol](https://modelcontextprotocol.io)
 server that exposes the package's read-only governance surface to MCP-aware
@@ -20,22 +20,30 @@ coexist:
   [`docs/contracts/mcp-cloud-scope.md`](contracts/mcp-cloud-scope.md).
   Wire-parity-checked against the local stdio kernel on every release.
 
-The MCP server **never executes engine code, never writes files, never spawns
-shells**. It is a read-only instructional surface — see
-[`docs/contracts/mcp-phase-1-scope.md`](contracts/mcp-phase-1-scope.md).
+Every implemented tool is either read-only or writes only inside the
+consumer's project tree via a path-guard (`_validateInTreePath`) —
+[`docs/contracts/mcp-phase-1-scope.md`](contracts/mcp-phase-1-scope.md)
+is the scope contract; exec-tier tools (shell-spawning) and network-tier
+tools (billable) are gated behind
+[`agents/settings/contexts/mcp-coverage-strategy.md`](../agents/settings/contexts/mcp-coverage-strategy.md).
 
 ## What the server exposes
 
-| Primitive | URIs | Source | Count (this package) |
-|---|---|---|---|
-| `prompts/list` + `prompts/get` | `skill.<name>`, `command.<name>` | `dist/agent-src/skills/`, `dist/agent-src/commands/` | 174 skills + 104 commands |
-| `resources/list` + `resources/read` | `rule://<stem>` | `dist/agent-src/rules/` | 60 rules |
-| ↳ | `guideline://<relpath>` | `docs/guidelines/` | 69 guidelines |
-| ↳ | `context://<relpath>` | `dist/agent-src/contexts/` | 31 contexts |
+| Primitive | URIs | Source |
+|---|---|---|
+| `prompts/list` + `prompts/get` | `skill.<name>`, `command.<name>` | `dist/agent-src/skills/`, `dist/agent-src/commands/` |
+| `resources/list` + `resources/read` | `rule://<stem>` | `dist/agent-src/rules/` |
+| ↳ | `guideline://<relpath>` | `docs/guidelines/` |
+| ↳ | `context://<relpath>` | `dist/agent-src/contexts/` |
+| `tools/list` + `tools/call` | see [`agents/settings/contexts/mcp-tool-tier-map.md`](../agents/settings/contexts/mcp-tool-tier-map.md) for the full candidate surface | `src/scripts/mcp_server/consumer_tool_catalog.json` |
 
 All resources are served with `mimeType: text/markdown`. Pagination is
 cursor-based (default page size: 100). Hot-reload triggers automatically on
 file mtime changes — edit a rule, reissue `resources/list`, see the update.
+Exact prompt/resource/tool counts drift with every content change — the smoke
+test below reports the live numbers rather than a number pinned in prose.
+_Last verified boot (`task mcp:glama-test`, 2026-07-07): 430 prompts / 232
+resources / 27 tools (18 implemented, 9 stubs — post write/exec cut)._
 
 ## Setup — one-line install
 
@@ -60,10 +68,9 @@ task mcp:run            # maintainer / dev repo
 ./agent-config mcp:run  # consumer projects
 ```
 
-Both forms launch the TypeScript MCP server over stdio via `tsx`. Use these for
-
-(Claude Desktop, Cursor, Zed, Continue) launch the server themselves via
-the config snippets below.
+Both forms launch the TypeScript MCP server over stdio via `tsx`. Use these
+for a manual smoke test — MCP clients (Claude Desktop, Cursor, Zed, Continue)
+launch the server themselves via the config snippets below.
 
 ## Client configuration
 
@@ -140,8 +147,9 @@ boots cleanly:
 
 ```bash
 ./agent-config mcp:run < /dev/null
-# Expect stderr: "mcp-server: loaded N prompts (0 warnings)" and
-#                "mcp-server: loaded 160 resources (0 warnings)"
+# Expect stderr: "mcp-server: loaded N prompts (0 warnings)",
+#                "mcp-server: loaded N resources (0 warnings)", and
+#                "mcp-server: registered N tools (N implemented, N stubs): [...]"
 ```
 
 ## Troubleshooting
@@ -155,9 +163,13 @@ boots cleanly:
 ## Scope
 
 - **In scope:** read-only prompts + resources, pagination, hot-reload, stdio
-  transport, free-tier client compatibility.
-- **Out of scope (Phase 4+):** `tools/*` primitive, SSE / HTTP transport,
-  cloud distribution, signed payloads. Tracked in
-  [`agents/roadmaps/road-to-mcp-server.md`](../agents/roadmaps/road-to-mcp-server.md).
+  transport, free-tier client compatibility, a growing read-only and
+  in-tree-write `tools/*` surface (see
+  [`agents/settings/contexts/mcp-tool-tier-map.md`](../agents/settings/contexts/mcp-tool-tier-map.md)).
+- **Out of scope:** SSE / native HTTP transport for this server (the
+  Cloudflare Worker above is the HTTP bridge instead), shell-exec and
+  network-tier tools until the safety envelope in
+  [`agents/settings/contexts/mcp-coverage-strategy.md`](../agents/settings/contexts/mcp-coverage-strategy.md)
+  ships, signed payloads.
 
 ← [Architecture](architecture.md) · [MCP config generation (consumer side)](mcp.md)

package/docs/setup/mcp-cloud-endpoints.md

@@ -19,8 +19,15 @@ resources. `tools/list` returns two **deprecated stubs**
 successors; `tools/call` against either returns `isError=true`. No
 script execution, no FS access, no shell.
 
-Full power — the ~112 Python scripts (linters, audits, `task ci`,
-work-engine hooks) — requires the local install. See
+Full power — the implemented tool surface (18 tools as of the 2026-07-07
+write/exec cut: memory, roadmap, capabilities, doctor/conformance,
+telemetry, council-estimate, and the vitest `run_tests` pilot) — requires
+the **local kernel server** (`agent-config mcp:run` on a repo checkout).
+`implemented_on` stays `["stdio"]` for every execution tool, permanently:
+the Worker has no kernel runtime endpoint — it serves a release-pinned
+content snapshot from R2, so there is no process that could run the
+handlers, and the A0-cloud contract's no-execution boundary is a design
+invariant, not a backlog item. See
 [`../contracts/mcp-cloud-scope.md`](../contracts/mcp-cloud-scope.md)
 for the execution-safety boundary and the Phase-7-DEFERRED gate that
 governs any future tool restoration.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "8.2.0",
+    "version": "8.4.0",
     "description": "Universal AI Agent OS — audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,
@@ -56,7 +56,7 @@
     },
     "scripts": {
         "build:cli": "tsc -p tsconfig.json && chmod +x dist/cli/agent-config.js",
-        "build:install-bundle": "esbuild src/scripts/install.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/install/install.mjs",
+        "build:install-bundle": "esbuild src/scripts/install.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/install/install.mjs --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);\"",
         "build:ui": "vite build",
         "build:discovery": "./scripts-run src/scripts/build_discovery_manifest --write --strict",
         "build:mcp-manifest": "./scripts-run src/scripts/build_mcp_registry_manifest --write --strict",

package/src/config/surface-matrix.yml

@@ -0,0 +1,213 @@
+# Surface Matrix — machine-checked per-tool canonical-surface declarations.
+#
+# One entry per tool in install.ts::USER_SCOPE_PATHS (set equality enforced by
+# lint_surface_matrix). Consumed by:
+#   - `agent-config doctor` (surface-state check — flags duplicate surfaces)
+#   - `agent-config converge` (per-tool cleanup actions)
+#   - CI (src/scripts/lint_surface_matrix.ts — coverage + drift)
+# Contract: docs/contracts/surface-matrix.md
+#
+# Fields per tool:
+#   surface:     projection | plugin | bundles | export-only
+#                projection  = installer writes content files into the user
+#                              scope path; that projection is canonical
+#                plugin      = the tool's own plugin/marketplace channel is
+#                              canonical (no user-scope projection exists)
+#                bundles     = manual import artifacts (ZIPs); no filesystem
+#                              discovery convention
+#                export-only = a config/marker export; no content tree
+#   hooks:       managed-settings-block | settings-hooks-opt-in | plugin | none
+#   alternates:  legitimate secondary surfaces (NOT duplicates), with role
+#   duplicate:   the duplicate-surface definition — `detect` paths that, when
+#                ALL present, mean the tool has a duplicate content surface.
+#                Only tools with a defined duplicate class are checked by
+#                doctor/converge. `pending-evidence` documents a suspected but
+#                unverified class (never acted on).
+#   converge:    the consented cleanup action for the duplicate class
+#   notes:       provenance — where the classification comes from
+
+schema_version: 1
+
+tools:
+  claude-code:
+    surface: projection
+    scope_path: "~/.claude/"
+    hooks: managed-settings-block
+    alternates:
+      - id: marketplace-plugin
+        role: bootstrap-shim
+        detail: >-
+          hooks/hooks.json (byte-identical to the managed settings block, so
+          Claude Code dedupes) plus one install-pointer skill; zero content
+          skills by construction (lint_marketplace enforces).
+    duplicate:
+      description: >-
+        A pre-shim marketplace plugin snapshot (content skills) installed next
+        to the ~/.claude/ file projection — every skill/command lists twice
+        and the snapshot rots silently.
+      detect:
+        all_of:
+          - "~/.claude/skills"
+          - "~/.claude/plugins/cache/event4u-agent-config"
+    converge:
+      action: plugin-uninstall
+      command: "claude plugin uninstall agent-config@event4u-agent-config"
+      reaps:
+        - "~/.claude/plugins/cache/event4u-agent-config"
+    notes: >-
+      Single-surface decision (agents/settings/contexts/
+      claude-code-single-surface-decision.md); shim invariant verified via
+      scratch marketplace install, 2026-07-08.
+
+  augment:
+    surface: projection
+    scope_path: "~/.augment/"
+    hooks: settings-hooks-opt-in
+    alternates:
+      - id: augment-plugin
+        role: dormant
+        detail: >-
+          .augment-plugin/ manifest-only wrapper (source: "."). Marketplace
+          feature is account-gated ("Plugin marketplace feature is not
+          enabled for your account") — dual install unreproducible today.
+    duplicate:
+      pending_evidence: >-
+        Suspected duplicate class analogous to Claude Code IF Augment enables
+        the plugin marketplace broadly. NOT acted on — evidence gate
+        agents/settings/contexts/augment-surface-parity.md (2026-07-08) could
+        not reproduce; re-run the gate before defining detect paths.
+    notes: >-
+      Projection-primary on evidence. NO retirement move without a fresh
+      parity gate (roadmap Phase 0 rule).
+
+  copilot:
+    surface: plugin
+    scope_path: "~/.copilot/"
+    hooks: plugin
+    notes: >-
+      Plugin-primary by design — no user-scope content projection exists for
+      Copilot; the project bridge is .github/plugin/marketplace.json. The
+      plugin is the correct surface here, not a duplicate (council Q3,
+      2026-07-07). Do not "fix".
+
+  claude-desktop:
+    surface: bundles
+    scope_path: "~/Library/Application Support/Claude/"
+    hooks: none
+    notes: >-
+      Skill ZIPs imported manually via Customize → Skills; no filesystem
+      discovery, no plugin channel — no dual-surface class (Phase 0 survey).
+
+  cursor:
+    surface: projection
+    scope_path: "~/.cursor/"
+    hooks: none
+    notes: Plain projection (rules/commands/personas); no plugin channel.
+
+  windsurf:
+    surface: projection
+    scope_path: "~/.codeium/windsurf/"
+    hooks: none
+    notes: Plain projection (rules only); no plugin channel.
+
+  cline:
+    surface: projection
+    scope_path: "~/Documents/Cline/Rules/"
+    hooks: none
+    notes: Plain projection (rules only); no plugin channel.
+
+  gemini-cli:
+    surface: projection
+    scope_path: "~/.gemini/"
+    hooks: none
+    notes: Plain projection (skill bundle); no plugin channel (Phase 0 survey).
+
+  codex:
+    surface: projection
+    scope_path: "~/.codex/"
+    hooks: none
+    notes: Plain projection (skill bundle); no plugin channel (Phase 0 survey).
+
+  continue:
+    surface: projection
+    scope_path: "~/.continue/"
+    hooks: none
+    notes: Plain projection (skill bundle); no plugin channel (Phase 0 survey).
+
+  droid:
+    surface: projection
+    scope_path: "~/.factory/"
+    hooks: none
+    notes: Plain projection (skill bundle); no plugin channel (Phase 0 survey).
+
+  roocode:
+    surface: projection
+    scope_path: "~/.roo/"
+    hooks: none
+    notes: Plain projection (skill bundle); no plugin channel.
+
+  kilocode:
+    surface: projection
+    scope_path: "~/.kilocode/"
+    hooks: none
+    notes: Plain projection (skill bundle); no plugin channel.
+
+  kiro:
+    surface: projection
+    scope_path: "~/.kiro/"
+    hooks: none
+    notes: Plain projection (rules/steering/personas); no plugin channel.
+
+  qoder:
+    surface: projection
+    scope_path: "~/.qoder/"
+    hooks: none
+    notes: Plain projection (skill bundle); no plugin channel.
+
+  opencode:
+    surface: projection
+    scope_path: "~/.opencode/"
+    hooks: none
+    notes: Plain projection (skill bundle); no plugin channel.
+
+  trae:
+    surface: projection
+    scope_path: "~/.trae/"
+    hooks: none
+    notes: Plain projection (skill bundle); no plugin channel.
+
+  antigravity:
+    surface: projection
+    scope_path: "~/.agents/"
+    hooks: none
+    notes: Plain projection (skill bundle); no plugin channel.
+
+  codebuddy:
+    surface: projection
+    scope_path: "~/.codebuddy/"
+    hooks: none
+    notes: Plain projection (skill bundle); no plugin channel.
+
+  warp:
+    surface: projection
+    scope_path: "~/.warp/"
+    hooks: none
+    notes: Plain projection (skill bundle); no plugin channel.
+
+  aider:
+    surface: export-only
+    scope_path: "~/.aider.conf.yml"
+    hooks: none
+    notes: Config-file export; no content tree, no plugin channel (Phase 0 survey).
+
+  zed:
+    surface: export-only
+    scope_path: "~/.config/zed/"
+    hooks: none
+    notes: Export/marker only; no plugin channel (Phase 0 survey).
+
+  jetbrains:
+    surface: export-only
+    scope_path: "~/.config/JetBrains/"
+    hooks: none
+    notes: Export/marker only; no plugin channel (Phase 0 survey).