@event4u/agent-config 8.2.0 → 8.3.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.3.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/scripts/_cli/cmd_doctor.ts

@@ -81,6 +81,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as YAML from 'yaml';
 
 import * as claude_plugin from '../_lib/claude_plugin.js';
+import * as claude_settings_hooks from '../_lib/claude_settings_hooks.js';
 import { _is_source_repo } from './cmd_refresh.js';
 import * as installed_lock from '../_lib/installed_lock.js';
 import * as installed_tools from '../_lib/installed_tools.js';
@@ -730,6 +731,7 @@ const CHECK_IDS = [
     'scope',
     'global-binary',
     'claude-plugin',
+    'hook-wiring',
     'stale-orphans',
     'manifest-integrity',
     'lockfile-freshness',
@@ -749,6 +751,7 @@ const GLOBAL_CHECK_IDS: ReadonlySet<string> = new Set([
     'scope',
     'global-binary',
     'claude-plugin',
+    'hook-wiring',
     'stale-orphans',
     'mcp-mode',
     'mcp-beta-readiness',
@@ -1005,12 +1008,14 @@ function lstripV(s: string): string {
 }
 
 /**
- * Claude Code plugin state. The plugin is OPTIONAL — the `~/.claude/` file
- * projection is a full install on its own — so a missing plugin is `ok`,
- * never a warning. What DOES warn is a stale installed plugin: Claude Code
- * pins the plugin to its install-time git SHA, so its command surface
- * silently lags every upgrade until `claude plugin update` runs
- * (`agent-config upgrade` now does that automatically).
+ * Claude Code plugin state under the single-surface model
+ * (road-to-claude-code-single-surface): the `~/.claude/` file projection is
+ * THE distribution surface for Claude Code — content, and hooks via the
+ * managed settings.json block. An installed marketplace plugin next to the
+ * projection is a **duplicate surface**: every skill/command lists twice
+ * and the plugin's SHA snapshot rots silently. That is `fail`, with the
+ * uninstall command as the fix (never uninstalled autonomously — the plugin
+ * is a user-owned surface).
  */
 function _check_claude_plugin(): Dict {
     const claude = shutilWhich('claude');
@@ -1027,11 +1032,27 @@ function _check_claude_plugin(): Dict {
             id: 'claude-plugin',
             status: 'ok',
             message:
-                'plugin not installed (optional — the ~/.claude/ file projection ' +
-                'already carries the full skill/command set)',
+                'plugin not installed (single-surface model — the ~/.claude/ file ' +
+                'projection carries content AND hooks)',
             remedy: '',
         };
     }
+    const projection = path.join(os.homedir(), '.claude', 'skills');
+    const projection_present = isDir(projection);
+    if (projection_present) {
+        return {
+            id: 'claude-plugin',
+            status: 'fail',
+            message:
+                'duplicate surface: the marketplace plugin AND the ~/.claude/ file ' +
+                'projection are both installed — every skill/command lists twice and ' +
+                'the plugin snapshot rots silently',
+            remedy:
+                `claude plugin uninstall ${claude_plugin.CLAUDE_PLUGIN_ID}@${claude_plugin.CLAUDE_MARKETPLACE_NAME} ` +
+                '(hooks stay — they are registered in ~/.claude/settings.json; ' +
+                'verify with the hook-wiring check)',
+        };
+    }
     const snapshot_v = lstripV(claude_plugin.claude_plugin_snapshot_version() || '');
     const binary_v = lstripV(_current_package_version() || '');
     if (snapshot_v && binary_v && snapshot_v !== binary_v) {
@@ -1046,9 +1067,86 @@ function _check_claude_plugin(): Dict {
     }
     return {
         id: 'claude-plugin',
-        status: 'ok',
-        message: `plugin installed${snapshot_v ? ` (snapshot ${snapshot_v})` : ''}`,
-        remedy: '',
+        status: 'warn',
+        message:
+            `plugin installed${snapshot_v ? ` (snapshot ${snapshot_v})` : ''} without the ` +
+            'file projection — deprecated surface; the projection is the supported path',
+        remedy: 'agent-config global (then uninstall the plugin per the printed hint)',
+    };
+}
+
+/**
+ * Managed hook wiring (single-surface model): the deterministic hook matrix
+ * must be registered in ~/.claude/settings.json AND the dispatch target
+ * (`agent-config` binary) must resolve on PATH. Both halves are required —
+ * hooks without a binary silently no-op every session.
+ */
+function _check_hook_wiring(): Dict {
+    const claude = shutilWhich('claude');
+    if (claude === null) {
+        return {
+            id: 'hook-wiring',
+            status: 'skipped',
+            message: 'Claude Code CLI not on PATH — hook-wiring check not applicable',
+            remedy: '',
+        };
+    }
+    const settings_path = path.join(os.homedir(), '.claude', 'settings.json');
+    let missing: string[];
+    try {
+        const matrix = claude_settings_hooks.build_claude_hook_matrix(
+            path.join(_package_root(), 'src', 'scripts', 'hook_manifest.yaml'),
+        );
+        const settings = pathExists(settings_path)
+            ? (JSON.parse(fs.readFileSync(settings_path, 'utf8')) as Record<string, unknown>)
+            : {};
+        const hooks = ((settings['hooks'] ?? {}) as Record<string, unknown>) || {};
+        missing = Object.keys(matrix).filter((ev) => {
+            const groups = hooks[ev];
+            if (!Array.isArray(groups)) return true;
+            return !JSON.stringify(groups).includes(claude_settings_hooks.MANAGED_SIGNATURE);
+        });
+    } catch (e) {
+        return {
+            id: 'hook-wiring',
+            status: 'fail',
+            message: `cannot evaluate managed hooks: ${String(e)}`,
+            remedy: 'fix ~/.claude/settings.json (invalid JSON?), then agent-config refresh --global',
+        };
+    }
+    const binary_ok = shutilWhich('agent-config') !== null;
+    if (missing.length === 0 && binary_ok) {
+        return {
+            id: 'hook-wiring',
+            status: 'ok',
+            message: 'managed hooks registered in ~/.claude/settings.json; dispatch binary on PATH',
+            remedy: '',
+        };
+    }
+    if (missing.length > 0 && claude_plugin.claude_plugin_installed()) {
+        return {
+            id: 'hook-wiring',
+            status: 'warn',
+            message:
+                `managed hooks missing for: ${missing.join(', ')} — currently carried by the ` +
+                'installed plugin (deprecated surface)',
+            remedy: 'agent-config refresh --global (writes the managed settings.json block)',
+        };
+    }
+    const parts: string[] = [];
+    if (missing.length > 0) parts.push(`managed hooks missing for: ${missing.join(', ')}`);
+    if (!binary_ok) parts.push('`agent-config` not on PATH (hooks would silently no-op)');
+    if (parts.length === 0) {
+        // hooks complete, binary missing was the only issue → covered above.
+        parts.push('`agent-config` not on PATH');
+    }
+    return {
+        id: 'hook-wiring',
+        status: 'fail',
+        message: parts.join('; '),
+        remedy: binary_ok
+            ? 'agent-config refresh --global'
+            : 'npm install -g @event4u/agent-config, then agent-config refresh --global',
     };
 }
 
@@ -1818,6 +1916,7 @@ function _run_checks(
         scope: () => _check_scope(project_root),
         'global-binary': () => _check_global_binary(project_root),
         'claude-plugin': _check_claude_plugin,
+        'hook-wiring': _check_hook_wiring,
         'stale-orphans': _check_stale_orphans,
         'manifest-integrity': () => _check_manifest_integrity(manifest),
         'lockfile-freshness': () => _check_lockfile_freshness(manifest),
@@ -1890,6 +1989,7 @@ function _run_checks_no_manifest(
         scope: () => _check_scope(project_root),
         'global-binary': () => _check_global_binary(project_root),
         'claude-plugin': _check_claude_plugin,
+        'hook-wiring': _check_hook_wiring,
         'stale-orphans': _check_stale_orphans,
         'manifest-integrity': () => _skipped_manifest_check('manifest-integrity'),
         'lockfile-freshness': () => _skipped_manifest_check('lockfile-freshness'),

package/src/scripts/_cli/cmd_uninstall.ts

@@ -55,6 +55,7 @@
  */
 
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -62,6 +63,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as fs_atomic from '../_lib/fs_atomic.js';
 import * as installed_lock from '../_lib/installed_lock.js';
 import * as installed_tools from '../_lib/installed_tools.js';
+import { remove_managed_hooks } from '../_lib/claude_settings_hooks.js';
 import { resolve_project_root } from '../_lib/agent_settings.js';
 import { subtract_pointers } from '../_lib/json_pointers.js';
 import { PROJECT_BRIDGE_MARKERS, USER_SCOPE_PATHS } from '../install.js';
@@ -771,6 +773,26 @@ function _uninstall_global(opts: Options): number {
             removed_names.push(tool);
         }
     }
+    // Managed Claude hooks live in ~/.claude/settings.json (single-surface
+    // model) — remove exactly our entries, never user-owned ones.
+    if (tools.includes('claude-code')) {
+        const settings_path = path.join(os.homedir(), '.claude', 'settings.json');
+        if (opts.dry_run) {
+            _print(_stdout, `  · claude-code: would remove managed hooks from ${settings_path}`);
+        } else {
+            try {
+                const res = remove_managed_hooks(settings_path);
+                if (res.changed) {
+                    _print(
+                        _stdout,
+                        `  · claude-code: removed managed hooks (${res.events.join(', ')})`,
+                    );
+                }
+            } catch (e) {
+                _print(_stderr, `⚠️  claude-code: managed-hook removal skipped — ${String(e)}`);
+            }
+        }
+    }
     if (lock !== null && !opts.dry_run) {
         const remaining = (lock.tools ?? []).filter((t) => !tools.includes(t));
         const version = String((lock as unknown as AnyDict)['agent_config_version'] ?? '');