@event4u/agent-config 8.2.0 → 8.3.0

package/.claude-plugin/marketplace.json

@@ -5,8 +5,8 @@
     "email": "dev@event4u.app"
   },
   "metadata": {
-    "description": "Shared agent configuration — skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "8.2.0",
+    "description": "Shared agent configuration — skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI). DEPRECATED: install via `npx -y @event4u/agent-config init` instead — the file projection carries content AND hooks; this plugin remains only for existing installs during the migration window.",
+    "version": "8.3.0",
     "keywords": [
       "agent-config",
       "skills",
@@ -26,7 +26,7 @@
   "plugins": [
     {
       "name": "agent-config",
-      "description": "Full skill catalog — writing, reviewing, managing, and analyzing agent content, plus stack-specific skills for Laravel, PHP, Docker, AWS, Playwright, and more.",
+      "description": "Full skill catalog — writing, reviewing, managing, and analyzing agent content, plus stack-specific skills for Laravel, PHP, Docker, AWS, Playwright, and more. DEPRECATED: install via `npx -y @event4u/agent-config init` instead — the file projection carries content AND hooks; this plugin remains only for existing installs during the migration window.",
       "keywords": [
         "skills",
         "rules",

package/CHANGELOG.md

@@ -989,6 +989,44 @@ our recommendation order, not its support status.
 > that forces a new era split (`# Era: 8.2.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [8.3.0](https://github.com/event4u-app/agent-config/compare/8.2.0...8.3.0) (2026-07-08)
+
+### Features
+
+* **ci:** add release.yml — merge a `release`-labeled PR to cut a release ([742aa91](https://github.com/event4u-app/agent-config/commit/742aa91c8dc3686a1618291dd425efbc1a69ac13))
+* **release:** add --ci mode to release.ts for the label-triggered CI path ([2fc9db6](https://github.com/event4u-app/agent-config/commit/2fc9db6b98fa998a03e68c0e2ce676c40d63c6e8))
+* **mcp:** ship the run_tests shell-exec pilot under a compiled safety envelope ([598a8a4](https://github.com/event4u-app/agent-config/commit/598a8a49f05f5e9ebd4c0c531a5424f079eb16b6))
+* **guardrails:** hook-matrix single source, golden smoke, doctor-last upgrade step (Phase 4) ([d3ddd37](https://github.com/event4u-app/agent-config/commit/d3ddd37aa9f72dd65cebd54985e121d05a8bc0e6))
+* **mcp:** implement the 8 council-approved Phase 4 tools (17 implemented total) ([71f4074](https://github.com/event4u-app/agent-config/commit/71f4074b1b065dd455b361959322ae18c11e0d6d))
+* **doctor+docs:** plugin retirement — duplicate-surface/hook-wiring checks, migration flow, docs sweep (Phase 3) ([3f6234d](https://github.com/event4u-app/agent-config/commit/3f6234d82730d0210d72c5712ca49a84fb160c0e))
+* **upgrade:** register managed hooks on global deploy; decouple upgrade steps (Phase 2) ([9c06cdb](https://github.com/event4u-app/agent-config/commit/9c06cdba7622691ed8c6b175fbc0f32b975db311))
+* **install:** managed Claude hook registration in settings.json (Phase 1) ([f1a7644](https://github.com/event4u-app/agent-config/commit/f1a7644b89a4da1e67b95cf8dc15eda778f4dc67))
+
+### Bug Fixes
+
+* **scripts:** make upstream-remote wiring idempotent in mcp_registry_submit ([b1c5ee1](https://github.com/event4u-app/agent-config/commit/b1c5ee18105cc2845e66b3595743dfe673292f8c))
+* **roadmap:** correct mcp-cloud-endpoints doc path in Phase 6 step text ([65ab1d6](https://github.com/event4u-app/agent-config/commit/65ab1d6611edd63242b3f334c4233087975d45b0))
+* **ci:** static yaml import + createRequire banner; no unchecked step indexing ([98c71c0](https://github.com/event4u-app/agent-config/commit/98c71c0f88c5e696dd0b5d00ed0e6a38c48717a1))
+* **mcp:** use process.stdout.write instead of console.log in glama drift lint ([80b53fe](https://github.com/event4u-app/agent-config/commit/80b53fea3f52f486395ebb9a7ede4ea583014b55))
+* **mcp:** fix stale glama build docs and dead pycache artifacts ([ea1cece](https://github.com/event4u-app/agent-config/commit/ea1cece30c097846f3475ac51211a2854223cae8))
+* **install:** accept --no-ui in the bash orchestrator (unblocks upgrade) ([a519b34](https://github.com/event4u-app/agent-config/commit/a519b34f9618c5c165d0bcc5c6ea04d7ce141361))
+* **release:** era-split gate measures the post-release state the drift test sees ([572e6ce](https://github.com/event4u-app/agent-config/commit/572e6ce83b74d37112213cb790c3a07a1d4e0968))
+
+### Documentation
+
+* **release:** document the dual release path; fix stale release.py refs ([9ae0aee](https://github.com/event4u-app/agent-config/commit/9ae0aeed403376581d656b2682c6009694e9d1b1))
+* **adr:** ADR-113 — CI-native release, label trigger, bot-PR-approval finding ([7af715c](https://github.com/event4u-app/agent-config/commit/7af715cc0753fbb77facf904101c317f271863e1))
+* **mcp:** Phase 6 — ADR-112 stdio-lite verdict, cloud-scope note, fresh counts ([c6fe3ed](https://github.com/event4u-app/agent-config/commit/c6fe3ed07689b82ea349beb377bd4cf97ceddaca))
+* **context:** Phase 0 hook+agent parity findings — settings.json parity CONFIRMED ([b22bc38](https://github.com/event4u-app/agent-config/commit/b22bc38412d76315d4406f41fbd746a70952cdbb))
+* **roadmap:** add road-to-claude-code-single-surface (council 2026-07-07, Option B projection-primary) ([cb283c3](https://github.com/event4u-app/agent-config/commit/cb283c3c0dbc52f66337a30a8edb94e084caeda6))
+* **mcp:** resolve A0 amendment signoff, run council, record write/exec cut ([323def8](https://github.com/event4u-app/agent-config/commit/323def8c0692c26408791623374d28eee512686a))
+* **readme:** add troubleshooting section for install/upgrade failure modes ([ba33679](https://github.com/event4u-app/agent-config/commit/ba336790f6c8f8eac662e72ae2a408338b03b971))
+
+### Chores
+
+* **roadmap:** archive road-to-ci-native-release; spawn first-run follow-up ([1544c3c](https://github.com/event4u-app/agent-config/commit/1544c3c3773f1eded3e3037e4abf04f66d9e5900))
+* **mcp:** record registry submission, fix submit-script PR head, park roadmap to later/ ([1f8f49f](https://github.com/event4u-app/agent-config/commit/1f8f49f97d0e443141d53736beea59ea45e780e7))
+
 ## [8.2.0](https://github.com/event4u-app/agent-config/compare/8.1.0...8.2.0) (2026-07-07)
 
 ### Features

package/MIGRATION.md

@@ -1,3 +1,21 @@
+# Migrating off the Claude Code marketplace plugin (single-surface model)
+
+The marketplace plugin for Claude Code is deprecated. The npx/npm global
+install is the single surface: it deploys content to `~/.claude/` and
+registers the deterministic hooks in a managed `~/.claude/settings.json`
+block. If you installed the plugin in the past:
+
+```bash
+agent-config upgrade                                        # wires the managed hooks
+claude plugin uninstall agent-config@event4u-agent-config   # removes the duplicate surface
+```
+
+Then start a new Claude Code session. Nothing else changes: hooks keep
+firing (now from `settings.json`), skills/commands stop listing twice, and
+`agent-config doctor` verifies the end state (`hook-wiring` ok,
+`claude-plugin` no longer reporting a duplicate surface). Augment CLI and
+Copilot CLI plugins are unaffected.
+
 # Migrating to 6.0
 
 > Upgrading an existing install to the **6.0 experience-first** layout.

package/README.md

@@ -364,12 +364,21 @@ Three classes of install/runtime behaviour look like package bugs but are host-h
 
 | Tool | Install |
 |---|---|
-| **Augment CLI** · **Claude Code** · **Copilot CLI** | [Install →](docs/installation.md) — rules + skills + commands, marketplace-updated |
+| **Augment CLI** · **Copilot CLI** | [Install →](docs/installation.md) — rules + skills + commands, marketplace-updated |
+
+> **Claude Code: the marketplace plugin is deprecated** (single-surface
+> model). The npx/npm file projection now carries content **and** the
+> deterministic hooks (registered in a managed `~/.claude/settings.json`
+> block by `agent-config global` / `upgrade`), so the plugin only duplicates
+> skill/command listings while its git-SHA snapshot rots silently. Existing
+> installs: `claude plugin uninstall agent-config@event4u-agent-config` —
+> `agent-config doctor` flags the duplicate surface.
 
 Keep the global install current with `agent-config upgrade` (latest) or
 `agent-config refresh --global` (same-version re-install); `agent-config doctor`
-flags a missing-from-`PATH` binary or binary↔plugin version drift. See
-[getting-started § Keeping current](docs/getting-started.md#keeping-current).
+flags a missing-from-`PATH` binary or broken hook wiring. See
+[getting-started § Keeping current](docs/getting-started.md#keeping-current) ·
+[Troubleshooting](#troubleshooting).
 
 ### Cloud / Hosted-agent surfaces
 
@@ -442,6 +451,80 @@ Browse content: [all 166 commands](dist/agent-src/commands/) · [skills catalog]
 
 ---
 
+## Troubleshooting
+
+First stop for any install problem: `agent-config doctor` — it flags a
+missing-from-`PATH` binary, binary↔plugin version drift, stale orphans, and
+manifest issues, each with a one-line fix hint.
+
+### A new command / skill is missing in Claude Code after an upgrade
+
+Under the single-surface model, `agent-config upgrade` refreshes the
+`~/.claude/` file projection — that IS the content surface, so a fresh
+session picks the new commands up directly. If commands are still missing,
+the usual cause is a leftover **marketplace plugin**: it is a git-SHA
+snapshot that never moves with the npm upgrade, and it shadows nothing —
+it just lists everything twice while lagging behind. Remove it:
+
+```bash
+claude plugin uninstall agent-config@event4u-agent-config
+```
+
+Then start a **new** Claude Code session. `agent-config doctor` reports a
+leftover plugin as `claude-plugin: duplicate surface`; hooks are unaffected
+(they live in a managed `~/.claude/settings.json` block — verify with the
+`hook-wiring` check).
+
+### Skills / commands appear twice in Claude Code
+
+Same cause as above: the deprecated marketplace plugin is installed next to
+the `~/.claude/` file projection, so every skill lists plain **and**
+`agent-config:`-prefixed. Uninstall the plugin (command above) and start a
+new session.
+
+### `agent-config upgrade` fails with `Unknown argument: --no-ui`
+
+Known bug in 8.2.0: `upgrade` passed a `--no-ui` flag that the install
+orchestrator did not accept yet, so the run aborted early. Fixed on `main`;
+until the next release, work around it with:
+
+```bash
+AGENT_CONFIG_NO_UI=1 agent-config global   # refresh the global install, no wizard
+```
+
+### Upgrade was interrupted (Ctrl-C, wizard closed, step failed)
+
+Only the initial `npm install -g` hard-aborts an upgrade. Every later step
+(global re-deploy with hook registration, settings sync, wrapper + git-hook
+refresh) runs independently — a single failed step is reported in the
+end-of-run summary instead of silently skipping the rest. Re-run
+`agent-config upgrade` to converge, and use `agent-config doctor` to name
+anything left in a mixed state.
+
+### `agent-config: command not found` / hooks stopped firing
+
+Runtime hooks resolve the **global** binary on `PATH` — a project-local
+install alone is not enough for them. Reinstall the binary:
+
+```bash
+npm install -g @event4u/agent-config
+agent-config doctor   # verifies PATH + plugin wiring
+```
+
+### Project files look stale after a package update
+
+Project-local projections are only rewritten on an explicit refresh:
+
+```bash
+agent-config refresh             # re-apply the installed version to this project
+agent-config refresh --global    # same-version re-install of the global root
+```
+
+More per-version steps: [Migration](docs/MIGRATION.md) ·
+[getting-started § Keeping current](docs/getting-started.md#keeping-current).
+
+---
+
 ## Development
 
 Working on the package itself? Edit `src/` (the source of truth — `src/skills`, `src/rules`, `src/agent-src/`), regenerate trees:

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "8.2.0"
+agent_config_version: "8.3.0"
 
 # --- Project identity ---
 project:

package/dist/discovery/deprecation-report.md

@@ -1,6 +1,6 @@
 # Discovery — Deprecation Report
 
-- Generated: `2026-07-07T17:49:14Z`
+- Generated: `2026-07-08T05:11:12Z`
 - Deprecated artefacts: **0**
 
 _None. Tree is clean._

package/dist/discovery/discovery-manifest.json

@@ -12703,7 +12703,7 @@
       "reason": "scaffold template for ticket-bundle tickets (ADR-101); carries no runtime frontmatter — emit-tickets fills it in per ticket"
     }
   ],
-  "generated_at": "2026-07-07T17:49:14Z",
+  "generated_at": "2026-07-08T05:11:12Z",
   "packs": [
     {
       "artefact_count": 95,

package/dist/discovery/discovery-manifest.json.sha256

@@ -1 +1 @@
-c05ffa6acdbc37c03958938e24b594d44e05d694f8191e2dd6cb37b43feeb927  discovery-manifest.json
+bbf8a859d7617913d0ff170cc99c99654291ebc17892739f41c365ebbfcdba8a  discovery-manifest.json

package/dist/discovery/discovery-manifest.summary.md

@@ -1,6 +1,6 @@
 # Discovery Manifest — Summary
 
-- Generated: `2026-07-07T17:49:14Z`
+- Generated: `2026-07-08T05:11:12Z`
 - Scanner: `6f13c4a07cc0`
 - Artefacts: **527**
 - Unassigned: **0**

package/dist/discovery/orphan-report.md

@@ -1,6 +1,6 @@
 # Discovery — Orphan Report
 
-- Generated: `2026-07-07T17:49:14Z`
+- Generated: `2026-07-08T05:11:12Z`
 - Orphan artefacts: **0**
 
 > An orphan is an artefact whose declared pack has no other members.

package/dist/discovery/packs.json

@@ -1,6 +1,6 @@
 {
   "checksum": "sha256:1e7905dc4de76032d102a27f6a9d7f35cbed3297696fc57820e933ac171f251e",
-  "generated_at": "2026-07-07T17:49:14Z",
+  "generated_at": "2026-07-08T05:11:12Z",
   "packs": [
     {
       "always_on": false,

package/dist/discovery/trust-report.md

@@ -1,6 +1,6 @@
 # Discovery — Trust Report
 
-- Generated: `2026-07-07T17:49:14Z`
+- Generated: `2026-07-08T05:11:12Z`
 - Workspaces tracked: **10**
 - Human-review-required artefacts: **3**
 

package/dist/discovery/workspaces.json

@@ -1,6 +1,6 @@
 {
   "checksum": "sha256:1e7905dc4de76032d102a27f6a9d7f35cbed3297696fc57820e933ac171f251e",
-  "generated_at": "2026-07-07T17:49:14Z",
+  "generated_at": "2026-07-08T05:11:12Z",
   "scanner_version": "6f13c4a07cc0",
   "workspaces": [
     {