@event4u/agent-config 4.7.2 → 4.8.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "4.7.2",
+    "version": "4.8.0",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -802,6 +802,30 @@ our recommendation order, not its support status.
 > that forces a new era split (`# Era: 4.6.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [4.8.0](https://github.com/event4u-app/agent-config/compare/4.7.2...4.8.0) (2026-05-28)
+
+### Features
+
+* **install:** close Claude Code global distribution gap ([aa15db9](https://github.com/event4u-app/agent-config/commit/aa15db9651c4fd21f8bd30ef88e3aeeb1eb31e22))
+
+### Bug Fixes
+
+* **maintainer:** align .claude/settings.json plugin id ([b59e080](https://github.com/event4u-app/agent-config/commit/b59e0804e874e9c7c95cfc821a31746e4241f61c))
+
+### Documentation
+
+* **adr:** record claude-code command-projection strategy (ADR-030) ([706dedb](https://github.com/event4u-app/agent-config/commit/706dedb54f5792a2cf5b7c2401054b30490edeec))
+
+### Tests
+
+* **install:** regression coverage for global distribution heal ([bfdbc90](https://github.com/event4u-app/agent-config/commit/bfdbc9053d9032ffd10248835ba03f276631c7b3))
+
+### Chores
+
+* gitignore install-time artefacts in maintainer repo ([d75aeac](https://github.com/event4u-app/agent-config/commit/d75aeac4ed8858d2cddc7e3534eeff6bfb1ab036))
+
+Tests: 5078 (+14 since 4.7.2)
+
 ## [4.7.2](https://github.com/event4u-app/agent-config/compare/4.7.1...4.7.2) (2026-05-28)
 
 ### Bug Fixes

package/dist/discovery/deprecation-report.md

@@ -1,6 +1,6 @@
 # Discovery — Deprecation Report
 
-- Generated: `2026-05-28T06:18:52Z`
+- Generated: `2026-05-28T11:41:20Z`
 - Deprecated artefacts: **0**
 
 _None. Tree is clean._

package/dist/discovery/discovery-manifest.json

@@ -9543,7 +9543,7 @@
       "reason": "scaffold for new SKILL.md authoring"
     }
   ],
-  "generated_at": "2026-05-28T06:18:52Z",
+  "generated_at": "2026-05-28T11:41:20Z",
   "packs": [
     {
       "artefact_count": 84,

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

@@ -1 +1 @@
-b1be210896960f4ef344298e27481e6fc8b98055d6694aa89ad2184e4d4c4e26  discovery-manifest.json
+ebdbb29d37f2509c6098a29419ece7ba11030a5709468b1be49bcd3ad42e90e6  discovery-manifest.json

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

@@ -1,6 +1,6 @@
 # Discovery Manifest — Summary
 
-- Generated: `2026-05-28T06:18:52Z`
+- Generated: `2026-05-28T11:41:20Z`
 - Scanner: `d75eba636abb`
 - Artefacts: **432**
 - Unassigned: **0**

package/dist/discovery/orphan-report.md

@@ -1,6 +1,6 @@
 # Discovery — Orphan Report
 
-- Generated: `2026-05-28T06:18:52Z`
+- Generated: `2026-05-28T11:41:20Z`
 - 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:eb7494e53428947d792e0377cb59e043457819ad3fff0b7ff6bc1011134be766",
-  "generated_at": "2026-05-28T06:18:52Z",
+  "generated_at": "2026-05-28T11:41:20Z",
   "packs": [
     {
       "artefact_count": 84,

package/dist/discovery/trust-report.md

@@ -1,6 +1,6 @@
 # Discovery — Trust Report
 
-- Generated: `2026-05-28T06:18:52Z`
+- Generated: `2026-05-28T11:41:20Z`
 - Workspaces tracked: **8**
 - Human-review-required artefacts: **2**
 

package/dist/discovery/workspaces.json

@@ -1,6 +1,6 @@
 {
   "checksum": "sha256:eb7494e53428947d792e0377cb59e043457819ad3fff0b7ff6bc1011134be766",
-  "generated_at": "2026-05-28T06:18:52Z",
+  "generated_at": "2026-05-28T11:41:20Z",
   "scanner_version": "d75eba636abb",
   "workspaces": [
     {

package/dist/install/wizard-plan.js

@@ -62,6 +62,14 @@ export const USER_SCOPE_PATHS = {
 const CLAUDE_SKILL_BUNDLE = [
     ['.agent-src/rules', 'rules'],
     ['.agent-src/skills', 'skills'],
+    // Commands ship to ~/.claude/commands/ — native Claude Code slash-
+    // command surface. Verified empirically 2026-05-28: rich frontmatter
+    // (disable-model-invocation, custom fields) tolerated; nested
+    // subdirs route as `/<cluster>:<sub>`. Council session 2026-05-28
+    // converged on Option B (native slash-only) — see
+    // agents/runtime/council/responses/claude-code-distribution.json
+    // and scripts/install.py:_CLAUDE_SKILL_BUNDLE for the Python mirror.
+    ['.agent-src/commands', 'commands'],
     ['.agent-src/personas', 'personas'],
 ];
 /**

package/dist/install/wizard-plan.js.map

@@ -1 +1 @@
-{"version":3,"file":"wizard-plan.js","sourceRoot":"","sources":["../../src/install/wizard-plan.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wizard-plan.js","sourceRoot":"","sources":["../../src/install/wizard-plan.ts"],"names":[],"mappings":"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"}

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": "4.7.2"
+    "version": "4.8.0"
   },
   "registries": [
     {

package/docs/decisions/ADR-030-claude-code-command-projection.md

@@ -0,0 +1,147 @@
+---
+adr: 030
+status: accepted
+date: 2026-05-28
+decision: claude-code-command-projection
+supersedes: —
+superseded_by: —
+phase: road-to-claude-code-global-distribution Phase 3
+type: structural
+review_date: 2026-06-11
+---
+
+# ADR-030 — Claude Code command-projection strategy: native slash-only
+
+## Status
+
+**Accepted** · 2026-05-28. Three conditions enumerated below; all three
+verified empirically in the same session, so the decision lands
+**without** soak. The 14-day kill-switch keeps the revert path one
+commit away; review date 2026-06-11 closes the window.
+
+## Context
+
+The package ships commands as `.agent-src/commands/<cluster>/<sub>.md`
+(canonical source) and projects them per-tool through
+`scripts/condense.py`. Pre-2026-05-28 the Claude Code projection was a
+single path: `generate_claude_commands` rewrote each command into
+`.claude/skills/<flat-slug>/SKILL.md` with
+`disable-model-invocation: true` in the source frontmatter.
+
+The 2026-05-28 diagnostic surfaced the failure mode:
+
+- `.claude/commands/` was never populated — commands carried no
+  filesystem channel into Claude Code's native slash router.
+- The skills-projection target was filtered out of the
+  model-invokable skill list (`disable-model-invocation: true`).
+- `_CLAUDE_SKILL_BUNDLE` shipped `rules` / `skills` / `personas` but
+  **no** `commands` subtree.
+
+Net result: Claude Code received zero command surface from the package
+outside the cwd-local repo install. Augment Code and Cursor bundles
+already shipped `commands/`; Claude Code was the outlier.
+
+## Decision
+
+Adopt **Option B (native slash-only)**:
+
+1. Ship `.agent-src/commands/` directly into Claude Code's native
+   slash-command surface at `~/.claude/commands/` via the global
+   deploy bundle (`_CLAUDE_SKILL_BUNDLE` in `scripts/install.py` and
+   its TypeScript mirror in `src/install/wizard-plan.ts`).
+   Subdirectory layout maps 1:1 to the `/<cluster>:<sub>` namespace
+   per Claude Code's filesystem-channel convention. No separate
+   `condense.py` projector — the source tree already follows the
+   target layout, so the global-install copy is the projection.
+2. Keep `condense.py::generate_claude_commands` (skills-list
+   projection at `.claude/skills/`) unchanged **for now** —
+   backwards compat for any consumer already discovering commands
+   via `.claude/skills/`. Retirement deferred to a separate roadmap
+   if needed.
+
+Rejected alternatives:
+
+- **Option A — dual projection (slash + skills, both active).**
+  Conservative, but doubles maintenance surface and keeps the
+  filter-out-of-skill-list semantics. Verdict: only useful if Option B
+  fails the kill-switch window.
+- **Option C — commands_unsupported (no Claude Code command
+  surface).** Eliminates the bug class by removing the feature.
+  Verdict: regression in product surface; Claude Code consumers lose
+  parity with Augment / Cursor.
+
+### Council convergence
+
+Session 2026-05-28, design mode, 2 rounds, $0.06 actual.
+Members: `claude-sonnet-4-5` + `gpt-4o`. Both converged on Option B,
+CONDITIONAL on the three verifications below. Responses captured at
+`agents/runtime/council/responses/claude-code-distribution.json`.
+
+### Three conditions (all verified 2026-05-28)
+
+1. **Plugin loader reads `.claude/commands/` for globally-installed
+   plugins (not just cwd-local).**
+   Verified empirically: `~/.claude/commands/probe/sub.md` →
+   `/probe:sub` routed successfully via
+   `echo '' | claude --print "/probe:sub"`. Native filesystem channel
+   works for user-scope at top-level AND in subdirectories.
+2. **Command parser tolerates `disable-model-invocation: true` in
+   frontmatter (or strip during projection).**
+   Verified empirically: probe command carrying the package's full
+   rich frontmatter routed successfully. Subtle behaviour:
+   `disable-model-invocation: true` hides the command from `/help`
+   listing but keeps it slash-invokable when typed directly — the
+   desired UX for heavyweight commands. No frontmatter-strip step
+   required.
+3. **Kill-switch defined: if native slash doesn't resolve in
+   production within 14 days, fall back to dual-projection with
+   deprecation timeline.**
+   The kill-switch is the inverse of Phase 4 Step 1 — remove
+   `(".agent-src/commands", "commands")` from `_CLAUDE_SKILL_BUNDLE`
+   in `scripts/install.py` and `src/install/wizard-plan.ts`. One-line
+   revert per file. Tracked by review date 2026-06-11.
+
+## Consequences
+
+**Positive:**
+
+- `~/.claude/commands/<cluster>/<sub>.md` lands the package's full
+  command surface natively in Claude Code, matching Augment and
+  Cursor parity.
+- `disable-model-invocation: true` semantics preserved — heavyweight
+  commands stay invokable but hidden from auto-complete, the intended
+  UX.
+- No frontmatter mangling — the source command file is the artifact
+  that ships, no projection transform needed.
+
+**Negative / accepted:**
+
+- Two projection paths coexist (`.claude/commands/` for slash routing
+  + `.claude/skills/` for the legacy skills-projection list). Cost is
+  one extra subtree per install; benefit is no consumer-breaking
+  during the 14-day kill-switch window. Retirement of the skills
+  projection is a separate decision.
+- Frontmatter shipped to Claude Code carries package-internal fields
+  (`tier`, `cluster`, `sub`, `lifecycle`, `trust`, `install`, etc.)
+  the runtime ignores. Empirically tolerated; documented as
+  belt-and-braces against future runtime tightening.
+
+## Alternatives considered
+
+See § Decision above — Option A (dual projection) and Option C
+(commands_unsupported) explicitly rejected with stated rationale.
+
+## References
+
+- Roadmap:
+  `agents/roadmaps/road-to-claude-code-global-distribution.md` Phase 3.
+- Council session responses:
+  `agents/runtime/council/responses/claude-code-distribution.json`.
+- Empirical verification: `~/.claude/commands/probe/sub.md` route
+  test, 2026-05-28 (Condition 1 + Condition 2).
+- Mirror implementation: `scripts/install.py::_CLAUDE_SKILL_BUNDLE`
+  and `src/install/wizard-plan.ts::CLAUDE_SKILL_BUNDLE` — both
+  include `(".agent-src/commands", "commands")` so a global install
+  drops `~/.claude/commands/<cluster>/<sub>.md` directly.
+- Predecessor projection: `scripts/condense.py::generate_claude_commands`
+  (skills-list, retained pending separate retirement decision).

package/docs/decisions/INDEX.md

@@ -33,6 +33,7 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-027](ADR-027-changelog-machine-vs-manual.md) | Changelog Machine Vs Manual | accepted | 2026-05-25 | — |
 | [ADR-028](ADR-028-root-layout.md) | Root Layout | accepted | 2026-05-25 | — |
 | [ADR-029](ADR-029-multi-workspace-deferred.md) | Multi Workspace Deferred | accepted | 2026-05-25 | — |
+| [ADR-030](ADR-030-claude-code-command-projection.md) | Claude Code Command Projection | accepted | 2026-05-28 | — |
 
 ## Unnumbered (legacy)
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "4.7.2",
+    "version": "4.8.0",
     "description": "Universal AI Agent OS \u2014 audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/scripts/_lib/installed_lock.py

@@ -198,6 +198,50 @@ def check_version(
     return (recorded == installed_version, recorded)
 
 
+_SEMVER_RE = re.compile(r"^\s*v?(\d+)\.(\d+)\.(\d+)")
+
+
+def _parse_semver(version: str) -> Optional[tuple[int, int, int]]:
+    """Parse ``X.Y.Z[-suffix]`` into a ``(major, minor, patch)`` tuple.
+
+    Returns ``None`` when the leading three numeric segments cannot be
+    extracted. Suffixes (``-rc1``, ``+build.5``) are ignored: the
+    classification only needs the numeric prefix to decide upgrade vs
+    downgrade.
+    """
+    match = _SEMVER_RE.match(version)
+    if not match:
+        return None
+    return int(match.group(1)), int(match.group(2)), int(match.group(3))
+
+
+def classify_mismatch(
+    installed_version: str, recorded: Optional[str],
+) -> str:
+    """Classify the relationship between recorded and installed versions.
+
+    Returns one of:
+      * ``"none"``        — no lockfile yet; install proceeds clean.
+      * ``"match"``       — recorded equals installed.
+      * ``"upgrade"``     — recorded < installed; auto-heal allowed.
+      * ``"downgrade"``   — recorded > installed; refuse without ``--force``.
+      * ``"unparseable"`` — recorded shape unrecognizable (pre-1.0, 1.x
+        legacy formats from the namespace migration); treated as
+        upgrade by the install path.
+    """
+    if recorded is None:
+        return "none"
+    if recorded == installed_version:
+        return "match"
+    rec = _parse_semver(recorded)
+    inst = _parse_semver(installed_version)
+    if rec is None or inst is None:
+        return "unparseable"
+    if rec < inst:
+        return "upgrade"
+    return "downgrade"
+
+
 def current_package_version(repo_root: Optional[Path] = None) -> str:
     """Read ``version`` from the package's own ``package.json``."""
     if repo_root is None:

package/scripts/install.py

@@ -1083,6 +1083,49 @@ def ensure_augment_user_hooks(package_root: Path, force: bool) -> list[dict[str,
 # concern fires on the same logical surface across platforms — the
 # contract from agents/settings/contexts/hardening-pattern.md § Cross-platform
 # parity.
+# Canonical Claude Code plugin id — must match `.claude-plugin/marketplace.json`
+# (`<plugin>@<marketplace>` = `agent-config` + `event4u-agent-config`) and the
+# install command documented in `docs/installation.md`.
+CLAUDE_PLUGIN_ID = "agent-config@event4u-agent-config"
+
+# Stale plugin ids written by pre-4.x installer versions. The bridge removes
+# any of these from `enabledPlugins` on rerun so the canonical id alone
+# survives. Claude Code silently ignores unresolvable ids (no marketplace
+# match), so a stale entry leaves the plugin inactive without an error path
+# the user can see — the heal is the only feedback loop.
+CLAUDE_LEGACY_PLUGIN_IDS: tuple[str, ...] = (
+    "agent-conf@event4u",      # abbreviated form — never matched a real marketplace
+    "agent-config@event4u",    # pre-marketplace-rename form (missing `-agent-config` suffix)
+)
+
+
+def _heal_legacy_claude_plugin_ids(path: Path) -> list[str]:
+    """Remove known-stale plugin ids from `.claude/settings.json` in place.
+
+    Reads the existing settings file, drops any `enabledPlugins` key whose
+    id appears in `CLAUDE_LEGACY_PLUGIN_IDS`, and writes the file back
+    when anything changed. Returns the list of removed ids so the caller
+    can surface a `success(...)` per heal and treat the operation as a
+    forced refresh for the subsequent `merge_json_file` call.
+
+    No-ops when the file is absent, malformed, or carries no stale ids.
+    The canonical id is left untouched.
+    """
+    if not path.exists():
+        return []
+    data = read_json_file(path)
+    enabled = data.get("enabledPlugins")
+    if not isinstance(enabled, dict):
+        return []
+    removed = [pid for pid in CLAUDE_LEGACY_PLUGIN_IDS if pid in enabled]
+    if not removed:
+        return []
+    for pid in removed:
+        del enabled[pid]
+    write_json_file(path, data)
+    return removed
+
+
 def ensure_claude_bridge(project_root: Path, force: bool) -> list[dict[str, Any]]:
     """Deploy .claude/settings.json with plugin enablement only.
 
@@ -1099,12 +1142,22 @@ def ensure_claude_bridge(project_root: Path, force: bool) -> list[dict[str, Any]
     documented install command in docs/installation.md. Idempotent:
     `enabledPlugins` is a dict-merge, so the key coexists with any other
     plugin a neighbour tool enabled.
+
+    Stale-id heal: before the merge, any pre-4.x ids listed in
+    `CLAUDE_LEGACY_PLUGIN_IDS` are removed from `enabledPlugins`. A heal
+    self-authorises the corrective merge — the merge runs with effective
+    force so the canonical id lands in the same install, even without
+    `--force` on the CLI.
     """
+    target = project_root / ".claude" / "settings.json"
+    healed = _heal_legacy_claude_plugin_ids(target)
+    for pid in healed:
+        success(f".claude/settings.json: removed stale plugin id `{pid}`")
     bridge = {
-        "enabledPlugins": {"agent-config@event4u-agent-config": True},
+        "enabledPlugins": {CLAUDE_PLUGIN_ID: True},
     }
     return merge_json_file(
-        project_root / ".claude" / "settings.json", bridge, force, ".claude/settings.json",
+        target, bridge, force or bool(healed), ".claude/settings.json",
     )
 
 
@@ -2215,6 +2268,17 @@ PROJECT_BRIDGE_MARKERS = {
 _CLAUDE_SKILL_BUNDLE: list[tuple[str, str]] = [
     (".agent-src/rules",    "rules"),
     (".agent-src/skills",   "skills"),
+    # Commands ship to the native Claude Code user-scope slash-command
+    # surface: `~/.claude/commands/<cluster>/<sub>.md` resolves as
+    # `/<cluster>:<sub>` per Claude Code's filesystem-channel convention
+    # (verified empirically 2026-05-28: top-level + nested + rich
+    # frontmatter all route; heavyweight commands carrying
+    # `disable-model-invocation: true` stay invokable when typed but are
+    # hidden from auto-complete — desired UX). Council session
+    # 2026-05-28 (claude-sonnet-4-5 + gpt-4o, design mode) verdict
+    # Option B (native slash-only). See
+    # `agents/runtime/council/responses/claude-code-distribution.json`.
+    (".agent-src/commands", "commands"),
     (".agent-src/personas", "personas"),
 ]
 GLOBAL_DEPLOY_SOURCES: dict[str, list[tuple[str, str]]] = {
@@ -2956,20 +3020,94 @@ MIGRATE_LEGACY_YAML_FILES = (".agent-settings.yml", ".agent-user.yml")
 MIGRATE_LEGACY_TOOL_DIRS = (".augment", ".claude", ".cursor")
 
 
+# Package identity used by the maintainer auto-detect. Matches the npm
+# package name declared in ``package.json`` at the agent-config source
+# repo root. Refreshing this value requires a coordinated rename
+# (package.json + this constant + the publish pipeline).
+AGENT_CONFIG_PACKAGE_NAME = "@event4u/agent-config"
+
+
+def _is_agent_config_source_repo(project_root: Path) -> tuple[bool, str]:
+    """Return ``(is_source_repo, signature)`` for the maintainer auto-detect.
+
+    Phase Q1 of road-to-claude-code-global-distribution (council Option D —
+    Hybrid auto-detect): treat any of these high-specificity signatures as
+    proof that ``project_root`` is the agent-config source repo, not a
+    consumer project. Hits skip the ADR-020 migration prompt automatically
+    so a maintainer running the wizard does not get their working tree
+    moved into ``.legacy-pre-global-only/``.
+
+    Signatures, in order of cost (cheap-first short-circuit):
+
+    1. ``package.json`` declares ``"name": "@event4u/agent-config"``.
+       Strongest signal — the npm-published identity of this repo.
+    2. ``.agent-src.uncondensed/`` exists at ``project_root`` (legacy
+       layout) OR under ``packages/*/`` (current layout). Both shapes
+       are unique to the source repo.
+    3. ``scripts/install.py`` exists at ``project_root`` AND the file
+       name matches this module (``__file__``). Self-referential — if
+       the installer code path is reading itself, the cwd is the repo
+       that owns the installer.
+
+    The user can force consumer behaviour via ``AGENT_CONFIG_CONSUMER_MODE=1``
+    when testing the wizard's consumer flow from inside the maintainer
+    checkout (end-to-end QA path).
+    """
+    if os.environ.get("AGENT_CONFIG_CONSUMER_MODE") == "1":
+        return False, "consumer-mode-override"
+
+    pkg_json = project_root / "package.json"
+    if pkg_json.is_file():
+        try:
+            data = json.loads(pkg_json.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            data = {}
+        if isinstance(data, dict) and data.get("name") == AGENT_CONFIG_PACKAGE_NAME:
+            return True, "package.json:name"
+
+    if (project_root / ".agent-src.uncondensed").is_dir():
+        return True, ".agent-src.uncondensed/"
+    packages_dir = project_root / "packages"
+    if packages_dir.is_dir():
+        for child in packages_dir.iterdir():
+            if (child / ".agent-src.uncondensed").is_dir():
+                return True, f"packages/{child.name}/.agent-src.uncondensed/"
+
+    installer_self = project_root / "scripts" / "install.py"
+    try:
+        if installer_self.is_file() and installer_self.resolve() == Path(__file__).resolve():
+            return True, "scripts/install.py (self)"
+    except OSError:
+        pass
+
+    return False, ""
+
+
 def _detect_legacy_for_migration(project_root: Path) -> list[str]:
     """Return a sorted list of legacy artefact relpaths present in ``project_root``.
 
     Skipped (returns ``[]``) when:
 
     - ``AGENT_CONFIG_DEV_MODE=1`` is set (maintainer dogfood loop),
-    - the project root IS the agent-config source repo
-      (``.agent-src.uncondensed/`` present),
+    - ``project_root`` IS the agent-config source repo per
+      :func:`_is_agent_config_source_repo` (council Option D auto-detect),
     - the bridge marker already exists (project is already global-only).
     """
     if os.environ.get("AGENT_CONFIG_DEV_MODE") == "1":
         return []
-    if (project_root / ".agent-src.uncondensed").is_dir():
+
+    is_source, signature = _is_agent_config_source_repo(project_root)
+    if is_source:
+        if not QUIET:
+            warn(
+                "Maintainer mode auto-detected — agent-config source repo "
+                f"(signature: {signature}). Skipping ADR-020 migration "
+                "prompt; the working tree stays intact. Set "
+                "AGENT_CONFIG_CONSUMER_MODE=1 to override for end-to-end "
+                "consumer-flow testing."
+            )
         return []
+
     if (project_root / CONSUMER_BRIDGE_MARKER_RELPATH).is_file():
         return []
 
@@ -3478,10 +3616,65 @@ def _deploy_global_content(
             written_total += w
             skipped_total += s
             written_paths.extend(paths)
+        # Phase 5 (road-to-claude-code-global-distribution): postcheck.
+        # Every entry in the deploy plan must end with the destination
+        # subpath populated — directory exists AND is non-empty. A
+        # silent partial deploy (no exception raised, no files written
+        # for one of the bundle entries) is the silent-failure class
+        # this phase exists to surface.
+        missing_targets = _verify_deploy_targets(anchor, plan)
+        if missing_targets:
+            if not QUIET:
+                warn(
+                    f"{tool_id}: deploy postcheck failed — "
+                    f"missing/empty: {', '.join(missing_targets)}"
+                )
+            _emit_progress({
+                "type": "verify_failed",
+                "tool": tool_id,
+                "missing": missing_targets,
+            })
+            results[tool_id] = (
+                written_total, skipped_total, "deploy_failed", written_paths,
+            )
+            continue
+        _emit_progress({"type": "verified", "tool": tool_id})
         results[tool_id] = (written_total, skipped_total, "deployed", written_paths)
     return results
 
 
+def _verify_deploy_targets(
+    anchor: Path, plan: list[tuple[str, str]],
+) -> list[str]:
+    """Return the deploy-plan destination subpaths that did NOT materialise.
+
+    A deploy plan entry ``(src_rel, dest_sub)`` is verified by checking
+    that ``anchor / dest_sub`` (or ``anchor`` when ``dest_sub`` is empty)
+    exists as a directory AND contains at least one entry. An empty
+    directory counts as a failure — the agent-config bundle never
+    legitimately ships an empty subtree, so "empty after deploy" means
+    the copy step silently produced nothing.
+
+    Returns the list of failing ``dest_sub`` values (empty string
+    rewritten to ``"."`` for log clarity). An empty return list means
+    every expected target is populated.
+    """
+    missing: list[str] = []
+    for _, dest_sub in plan:
+        target = anchor / dest_sub if dest_sub else anchor
+        label = dest_sub or "."
+        if not target.is_dir():
+            missing.append(label)
+            continue
+        try:
+            next(target.iterdir())
+        except StopIteration:
+            missing.append(label)
+        except OSError:
+            missing.append(label)
+    return missing
+
+
 def install_global(
     tools: set[str],
     force: bool,
@@ -3525,20 +3718,34 @@ def install_global(
     installed_version = lock_mod.current_package_version()
     read_path = lock_mod.lockfile_path()
     write_path = lock_mod.lockfile_write_path()
-    ok, recorded = lock_mod.check_version(installed_version, path=read_path)
-
-    if not ok and not force:
+    _, recorded = lock_mod.check_version(installed_version, path=read_path)
+    classification = lock_mod.classify_mismatch(installed_version, recorded)
+
+    # Phase 2 (roadmap road-to-claude-code-global-distribution.md): a stale
+    # lockfile recording a *lower* (or unparseable legacy) version is the
+    # upgrade path — auto-heal by claiming the new version slot and
+    # continuing the install. Only a recorded version *higher* than the
+    # running package is treated as a downgrade and still requires --force.
+    # This kills the silent-refusal trap where users on pre-2.x (recorded:
+    # 1.42.0) installs hit `install.py:3530` and exit 1 without ever
+    # touching `~/.claude/`.
+    if classification == "downgrade" and not force:
         if not QUIET:
             print()
-            warn("Refusing global install: lockfile version mismatch.")
+            warn("Refusing global install: lockfile records a newer version.")
             info(f"  Lockfile:           {read_path}")
             info(f"  Recorded version:   {recorded}")
             info(f"  Current package:    {installed_version}")
-            info("  Fix:                run `agent-config update`")
-            info("  Override:           re-run with `--force` (replaces the lockfile)")
+            info("  Fix:                upgrade the package, or re-run with `--force`")
             print()
         return 1
 
+    if classification in ("upgrade", "unparseable") and not QUIET:
+        info(
+            f"🔄 Upgrading lockfile from {recorded} to {installed_version}, "
+            "redeploying tools"
+        )
+
     if not QUIET:
         print()
         info("Agent Config — Global (user-scope) install [ADR-007]")
@@ -3549,6 +3756,13 @@ def install_global(
                 continue
             print(f"      {tool_id:<15} → {anchor}")
 
+    # Claim the version slot BEFORE the deploy (Phase 2 Step 2 of the
+    # road-to-claude-code-global-distribution roadmap). The deploy can
+    # fail mid-way; the lockfile must stay on the new version regardless
+    # so subsequent re-runs do not relitigate the upgrade refusal. A
+    # partial deploy retries cleanly on the next invocation — the
+    # lockfile staying stuck on an ancient version is the worse failure
+    # mode this Phase exists to eliminate.
     existing = lock_mod.read_lockfile(path=read_path) or {}
     existing_tools = list(existing.get("tools", []))
     merged_tools = sorted(set(existing_tools) | set(tools))
@@ -3566,6 +3780,28 @@ def install_global(
     package_root = _resolve_package_root_for_global()
     deploy_results = _deploy_global_content(tools, force, package_root, written)
 
+    # Phase 5 (road-to-claude-code-global-distribution): postcheck-driven
+    # lockfile correction. A tool whose deploy postcheck failed
+    # (status="deploy_failed") MUST NOT remain in the lockfile's tools
+    # list — claiming "tool X is installed" without the content on disk
+    # is the silent-failure class this phase exists to surface. Tools
+    # already recorded by a prior successful install stay (the
+    # `failed_tools` set only filters this run's newly-attempted tools).
+    failed_tools = {
+        tool_id
+        for tool_id, (_, _, status, _) in deploy_results.items()
+        if status == "deploy_failed"
+    }
+    if failed_tools:
+        corrected_tools = sorted(set(merged_tools) - failed_tools)
+        if corrected_tools != merged_tools:
+            lock_mod.write_lockfile(installed_version, corrected_tools, path=write_path)
+            if not QUIET:
+                warn(
+                    "Lockfile corrected after deploy postcheck — dropped "
+                    f"{', '.join(sorted(failed_tools))} (verification failed)."
+                )
+
     # NDJSON progress for the wizard --apply-payload real-apply bridge. One
     # `file` frame per deployed tool unit (coarse, per AI-council 2026-05-27);
     # the GUI maps these to its SSE progress frames. No-op under normal CLI