@event4u/agent-config 8.0.0 → 8.2.0

package/src/scripts/_cli/cmd_upgrade.ts

@@ -20,9 +20,27 @@
  *
  * 1. `npm install -g @event4u/agent-config@latest` — refresh the global binary
  *    on PATH (the binary the Claude plugin hook resolves).
- * 2. `agent-config global` (→ `install.py --global`) — refresh the global root
- *    (`~/.event4u/agent-config/`) + regenerate plugin hooks.
- * 3. If run from inside a consumer project that already has a `./agent-config`
+ * 2. `agent-config global --no-ui` (→ `install --global`) — refresh the global
+ *    root (`~/.event4u/agent-config/`) + regenerate plugin hooks. `--no-ui`
+ *    suppresses the setup-wizard auto-launch: the wizard is an onboarding
+ *    surface, not an upgrade step, and a foreground wizard server would block
+ *    the remaining upgrade steps until Ctrl-C (which then failed the run).
+ * 2b. When the Claude Code plugin (`agent-config@event4u-agent-config`) is
+ *    installed, refresh it: `claude plugin marketplace update` +
+ *    `claude plugin update` — otherwise the plugin snapshot stays pinned to
+ *    its install-time git SHA and its command surface silently rots while
+ *    the file projection moves ahead. Non-fatal: a refresh failure warns and
+ *    names the manual commands. The plugin is OPTIONAL — the file projection
+ *    is a full install on its own; no plugin → no step, no nag.
+ * 3. `agent-config settings:sync --path <file>` for every EXISTING settings
+ *    file (global `~/.event4u/agent-config/settings/.agent-settings.yml`,
+ *    then the project settings when run inside a consumer project) — additive
+ *    merge that inserts keys the new release added to the template while
+ *    preserving user lines verbatim. Runs as a subprocess of the freshly
+ *    installed binary so the NEW template is the merge source. Non-fatal:
+ *    a sync failure warns and names the manual command, never fails the
+ *    upgrade. Never creates a settings file that did not exist.
+ * 4. If run from inside a consumer project that already has a `./agent-config`
  *    wrapper, re-stamp that wrapper from the canonical template.
  *
  * Flags:
@@ -71,6 +89,9 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as installed_lock from '../_lib/installed_lock.js';
 import * as update_check from '../_lib/update_check.js';
 import * as cli_wrapper from '../_lib/cli_wrapper.js';
+import * as claude_plugin from '../_lib/claude_plugin.js';
+import { event4u_root } from '../_lib/user_global_paths.js';
+import { project_settings_path } from '../_lib/agent_settings.js';
 import { _is_source_repo } from './cmd_refresh.js';
 
 const PACKAGE_NAME = '@event4u/agent-config';
@@ -219,6 +240,170 @@ function _maybe_refresh_project_wrapper(project_root: string, out: OutSink, _err
     }
 }
 
+/**
+ * Refresh the consumer's installed `.git/hooks/pre-commit` gate after a
+ * global upgrade — but only when the hook is OURS (identified by the
+ * `pre-commit-roadmap-progress` marker) and only when run from inside a
+ * project that has it. Without this, a hook installed under an older
+ * release keeps running the old template forever (`hooks:install` without
+ * `--force` short-circuits on the marker) — the py2ts-era hooks silently
+ * no-op'd for exactly this reason. Non-fatal: a failure warns and names
+ * the manual command.
+ */
+function _maybe_refresh_git_hook(
+    project_root: string,
+    runner: (cmd: string[]) => number,
+    out: OutSink,
+    err: OutSink,
+): void {
+    const hook = path.join(project_root, '.git', 'hooks', 'pre-commit');
+    let text: string;
+    try {
+        text = fs.readFileSync(hook, 'utf-8');
+    } catch {
+        return; // no hook installed (or worktree indirection) — nothing to refresh
+    }
+    if (!text.includes('pre-commit-roadmap-progress')) {
+        return; // not our hook — never overwrite a foreign pre-commit
+    }
+    const cmd = [_agent_config_bin(), 'hooks:install', '--force'];
+    _print(out, '→ ' + cmd.join(' '));
+    let rc: number;
+    try {
+        rc = runner(cmd);
+    } catch (exc) {
+        rc = 127;
+        _print(err, `cannot run ${cmd[0]}: ${osErrorStr(exc)}`);
+    }
+    if (rc !== 0) {
+        _print(
+            err,
+            `⚠️  agent-config upgrade: pre-commit hook refresh failed (exit ${rc}) — ` +
+                'run `agent-config hooks:install --force` manually.',
+        );
+    }
+}
+
+/**
+ * Existing settings files the post-upgrade sync should bring up to the new
+ * template (additive merge — user lines preserved verbatim, only missing
+ * template keys inserted; see `sync_agent_settings.ts`).
+ *
+ * Targets, in order:
+ *  1. Global settings — `~/.event4u/agent-config/settings/.agent-settings.yml`
+ *     (the canonical wizard-written file; `EVENT4U_CONFIG_HOME` honored).
+ *  2. Project settings — the project's read-path settings file when the
+ *     upgrade runs inside a consumer project that already has one.
+ *
+ * Only files that ALREADY EXIST are returned — the sync never creates a
+ * settings file as an upgrade side effect (fresh installs get theirs from
+ * the wizard / installer).
+ */
+function _settings_sync_targets(project_root: string): string[] {
+    const targets: string[] = [];
+    const global_settings = path.join(event4u_root(), 'settings', '.agent-settings.yml');
+    if (_isFile(global_settings)) {
+        targets.push(global_settings);
+    }
+    const project_settings = project_settings_path(project_root);
+    if (project_settings !== global_settings && _isFile(project_settings)) {
+        targets.push(project_settings);
+    }
+    return targets;
+}
+
+/**
+ * Run the additive settings sync for every existing target — as a SUBPROCESS
+ * of the freshly installed binary, never in-process: after `npm install -g`
+ * the running module is still the OLD version, so an in-process merge would
+ * use the OLD template and miss exactly the new keys the upgrade shipped.
+ *
+ * Non-fatal by design: the upgrade itself already succeeded; a sync failure
+ * surfaces a warning + the manual command instead of failing the run.
+ */
+function _sync_settings_files(
+    targets: readonly string[],
+    runner: (cmd: string[]) => number,
+    out: OutSink,
+    err: OutSink,
+): void {
+    for (const target of targets) {
+        const cmd = [_agent_config_bin(), 'settings:sync', '--path', target];
+        _print(out, '→ ' + cmd.join(' '));
+        let rc: number;
+        try {
+            rc = runner(cmd);
+        } catch (exc) {
+            rc = 127;
+            _print(err, `cannot run ${cmd[0]}: ${osErrorStr(exc)}`);
+        }
+        if (rc !== 0) {
+            _print(
+                err,
+                `⚠️  agent-config upgrade: settings sync failed (exit ${rc}) for ` +
+                    `${target} — run \`agent-config settings:sync --path ${target}\` manually.`,
+            );
+        }
+    }
+}
+
+/**
+ * Refresh steps for the OPTIONAL Claude Code plugin. Non-empty only when the
+ * `claude` CLI is on PATH AND the plugin is recorded as installed — the file
+ * projection is a complete install on its own, so a missing plugin is not a
+ * gap to nag about. When present, the plugin must be refreshed alongside the
+ * global install: Claude Code pins it to the install-time git SHA, so without
+ * this step its command surface silently lags every upgrade.
+ */
+function _claude_plugin_refresh_steps(): string[][] {
+    const claude = shutilWhich('claude');
+    if (claude === null) return [];
+    if (!claude_plugin.claude_plugin_installed()) return [];
+    return [
+        [claude, 'plugin', 'marketplace', 'update', claude_plugin.CLAUDE_MARKETPLACE_NAME],
+        [
+            claude,
+            'plugin',
+            'update',
+            `${claude_plugin.CLAUDE_PLUGIN_ID}@${claude_plugin.CLAUDE_MARKETPLACE_NAME}`,
+        ],
+    ];
+}
+
+/**
+ * Run the plugin-refresh steps. Non-fatal by design (same contract as the
+ * settings sync): the upgrade itself already succeeded; a failure surfaces a
+ * warning + the manual command instead of failing the run.
+ */
+function _refresh_claude_plugin(
+    steps: readonly string[][],
+    runner: (cmd: string[]) => number,
+    out: OutSink,
+    err: OutSink,
+): void {
+    for (const cmd of steps) {
+        _print(out, '→ ' + cmd.join(' '));
+        let rc: number;
+        try {
+            rc = runner(cmd);
+        } catch (exc) {
+            rc = 127;
+            _print(err, `cannot run ${cmd[0]}: ${osErrorStr(exc)}`);
+        }
+        if (rc !== 0) {
+            _print(
+                err,
+                `⚠️  agent-config upgrade: Claude Code plugin refresh failed (exit ${rc}) — ` +
+                    `run \`${cmd.join(' ')}\` manually.`,
+            );
+            return;
+        }
+    }
+    if (steps.length > 0) {
+        _print(out, 'ℹ️  Claude Code plugin refreshed — restart Claude Code to load it.');
+    }
+}
+
 interface Args {
     check: boolean;
     dry_run: boolean;
@@ -321,14 +506,26 @@ export async function main(argv: string[] | null = null, options: MainOptions =
     const target = `${PACKAGE_NAME}@latest`;
     const steps: string[][] = [
         ['npm', 'install', '-g', target],
-        [_agent_config_bin(), 'global'],
+        // --no-ui: the setup wizard is an onboarding surface, not an upgrade
+        // step — its foreground server used to block the upgrade until Ctrl-C.
+        [_agent_config_bin(), 'global', '--no-ui'],
     ];
 
+    const project_root = options.project_root ?? process.cwd();
+    const sync_targets = _settings_sync_targets(project_root);
+    const plugin_steps = _claude_plugin_refresh_steps();
+
     if (args.dry_run) {
         _print(out, 'agent-config upgrade — dry run, would execute:');
         for (const cmd of steps) {
             _print(out, '  ' + cmd.join(' '));
         }
+        for (const cmd of plugin_steps) {
+            _print(out, '  ' + cmd.join(' '));
+        }
+        for (const target of sync_targets) {
+            _print(out, '  ' + [_agent_config_bin(), 'settings:sync', '--path', target].join(' '));
+        }
         return 0;
     }
 
@@ -344,7 +541,20 @@ export async function main(argv: string[] | null = null, options: MainOptions =
         }
     }
 
-    _maybe_refresh_project_wrapper(options.project_root ?? process.cwd(), out, err);
+    // Refresh the OPTIONAL Claude Code plugin so its command surface tracks
+    // the upgrade (no-op when the plugin is not installed — the file
+    // projection is a full install on its own).
+    _refresh_claude_plugin(plugin_steps, runner, out, err);
+
+    // Bring existing settings files up to the NEW template (additive; the
+    // subprocess resolves the freshly installed binary + template).
+    _sync_settings_files(sync_targets, runner, out, err);
+
+    _maybe_refresh_project_wrapper(project_root, out, err);
+
+    // Re-stamp OUR installed .git/hooks/pre-commit from the new template
+    // (marker-guarded; foreign hooks are never touched).
+    _maybe_refresh_git_hook(project_root, runner, out, err);
 
     _print(
         out,
@@ -361,10 +571,29 @@ function installed_lock_is_newer(latest: string, installed: string): boolean {
 
 // --- CLI entry ---
 
-const _isCliEntry =
-    process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-if (_isCliEntry || process.argv[1] === _HERE) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
     main(process.argv.slice(2))
         .then((code) => {
             process.exitCode = code;

package/src/scripts/_cli/cmd_validate.ts

@@ -367,10 +367,29 @@ export function main(argv: string[]): number {
 
 // --- CLI entry ---
 
-const _isCliEntry =
-    process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-if (_isCliEntry || process.argv[1] === _HERE) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
     try {
         process.exitCode = main(process.argv.slice(2));
     } catch (e) {

package/src/scripts/_cli/cmd_versions.ts

@@ -476,10 +476,29 @@ export function main(argv: string[] | null = null, options: MainOptions = {}): n
 // Python: `if __name__ == "__main__": raise SystemExit(main())` (no argv slice;
 // argparse reads sys.argv[1:] inside `_parse` default).
 const _HERE = fileURLToPath(import.meta.url);
-const _isCliEntry =
-    process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-if (_isCliEntry || process.argv[1] === _HERE) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
     try {
         process.exitCode = main();
     } catch (exc) {

package/src/scripts/_dispatch.bash

@@ -13,7 +13,7 @@
 #   * CWD on entry is the consumer's repo root — we keep it that way
 #     so underlying scripts resolve paths correctly.
 #   * PACKAGE_ROOT is derived from this script's location, used only to
-#     locate the package-internal Python scripts (mcp_render.py, …).
+#     locate the package-internal TypeScript scripts (mcp_render.ts, …).
 #   * Unknown arguments are forwarded verbatim to the underlying script.
 
 set -euo pipefail
@@ -138,19 +138,26 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   mcp:render                 Render mcp.json → .cursor/mcp.json, .windsurf/mcp.json
                              (pass --claude-desktop to also write user-scope config)
   mcp:check                  Dry-run mcp:render; exit non-zero if targets are stale
-  mcp:setup                  Create .venv-mcp/ and install the mcp SDK
+  mcp:setup                  Verify the tsx runtime + MCP server module and
+                             print the client config snippet
                              (one-line MCP server onboarding; idempotent)
   mcp:run                    Run the built-in MCP server over stdio
                              (requires `mcp:setup` first; see docs/mcp-server.md)
                              (experimental — beta gates: docs/contracts/mcp-beta-criteria.md)
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
+  roadmap:archive            Archive completed roadmaps (branch-touched by default;
+                             --all for every complete one; --dry-run to preview)
   capabilities:index         Regenerate CAPABILITIES.yaml — the package coverage index
                              (capability area → coverage → backing skills/commands → gaps).
                              Pass --check to fail if stale (for CI). Reads src/ (package repo).
   settings:check             Validate .agent-settings.yml against the YAML-subset contract
                              (docs/contracts/settings-sync-yaml-subset.md). Read-only.
                              Exit 0 clean, 1 finding(s), 2 file absent / unreadable.
+  settings:sync              Additively merge new template keys into an existing
+                             .agent-settings.yml (user lines preserved verbatim).
+                             Run automatically by `upgrade`. Flags: --path <file>
+                             | --dry-run | --check (exit 2 on drift) | --profile.
   settings:migrate           Lift project-local .agent-settings.yml / .agent-user.yml into
                              ~/.event4u/agent-config/ (the global-only consumer surface,
                              ADR-020). Idempotent; --force overwrites a non-empty global
@@ -284,20 +291,35 @@ print_version() {
   fi
 }
 
-# Resolve the tsx runner (Python→TypeScript migration). Sets TSX_BIN to the
-# repo-local binary when present, else `npx tsx`. Exits 127 if neither works
-# since the runtime is now Node/tsx and there is no Python fallback.
+# Resolve the tsx runner (Python→TypeScript migration). tsx ships as a
+# RUNTIME dependency of the package, so the package-local install is the
+# canonical source — first via node_modules/.bin, then via the module's CLI
+# entry (covers installs where .bin shims are missing). `npx tsx` is a last
+# resort only: npx runs against the CONSUMER project's cwd, so its npm config
+# and devEngines/engines constraints apply — a consumer pinning e.g.
+# `node <24` hard-fails every hook and TS command with EBADDEVENGINES (the
+# 8.1.0 regression that silently broke hooks + roadmap:progress in consumer
+# projects). Exits 127 when nothing works — the runtime is Node/tsx, there is
+# no Python fallback.
 require_tsx() {
   if [[ -x "$PACKAGE_ROOT/node_modules/.bin/tsx" ]]; then
     TSX_BIN="$PACKAGE_ROOT/node_modules/.bin/tsx"
     return 0
   fi
+  if [[ -f "$PACKAGE_ROOT/node_modules/tsx/dist/cli.mjs" ]] && command -v node >/dev/null 2>&1; then
+    TSX_BIN="node $PACKAGE_ROOT/node_modules/tsx/dist/cli.mjs"
+    return 0
+  fi
   if command -v npx >/dev/null 2>&1; then
+    echo "⚠️  agent-config: package-local tsx not found — falling back to \`npx tsx\`" >&2
+    echo "    (subject to this project's npm config; reinstall the package to fix:" >&2
+    echo "     npm install -g @event4u/agent-config)" >&2
     TSX_BIN="npx tsx"
     return 0
   fi
-  echo "❌  agent-config: tsx runner not found on PATH" >&2
-  echo "    Run \`npm install\` in the package to provide node_modules/.bin/tsx." >&2
+  echo "❌  agent-config: tsx runner not found" >&2
+  echo "    Reinstall the package (npm install -g @event4u/agent-config) to provide" >&2
+  echo "    node_modules/tsx, or run \`npm install\` at the package root." >&2
   exit 127
 }
 
@@ -335,7 +357,7 @@ exec_hook() {
 
 # Locate a script. First argument is relative to PACKAGE_ROOT, second is
 # an optional fallback relative to CONSUMER_ROOT (for scripts that ship
-# to the consumer via .augment/, e.g. update_roadmap_progress.py).
+# to the consumer via .augment/, e.g. update_roadmap_progress.ts).
 resolve_script() {
   local pkg_rel="$1"
   local consumer_rel="${2-}"
@@ -422,6 +444,14 @@ cmd_roadmap_progress_check() {
   exec_ts "$script" --check "$@"
 }
 
+# The PR-gate archival sweep (`/create-pr` § 1c and roadmap-progress-sync's
+# PR-gate) instructs `./agent-config roadmap:archive` — this is that command.
+cmd_roadmap_archive() {
+  local script
+  script="$(resolve_script "dist/agent-src/scripts/archive_completed_roadmaps.ts" ".augment/scripts/archive_completed_roadmaps.ts")"
+  exec_ts "$script" "$@"
+}
+
 cmd_capabilities_index() {
   local script
   script="$(resolve_script "src/scripts/generate_capabilities_index.ts")"
@@ -593,7 +623,7 @@ Three modes, picked by flag combination:
                       at the consumer root. Idempotent.
 
   --regen             Provision the roadmap-progress regenerator at
-                      .augment/scripts/update_roadmap_progress.py
+                      .augment/scripts/update_roadmap_progress.ts
                       (canonical path per docs/contracts/hook-architecture-v1.md
                       § Regenerator location). Idempotent.
 
@@ -793,7 +823,7 @@ cmd_keys_install_openai() {
 
 # Council CLI — non-interactive wrapper around scripts.ai_council.orchestrator.
 # Three subcommands share one Python entry point; we forward the subcommand
-# verb so `./agent-config council:run --confirm` lands on `council_cli.py run`.
+# verb so `./agent-config council:run --confirm` lands on `council_cli.ts run`.
 cmd_council() {
   local sub="$1"; shift || true
   local script
@@ -811,7 +841,7 @@ cmd_use() {
 }
 
 # `agent-config update` — flip the agent_config_version pin in
-# .agent-settings.yml. See scripts/_cli/cmd_update.py (P3.1 of
+# .agent-settings.yml. See scripts/_cli/cmd_update.ts (P3.1 of
 # road-to-portable-runtime-and-update-check.md).
 cmd_update() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_update.ts" "$@"
@@ -826,7 +856,7 @@ cmd_refresh() {
 }
 
 # `agent-config migrate` — one-shot migration off legacy composer / npm
-# install paths onto the npx-only runtime. See scripts/_cli/cmd_migrate.py
+# install paths onto the npx-only runtime. See scripts/_cli/cmd_migrate.ts
 # (P3.5 of road-to-portable-runtime-and-update-check.md).
 cmd_migrate() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_migrate.ts" "$@"
@@ -845,7 +875,7 @@ cmd_init() {
 # `agent-config global` — user-scope install entry point. Forwards to the
 # bash installer with `--global` set (ADR-007). Phase 1.2 of
 # road-to-global-first-install.md. The bash wrapper handles option parsing
-# and forwards to `scripts/install.py --global`, where `install_global()`
+# and forwards to `scripts/install.ts --global`, where `install_global()`
 # currently scaffolds the per-tool anchor paths from USER_SCOPE_PATHS.
 # Concrete writes land in Phase 1.5 (export) and Phase 1.6 (lockfile).
 cmd_global() {
@@ -857,7 +887,7 @@ cmd_global() {
 # `agent-config export` — write a tool's canonical content into a
 # user-chosen path. ADR-007 D3 / Phase 1.5 of
 # road-to-global-first-install.md. Replaces the rejected symlink-bridge.
-# See scripts/_cli/cmd_export.py for the registry and idempotency logic.
+# See scripts/_cli/cmd_export.ts for the registry and idempotency logic.
 cmd_export() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_export.ts" "$@"
 }
@@ -884,6 +914,17 @@ cmd_settings_check() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_settings_check.ts" "$@"
 }
 
+# `agent-config settings:sync` — additive merge of the current
+# agent-settings template into an existing .agent-settings.yml. User lines
+# are preserved verbatim; only missing template keys are inserted.
+# Idempotent. Invoked automatically by `agent-config upgrade` for every
+# existing settings file (global + project) so nobody keeps stale settings
+# after a release. Flags: --path <file> | --dry-run | --check | --profile.
+# Exit 0 in-sync / updated, 2 drift under --check or bad input.
+cmd_settings_sync() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/sync_agent_settings.ts" "$@"
+}
+
 # `agent-config settings:migrate` — lift project-local
 # .agent-settings.yml / .agent-user.yml into ~/.event4u/agent-config/.
 # Phase 2.4 of road-to-global-only-install.md. Read-only on the source —
@@ -897,7 +938,7 @@ cmd_settings_migrate() {
 # `agent-config uninstall` — remove bridge markers (project) or lockfile
 # entries (global). Idempotent. Pass `--purge` to also delete deployed
 # content directories under user-scope anchors (destructive). See
-# scripts/_cli/cmd_uninstall.py.
+# scripts/_cli/cmd_uninstall.ts.
 cmd_uninstall() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_uninstall.ts" "$@"
 }
@@ -906,14 +947,14 @@ cmd_uninstall() {
 # Drift-cleanup sibling to `uninstall`: compares on-disk markers
 # against agents/installed-tools.lock and unlinks anything not
 # declared. Hard-floors when lockfile is absent. See
-# scripts/_cli/cmd_prune.py.
+# scripts/_cli/cmd_prune.ts.
 cmd_prune() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_prune.ts" "$@"
 }
 
 # `agent-config doctor` — read-only drift report against the manifest.
 # Surfaces missing / modified / foreign files. Exit 0 clean, 1 drift,
-# 2 manifest-absent. See scripts/_cli/cmd_doctor.py.
+# 2 manifest-absent. See scripts/_cli/cmd_doctor.ts.
 cmd_doctor() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_doctor.ts" "$@"
 }
@@ -930,14 +971,14 @@ cmd_conformance() {
 # `agent-config versions` — list available @event4u/agent-config versions
 # on the npm registry. Marks the current pin (from .agent-settings.yml)
 # and the latest published version. Offline-tolerant. See
-# scripts/_cli/cmd_versions.py.
+# scripts/_cli/cmd_versions.ts.
 cmd_versions() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_versions.ts" "$@"
 }
 
 # `agent-config explain <config|rule|route>` — print the decision chain
 # behind a configuration or routing outcome. Read-only diagnostic; never
-# edits state. See scripts/_cli/cmd_explain.py.
+# edits state. See scripts/_cli/cmd_explain.ts.
 cmd_explain() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_explain.ts" "$@"
 }
@@ -961,6 +1002,7 @@ main() {
     use)                     cmd_use "$@" ;;
     roadmap:progress)        cmd_roadmap_progress "$@" ;;
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
+    roadmap:archive)         cmd_roadmap_archive "$@" ;;
     capabilities:index)      cmd_capabilities_index "$@" ;;
     hooks:install)           cmd_hooks_install "$@" ;;
     keys:install-anthropic)  cmd_keys_install_anthropic "$@" ;;
@@ -1001,6 +1043,7 @@ main() {
     sync)                    cmd_sync "$@" ;;
     validate)                cmd_validate "$@" ;;
     settings:check)          cmd_settings_check "$@" ;;
+    settings:sync)           cmd_settings_sync "$@" ;;
     settings:migrate)        cmd_settings_migrate "$@" ;;
     uninstall)               cmd_uninstall "$@" ;;
     prune)                   cmd_prune "$@" ;;

package/src/scripts/_lib/claude_plugin.ts

@@ -0,0 +1,83 @@
+/**
+ * Claude Code plugin detection helpers — shared by `cmd_upgrade`,
+ * `cmd_doctor`, and the installer.
+ *
+ * Claude Code loads the FULL top-level command set (`/implement-ticket`,
+ * `/work`, `/review-changes`, …) from the installed plugin
+ * (`agent-config@event4u-agent-config`), NOT from the `~/.claude/commands/`
+ * file projection. A file-only install therefore silently misses top-level
+ * commands while namespaced subcommands (`/fix:pr-comments`, …) keep working
+ * — and an installed plugin stays pinned to its install-time git SHA until
+ * `claude plugin update` runs. These helpers detect both states so
+ * upgrade / doctor / install can refresh the plugin or surface the gap.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import process from 'node:process';
+
+export const CLAUDE_PLUGIN_ID = 'agent-config';
+export const CLAUDE_MARKETPLACE_NAME = 'event4u-agent-config';
+export const CLAUDE_MARKETPLACE_REPO = 'event4u-app/agent-config';
+
+/** The one-time install commands surfaced when the plugin is missing. */
+export const CLAUDE_PLUGIN_INSTALL_HINT: readonly string[] = [
+    `claude plugin marketplace add ${CLAUDE_MARKETPLACE_REPO}`,
+    `claude plugin install ${CLAUDE_PLUGIN_ID}@${CLAUDE_MARKETPLACE_NAME}`,
+];
+
+/** Claude Code config dir — `CLAUDE_CONFIG_DIR` env override, else `~/.claude`. */
+export function claude_config_dir(): string {
+    const env = (process.env['CLAUDE_CONFIG_DIR'] ?? '').trim();
+    return env !== '' ? env : path.join(os.homedir(), '.claude');
+}
+
+/**
+ * True when the agent-config plugin is recorded in Claude Code's
+ * `plugins/installed_plugins.json` (any marketplace — matched by the
+ * `agent-config@` id prefix). Unreadable / absent file → false.
+ */
+export function claude_plugin_installed(): boolean {
+    const p = path.join(claude_config_dir(), 'plugins', 'installed_plugins.json');
+    let data: unknown;
+    try {
+        data = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    } catch {
+        return false;
+    }
+    if (data === null || typeof data !== 'object') return false;
+    const plugins = (data as { plugins?: unknown }).plugins;
+    if (plugins === null || plugins === undefined || typeof plugins !== 'object') return false;
+    return Object.keys(plugins as Record<string, unknown>).some((k) =>
+        k.startsWith(`${CLAUDE_PLUGIN_ID}@`),
+    );
+}
+
+/**
+ * Version recorded in the installed marketplace snapshot's
+ * `.claude-plugin/marketplace.json` (`metadata.version` — bumped per
+ * release, so it tracks the package version the snapshot was taken from).
+ * Null when the snapshot is absent or unreadable.
+ */
+export function claude_plugin_snapshot_version(): string | null {
+    const p = path.join(
+        claude_config_dir(),
+        'plugins',
+        'marketplaces',
+        CLAUDE_MARKETPLACE_NAME,
+        '.claude-plugin',
+        'marketplace.json',
+    );
+    let data: unknown;
+    try {
+        data = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    } catch {
+        return null;
+    }
+    if (data === null || typeof data !== 'object') return null;
+    const metadata = (data as { metadata?: unknown }).metadata;
+    if (metadata === null || metadata === undefined || typeof metadata !== 'object') return null;
+    const v = (metadata as { version?: unknown }).version;
+    return typeof v === 'string' && v.trim() !== '' ? v.trim() : null;
+}