@event4u/agent-config 8.3.0 → 8.4.0

package/dist/mcp/registry-manifest.json

@@ -9,7 +9,7 @@
     "homepage": "https://github.com/event4u-app/agent-config#readme",
     "name": "@event4u/agent-config",
     "repository": "https://github.com/event4u-app/agent-config",
-    "version": "8.3.0"
+    "version": "8.4.0"
   },
   "registries": [
     {

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "8.3.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,

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).