@event4u/agent-config 8.4.1 → 8.5.0

package/src/agent-src/templates/scripts/work_engine/stack/runner.ts

@@ -11,7 +11,7 @@
  * runner and quality tools does this stack actually use, and what is the
  * exact command to invoke them?* It is the engine behind 6.1.0 Step 6 — the
  * toolchain resolver that lets one set of commands (`/tests execute`,
- * `/tests create`, `/quality-fix`, `/review-changes`, `/work`) adapt to
+ * `/tests create`, `/fix quality`, `/review changes`, `/work`) adapt to
  * phpunit / pest / vitest / jest / playwright / pytest / go / cargo instead
  * of exploding into per-stack command variants.
  *

package/src/config/agent-settings.template.yml

@@ -460,7 +460,7 @@ quality:
   #         tokens. The user runs quality tools manually; remote CI is
   #         the authoritative gate. The agent runs a quality tool ONLY
   #         when one of three triggers fires:
-  #           1. the user explicitly asks this turn (e.g. /quality-fix),
+  #           1. the user explicitly asks this turn (e.g. /fix quality),
   #           2. CI / the remote pipeline reports a concrete failure —
   #              then run exactly that failing check to reproduce + fix,
   #           3. the new-gate carve-out below.

package/src/install/selectedTools.ts

@@ -1,14 +1,20 @@
 /**
- * Persisted record of the AI tools the user actually selected in the wizard,
- * at `~/.event4u/agent-config/wizard-tools.json`. This is the user's prior
- * *selection* — distinct from `installed.lock` (every tool agent-config was
- * deployed to, which for an `--tools=all` install is the full set) and from
- * machine tool *detection*.
+ * Persisted record of the AI tools AND capability packs the user actually
+ * selected in the wizard, at `~/.event4u/agent-config/wizard-tools.json`.
+ * This is the user's prior *selection* — distinct from `installed.lock`
+ * (every tool agent-config was deployed to, which for an `--tools=all`
+ * install is the full set) and from machine tool *detection*.
  *
  * Written by the apply route on a real (non-dry-run) wizard-v2 apply, and
- * read by `detect-tools` so Step 1 pre-selects exactly the prior selection on
- * a repeat run. Empty / missing → first run → Step 1 falls back to
- * pre-selecting every installed tool.
+ * read by `detect-tools` / the manifest endpoint so a repeat run pre-selects
+ * exactly the prior selection. Empty / missing → first run → Step 1 falls
+ * back to pre-selecting every installed tool.
+ *
+ * `packs` was added by road-to-setup-experience (council 2026-07-08,
+ * lockfile-extension over settings-YAML surgery): the `packs:` list in
+ * `.agent-settings.yml` is only rendered into FRESH settings files, so on
+ * machines with an existing file the selection was never persisted anywhere
+ * — the wizard forgot installed packs between runs.
  *
  * `AGENT_CONFIG_WIZARD_TOOLS` overrides the path (tests only).
  */
@@ -23,17 +29,39 @@ function selectedToolsPath(): string {
     return resolve(homedir(), '.event4u', 'agent-config', 'wizard-tools.json');
 }
 
-export function writeSelectedTools(tools: string[]): void {
+export function writeSelectedTools(tools: string[], packs?: string[]): void {
     try {
         const path = selectedToolsPath();
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-        writeFileSync(path, `${JSON.stringify({ tools }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+        // Preserve a previously recorded packs list when the caller does not
+        // pass one (older call sites) — never silently drop the selection.
+        const record: { tools: string[]; packs?: string[] } = { tools };
+        const packsToWrite = packs ?? readSelectedPacks();
+        if (packsToWrite.length > 0 || packs !== undefined) record.packs = packsToWrite;
+        writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
     } catch {
         // Best-effort: a failed write just means the next run falls back to
         // pre-selecting installed tools.
     }
 }
 
+/**
+ * Return the recorded pack selection, or `[]` when absent / unreadable.
+ * Optionally intersect with the known-pack set so a stale id never surfaces.
+ */
+export function readSelectedPacks(knownIds?: ReadonlySet<string>): string[] {
+    try {
+        const raw = readFileSync(selectedToolsPath(), 'utf8');
+        const parsed = JSON.parse(raw) as { packs?: unknown };
+        const packs = Array.isArray(parsed.packs)
+            ? parsed.packs.filter((p): p is string => typeof p === 'string')
+            : [];
+        return knownIds === undefined ? packs : packs.filter((p) => knownIds.has(p));
+    } catch {
+        return [];
+    }
+}
+
 /**
  * Return the recorded selection, or `[]` when absent / unreadable. Optionally
  * intersect with the known-tool set so a stale id never surfaces.

package/src/scripts/_cli/cmd_converge.ts

@@ -250,6 +250,37 @@ export interface MainOptions {
     err?: OutSink;
 }
 
+/**
+ * Live-session notice for reaped Claude Code plugin caches — or null when no
+ * reap touched `~/.claude/plugins/`.
+ *
+ * Removing an installed plugin's cache does NOT reach into Claude Code
+ * sessions that are already running: they registered the plugin's hooks at
+ * session start and keep firing them, so every subsequent event logs
+ * `Failed to run: Plugin directory does not exist: …/plugins/cache/… — run
+ * /plugin to reinstall` until the session restarts. Claude Code's own
+ * `/plugin to reinstall` hint would recreate exactly the duplicate surface
+ * converge just removed — the correct remedy is a restart, so converge says
+ * so explicitly (road-to-truth-and-reference-hygiene follow-up, 2026-07-08).
+ */
+export function live_session_notice(executed_reaps: readonly string[]): string | null {
+    const hit = executed_reaps.some((r) => r.startsWith('~/.claude/plugins/'));
+    if (!hit) {
+        return null;
+    }
+    return (
+        '⚠️  Live-session note: Claude Code sessions that were ALREADY RUNNING still\n' +
+        '    hold the removed plugin\'s hook registrations. Until you restart them,\n' +
+        '    every event logs a non-blocking\n' +
+        '      "Failed to run: Plugin directory does not exist: …/plugins/cache/…"\n' +
+        '    error. This is cosmetic for new sessions but means the affected LIVE\n' +
+        '    session\'s plugin-sourced hooks no longer run — restart Claude Code\n' +
+        '    sessions to clear it. Do NOT follow the error\'s "/plugin to reinstall"\n' +
+        '    hint: reinstalling recreates the duplicate surface converge just removed\n' +
+        '    (the ~/.claude/ file projection already carries content AND hooks).'
+    );
+}
+
 export function main(argv: string[] | null = null, opts: MainOptions = {}): number {
     let args: Args;
     try {
@@ -329,6 +360,7 @@ export function main(argv: string[] | null = null, opts: MainOptions = {}): numb
     // Perform the cleanup — matrix-declared actions ONLY.
     let failures = 0;
     const report: string[] = [];
+    const executed_reaps: string[] = [];
     for (const f of findings) {
         if (f.command) {
             _print(out, `→ ${f.command}`);
@@ -351,6 +383,7 @@ export function main(argv: string[] | null = null, opts: MainOptions = {}): numb
             try {
                 fs.rmSync(abs, { recursive: true, force: true });
                 report.push(`${f.tool}: reaped package-tagged orphan \`${reap}\``);
+                executed_reaps.push(reap);
                 _print(out, `→ reaped ${reap}`);
             } catch (e) {
                 failures += 1;
@@ -367,6 +400,11 @@ export function main(argv: string[] | null = null, opts: MainOptions = {}): numb
     if (report.length === 0) {
         _print(out, '  (no actions completed)');
     }
+    const notice = live_session_notice(executed_reaps);
+    if (notice !== null) {
+        _print(out);
+        _print(out, notice);
+    }
     _print(
         out,
         'Rollback hint: a removed Claude Code plugin can be reinstalled with\n' +

package/src/scripts/_cli/cmd_doctor.ts

@@ -2,8 +2,8 @@
 /**
  * `agent-config doctor` — install + manifest health report (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_doctor.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_doctor.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * report lines (✅/❌/⚠️/⏭️ glyphs, ordering, fix hints), same filesystem
  * semantics. No behaviour changes — latent quirks are replicated, not fixed.
@@ -731,6 +731,7 @@ const CHECK_IDS = [
     'scope',
     'global-binary',
     'claude-plugin',
+    'claude-command-wrappers',
     'surface-state',
     'hook-wiring',
     'stale-orphans',
@@ -745,6 +746,7 @@ const CHECK_IDS = [
     'council-cli',
     'unsupported-combos',
     'wizard-state',
+    'settings-review-pending',
 ] as const;
 
 /** Checks that need only the project root and run regardless of a lockfile. */
@@ -752,6 +754,7 @@ const GLOBAL_CHECK_IDS: ReadonlySet<string> = new Set([
     'scope',
     'global-binary',
     'claude-plugin',
+    'claude-command-wrappers',
     'surface-state',
     'hook-wiring',
     'stale-orphans',
@@ -762,6 +765,7 @@ const GLOBAL_CHECK_IDS: ReadonlySet<string> = new Set([
     'tier-usage-readiness',
     'council-cli',
     'wizard-state',
+    'settings-review-pending',
 ]);
 
 /** Checks that genuinely cannot run without the project manifest. */
@@ -1077,6 +1081,69 @@ function _check_claude_plugin(): Dict {
     };
 }
 
+/**
+ * Claude Code flat-command discovery mitigation (council 2026-07-08,
+ * cc-user-command-discovery): Claude Code ≤ 2.1.204 does not register FLAT
+ * user-scope command files (`~/.claude/commands/<name>.md`) — nested
+ * commands and user-scope skills do. The installer therefore projects
+ * tier-0/1 visible flat commands as skill wrappers. This check flags the
+ * silent-failure state: a projection deployed by an OLDER release that
+ * still carries visible flat commands without wrappers (users see
+ * "Unknown command" for /commit etc. with zero error anywhere).
+ * Probe = `commit` (the canonical always-shipped visible flat command);
+ * static file checks only — never a live model call.
+ */
+function _check_claude_command_wrappers(): Dict {
+    const claude = shutilWhich('claude');
+    if (claude === null) {
+        return {
+            id: 'claude-command-wrappers',
+            status: 'skipped',
+            message: 'Claude Code CLI not on PATH — wrapper check not applicable',
+            remedy: '',
+        };
+    }
+    const anchor = path.join(os.homedir(), '.claude');
+    const commands_dir = path.join(anchor, 'commands');
+    if (!isDir(commands_dir)) {
+        return {
+            id: 'claude-command-wrappers',
+            status: 'skipped',
+            message: 'no ~/.claude/commands projection — nothing to check',
+            remedy: '',
+        };
+    }
+    const flat_probe = fs.existsSync(path.join(commands_dir, 'commit.md'));
+    const wrapper_probe = fs.existsSync(path.join(anchor, 'skills', 'commit', 'SKILL.md'));
+    if (wrapper_probe) {
+        return {
+            id: 'claude-command-wrappers',
+            status: 'ok',
+            message:
+                'flat-command skill wrappers present (Claude Code flat-command ' +
+                'discovery workaround active)',
+            remedy: '',
+        };
+    }
+    if (flat_probe) {
+        return {
+            id: 'claude-command-wrappers',
+            status: 'warn',
+            message:
+                'visible flat commands deployed WITHOUT skill wrappers — Claude Code ' +
+                '\u2264 2.1.204 does not register flat user-scope command files, so ' +
+                '/commit and other visible commands appear as "Unknown command"',
+            remedy: 'agent-config refresh --global (re-deploys with the wrapper projection)',
+        };
+    }
+    return {
+        id: 'claude-command-wrappers',
+        status: 'skipped',
+        message: 'no visible flat commands in the projection — nothing to wrap',
+        remedy: '',
+    };
+}
+
 /**
  * Matrix-driven duplicate-surface check (road-to-install-path-convergence
  * Phase 2): reads src/config/surface-matrix.yml and flags every tool whose
@@ -1167,6 +1234,7 @@ function pathExistsAny(p: string): boolean {
     }
 }
 
+
 /**
  * Managed hook wiring (single-surface model): the deterministic hook matrix
  * must be registered in ~/.claude/settings.json AND the dispatch target
@@ -1900,6 +1968,43 @@ function _check_wizard_state(): Dict {
     };
 }
 
+/**
+ * Pending settings-surface review (road-to-settings-change-review): the
+ * installer writes `state/settings-delta.json` when an upgrade changed
+ * defaults / enum vocabularies / added settings. The flag persists until
+ * the user resolves the review form (`agent-config config` → Settings →
+ * banner) — this check keeps it visible in every doctor run.
+ */
+function _check_settings_review_pending(): Dict {
+    const delta_pth = path.join(user_global_paths.event4u_root(), 'state', 'settings-delta.json');
+    if (!pathExists(delta_pth)) {
+        return {
+            id: 'settings-review-pending',
+            status: 'ok',
+            message: 'no pending settings-surface changes',
+            remedy: '',
+        };
+    }
+    let summary = '';
+    try {
+        const data = JSON.parse(readText0(delta_pth)) as {
+            oldVersion?: string;
+            newVersion?: string;
+            changes?: unknown[];
+        };
+        const n = Array.isArray(data.changes) ? data.changes.length : 0;
+        summary = `${n} change${n === 1 ? '' : 's'} (${data.oldVersion ?? '?'} → ${data.newVersion ?? '?'})`;
+    } catch {
+        summary = 'unreadable delta file';
+    }
+    return {
+        id: 'settings-review-pending',
+        status: 'warn',
+        message: `settings surface changed on upgrade — ${summary} awaiting review`,
+        remedy: 'agent-config config (Settings → “Review changes” banner)',
+    };
+}
+
 interface JsonDecodeError {
     msg: string;
     lineno: number;
@@ -2008,6 +2113,7 @@ function _run_checks(
         scope: () => _check_scope(project_root),
         'global-binary': () => _check_global_binary(project_root),
         'claude-plugin': _check_claude_plugin,
+        'claude-command-wrappers': _check_claude_command_wrappers,
         'surface-state': _check_surface_state,
         'hook-wiring': _check_hook_wiring,
         'stale-orphans': _check_stale_orphans,
@@ -2028,6 +2134,7 @@ function _run_checks(
         'council-cli': () => _check_council_cli(project_root),
         'unsupported-combos': () => _check_unsupported_combos(manifest),
         'wizard-state': _check_wizard_state,
+        'settings-review-pending': _check_settings_review_pending,
     };
     const out: Dict[] = [];
     for (const cid of CHECK_IDS) {
@@ -2082,6 +2189,7 @@ function _run_checks_no_manifest(
         scope: () => _check_scope(project_root),
         'global-binary': () => _check_global_binary(project_root),
         'claude-plugin': _check_claude_plugin,
+        'claude-command-wrappers': _check_claude_command_wrappers,
         'surface-state': _check_surface_state,
         'hook-wiring': _check_hook_wiring,
         'stale-orphans': _check_stale_orphans,
@@ -2096,6 +2204,7 @@ function _run_checks_no_manifest(
         'council-cli': () => _check_council_cli(project_root),
         'unsupported-combos': () => _skipped_manifest_check('unsupported-combos'),
         'wizard-state': _check_wizard_state,
+        'settings-review-pending': _check_settings_review_pending,
     };
     const out: Dict[] = [];
     for (const cid of CHECK_IDS) {
@@ -2572,6 +2681,7 @@ export {
     _check_lockfile_freshness,
     _check_global_binary,
     _check_claude_plugin,
+    _check_claude_command_wrappers,
     _check_bridge_drift,
     _check_mcp_mode,
     _check_offline_readiness,
@@ -2582,6 +2692,7 @@ export {
     _check_council_cli,
     _check_unsupported_combos,
     _check_wizard_state,
+    _check_settings_review_pending,
     _run_checks,
     _skipped_manifest_check,
     _check_bridge_drift_no_manifest,

package/src/scripts/_cli/cmd_explain.ts

@@ -3,8 +3,8 @@
  * `agent-config explain` — print the decision chain behind an outcome
  * (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_explain.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_explain.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output. No behaviour changes — latent quirks are replicated, not fixed.
  *

package/src/scripts/_cli/cmd_export.ts

@@ -2,8 +2,8 @@
  * `agent-config export` — eject a tool's canonical content into the project
  * (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_export.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_export.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same filesystem effects. No behaviour changes; latent quirks are
  * replicated and flagged inline, not fixed.
@@ -19,7 +19,7 @@
  *   and never calls `process.exit()`. argparse usage errors throw
  *   `ArgparseExit(2)`; `-h`/`--help` throws `ArgparseExit(0)`.
  * - The 9 marker constants and templates resolve to the same byte content as
- *   the Python originals: marker constants are re-exported from the
+ *   the retired Python implementations: marker constants are re-exported from the
  *   `install.ts` twin (single source of truth); templates are read from
  *   `dist/agent-src/templates` via `_from_template` exactly as Python does.
  * - `hashlib.sha256(content.encode("utf-8")).hexdigest()` →

package/src/scripts/_cli/cmd_fleet.ts

@@ -43,7 +43,19 @@ export interface FleetRepo {
     readonly tools?: string;
 }
 
-/** Parsed fleet config. */
+/**
+ * Parsed fleet config.
+ *
+ * INPUT-SCHEMA STABILITY: **stable, v1** (marked 2026-07-08,
+ * road-to-truth-and-reference-hygiene P3 — the output report was versioned
+ * from day one via {@link FleetReport.schema_version}; the input contract
+ * deserves the same explicitness). The accepted `fleet.yaml` shape is
+ * `repos: [<path-string> | {path, tools?}]` + optional `max_concurrency`;
+ * unknown keys are IGNORED (tolerant reader — forward-compatible by
+ * construction). Additive optional keys bump nothing; a breaking key
+ * rename/removal or semantics change requires an explicit `schema_version`
+ * field in the input and a reader that accepts the versionless v1 form.
+ */
 export interface FleetSpec {
     readonly repos: readonly FleetRepo[];
     readonly maxConcurrency: number;

package/src/scripts/_cli/cmd_migrate.ts

@@ -2,8 +2,8 @@
  * `agent-config migrate` — one-shot, opinionated migration off every legacy
  * install / state shape (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_migrate.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_migrate.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same filesystem effects. No behaviour changes — latent quirks are
  * replicated and flagged inline, not fixed.
@@ -82,7 +82,7 @@ import { resolve_project_root } from '../_lib/agent_settings.js';
 // specifier into the uncompiled template tree (`.ts` only) and crash the whole
 // CLI at module load — breaking every command (e.g. `agent-config init`).
 // `_load_state_migrator` spawns it via tsx instead (the install orchestrator
-// pattern), keeping the migrator lazy like the Python original.
+// pattern), keeping the migrator lazy like the retired Python implementation.
 
 const PACKAGE_NAME_NPM = '@event4u/agent-config';
 const PACKAGE_NAME_COMPOSER = 'event4u/agent-config';

package/src/scripts/_cli/cmd_prune.ts

@@ -1,8 +1,8 @@
 /**
  * `agent-config prune` — remove orphaned project bridge markers (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_prune.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_prune.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same filesystem effects. No behaviour changes — latent quirks are
  * replicated and flagged inline, not fixed.

package/src/scripts/_cli/cmd_refresh.ts

@@ -3,8 +3,8 @@
  * `agent-config refresh` — idempotent re-install, no version change
  * (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_refresh.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_refresh.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same filesystem effects, same subprocess argv/cwd/env. No behaviour
  * changes — latent quirks are replicated and flagged inline, not fixed.
@@ -145,7 +145,7 @@ const CONSUMER_BRIDGE_MARKER_RELPATH = path.join('agents', '.event4u-bridge.yml'
  * agent-config package source tree. Shared by the bridge-marker writer guard
  * and the `_is_source_repo` monorepo probe so the literal lives in one place
  * (the only other textual mention is the `_is_source_repo` docstring, matching
- * the Python original's two occurrences for the ADR-051 path-count parity).
+ * the retired Python implementation's two occurrences for the ADR-051 path-count parity).
  */
 const SRC_MARKER_DIR = '.agent-src.uncondensed';
 
@@ -215,7 +215,7 @@ function atomicWrite0644(target: string, body: string, prefix: string): void {
 }
 
 /**
- * Twin of `install._write_consumer_bridge_marker` (module-private). Returns the
+ * Mirrors `install._write_consumer_bridge_marker` (module-private). Returns the
  * written path, or `null` when skipped (dev mode / source repo).
  */
 function _write_consumer_bridge_marker(

package/src/scripts/_cli/cmd_settings_check.ts

@@ -2,8 +2,8 @@
  * `agent-config settings:check` — validate `.agent-settings.yml` against the
  * supported YAML subset (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_settings_check.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_settings_check.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output. Read-only — no filesystem mutation, no network. No behaviour
  * changes; latent quirks are replicated and flagged inline, not fixed.

package/src/scripts/_cli/cmd_settings_migrate.ts

@@ -2,8 +2,8 @@
  * `agent-config settings:migrate` — lift project-local settings into the
  * global store (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_settings_migrate.py` (ADR-200,
- * py2ts migration). The CLI contract mirrors the Python original EXACTLY —
+ * Ported from the retired Python `src/scripts/_cli/cmd_settings_migrate.py` (ADR-200,
+ * py2ts migration). The CLI contract pins the historical contract exactly —
  * same flags, same exit codes, same stdout/stderr split, byte-identical
  * emitted output, same filesystem effects. No behaviour changes; latent quirks
  * are replicated and flagged inline, not fixed.

package/src/scripts/_cli/cmd_sync.ts

@@ -2,8 +2,8 @@
  * `agent-config sync` — replay the installed-tools manifest (ADR-008)
  * (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_sync.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_sync.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same installer invocation. No behaviour changes; latent quirks are
  * replicated and flagged inline, not fixed.

package/src/scripts/_cli/cmd_uninstall.ts

@@ -1,8 +1,8 @@
 /**
  * `agent-config uninstall` — remove bridge markers (Phase 4.1) (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_uninstall.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_uninstall.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same filesystem effects. No behaviour changes — latent quirks are
  * replicated and flagged inline, not fixed.

package/src/scripts/_cli/cmd_update.ts

@@ -2,8 +2,8 @@
  * `agent-config update` — explicit, opt-in update of the version pin
  * (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_update.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_update.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same filesystem effects, same subprocess argv/cwd/env. No behaviour
  * changes — latent quirks are replicated and flagged inline, not fixed.
@@ -140,23 +140,23 @@ function _splitlinesKeepends(text: string): string[] {
 // Replicated module-private helpers (see header parity note)
 // ---------------------------------------------------------------------------
 
-/** Twin of `agent_settings._canonical_settings_path` (file-local private). */
+/** Mirrors `agent_settings._canonical_settings_path` (file-local private). */
 function _canonical_settings_path(project_root: string): string {
     return path.join(project_root, ...LOCAL_PROJECT_SUBDIR, DEFAULT_PROJECT_FILE);
 }
 
-/** Twin of `agent_settings._local_settings_path` (file-local private). */
+/** Mirrors `agent_settings._local_settings_path` (file-local private). */
 function _local_settings_path(project_root: string): string {
     return path.join(project_root, ...LOCAL_PROJECT_SUBDIR, LOCAL_PROJECT_FILE);
 }
 
-/** Twin of `agent_settings._resolve` — absolute, normalised path. */
+/** Mirrors `agent_settings._resolve` — absolute, normalised path. */
 function _resolve(p: string): string {
     return path.resolve(p);
 }
 
 /**
- * Twin of `agent_settings._resolve_cascade_paths` (file-local private).
+ * Mirrors `agent_settings._resolve_cascade_paths` (file-local private).
  *
  * Returns the ordered cascade of in-project settings files (shallow → deep).
  */
@@ -199,7 +199,7 @@ function _resolve_cascade_paths(cwd: string | null, project_path: string | null)
     return out;
 }
 
-/** Twin of `update_check._read_state` (module-private). */
+/** Mirrors `update_check._read_state` (module-private). */
 function _read_state(state_path: string): Record<string, unknown> {
     try {
         const raw = fs.readFileSync(state_path, 'utf-8');
@@ -213,7 +213,7 @@ function _read_state(state_path: string): Record<string, unknown> {
     return {};
 }
 
-/** Twin of `update_check._write_state` (module-private). */
+/** Mirrors `update_check._write_state` (module-private). */
 function _write_state(state_path: string, payload: Record<string, unknown>): void {
     const parent = path.dirname(state_path);
     fs.mkdirSync(parent, { recursive: true });

package/src/scripts/_cli/cmd_upgrade.ts

@@ -3,8 +3,8 @@
  * `agent-config upgrade` — fetch + install the latest global binary + refresh
  * (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_upgrade.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_upgrade.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same filesystem effects, same subprocess argv/cwd/env. No behaviour
  * changes — latent quirks are replicated and flagged inline, not fixed.
@@ -644,7 +644,8 @@ export async function main(argv: string[] | null = null, options: MainOptions =
     _print(
         out,
         '✅  agent-config upgraded' +
-            (doctor_rc === 0 ? ' — doctor green.' : ' — review the doctor findings above.'),
+            (doctor_rc === 0 ? ' — doctor green.' : ' — review the doctor findings above.') +
+            ' Tune settings any time with `agent-config config`.',
     );
     return 0;
 }

package/src/scripts/_cli/cmd_validate.ts

@@ -3,8 +3,8 @@
  * `agent-config validate` — drift detection for the installed-tools manifest
  * (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_validate.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_validate.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same filesystem semantics. No behaviour changes — latent quirks are
  * replicated, not fixed.
@@ -77,7 +77,7 @@ class ArgparseExit extends Error {
 /**
  * `pathlib.Path(p)` string form — collapse repeated separators and strip a
  * trailing separator (Python `str(Path("~/.cursor/"))` → `~/.cursor`), keeping
- * a lone root `/`. Mirrors how the Python original wraps every marker/anchor in
+ * a lone root `/`. Mirrors how the retired Python implementation wraps every marker/anchor in
  * `Path(...)` before `str()`-ing it into a message.
  */
 function pyPathStr(p: string): string {

package/src/scripts/_cli/cmd_versions.ts

@@ -1,8 +1,8 @@
 /**
  * `agent-config versions` — list available package versions (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/_cli/cmd_versions.py` (ADR-200, py2ts
- * migration). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/_cli/cmd_versions.py` (ADR-200, py2ts
+ * migration). The CLI contract pins the historical contract exactly — same
  * flags, same exit codes, same stdout/stderr split, byte-identical emitted
  * output, same subprocess invocation. Read-only (queries npm; never mutates).
  * No behaviour changes; latent quirks are replicated and flagged inline.