@event4u/agent-config 8.4.0 → 8.5.0

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.

package/src/scripts/_cli/explain_last/assumptions.ts

@@ -1,8 +1,8 @@
 /**
  * Resolve the `assumptions` why-slot for the trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/assumptions.py`
- * (ADR-200). Behaviour mirrors the Python original EXACTLY — same string /
+ * Ported from the retired Python `src/scripts/_cli/explain_last/assumptions.py`
+ * (ADR-200). Behaviour pins the historical contract exactly — same string /
  * dict normalisation, same 120-code-point id slice, same `or`-fallback
  * order, same always-array return. No behaviour changes.
  *

package/src/scripts/_cli/explain_last/council.ts

@@ -1,8 +1,8 @@
 /**
  * Resolve the `council` why-slot for the trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/council.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same candidate glob,
+ * Ported from the retired Python `src/scripts/_cli/explain_last/council.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same candidate glob,
  * same ±1h run window, same most-recent pick, same member extraction
  * (first stripped line, 200-code-point slice), and the same deliberate
  * omission of cost-metadata fields. No behaviour changes.

package/src/scripts/_cli/explain_last/halt.ts

@@ -1,8 +1,8 @@
 /**
  * Builder for the `trace.halt` slot.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/halt.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same `halts[-1]` pick,
+ * Ported from the retired Python `src/scripts/_cli/explain_last/halt.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same `halts[-1]` pick,
  * same `None` branches, same scrub passes, same `step` empty-string
  * fallback. No behaviour changes.
  *

package/src/scripts/_cli/explain_last/index.ts

@@ -1,8 +1,8 @@
 /**
  * `agent-config explain last` — execution-trace builder.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/__init__.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same subject derivation,
+ * Ported from the retired Python `src/scripts/_cli/explain_last/__init__.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same subject derivation,
  * same run-id derivation (with the UTC-mtime ISO fallback), same slot
  * aggregation order and key shape, same scrub pass on the run id. No
  * behaviour changes.

package/src/scripts/_cli/explain_last/inputs.ts

@@ -1,8 +1,8 @@
 /**
  * Resolve the `inputs` and `pack` why-slots for the trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/inputs.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same resolver reuse,
+ * Ported from the retired Python `src/scripts/_cli/explain_last/inputs.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same resolver reuse,
  * same `None`-on-error branches, same per-knob source attribution, same
  * pack-marker discovery order and key shape. No behaviour changes.
  *
@@ -30,9 +30,9 @@ const _SILENCED_LOGGERS: readonly string[] = [
 ];
 
 /**
- * Faithful twin of the Python `_silence_resolver_warnings` context manager.
+ * Port of the retired Python `_silence_resolver_warnings` context manager.
  *
- * The Python original raises the level of the `scripts.config.profiles` /
+ * the retired Python implementation raises the level of the `scripts.config.profiles` /
  * `scripts.config.presets` loggers to ERROR so a profile/preset read
  * failure does not leak an absolute path on stderr. The TypeScript config
  * twins funnel through a single shared `agent_settings.logger` that only

package/src/scripts/_cli/explain_last/memory.ts

@@ -1,8 +1,8 @@
 /**
  * Resolve the `memory` why-slot for the trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/memory.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same two sources, same
+ * Ported from the retired Python `src/scripts/_cli/explain_last/memory.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same two sources, same
  * coercion order, same `float()` semantics, same `None`-on-empty branch.
  * No behaviour changes.
  *

package/src/scripts/_cli/explain_last/provider.ts

@@ -1,8 +1,8 @@
 /**
  * Builder for the `trace.provider` slot.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/provider.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same video-only gate,
+ * Ported from the retired Python `src/scripts/_cli/explain_last/provider.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same video-only gate,
  * same `video_provider` / `contract.video_provider` extraction order, same
  * `None` branches, same scrub passes. No behaviour changes.
  *

package/src/scripts/_cli/explain_last/render.ts

@@ -1,8 +1,8 @@
 /**
  * Deterministic Markdown projection of an `ExplainTrace`.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/render.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same fixed section
+ * Ported from the retired Python `src/scripts/_cli/explain_last/render.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same fixed section
  * order, same skip-empty-chunk join, same `rstrip()` + trailing newline,
  * same tip-footer text and `with_footer` gate. No behaviour changes.
  *

package/src/scripts/_cli/explain_last/route.ts

@@ -1,8 +1,8 @@
 /**
  * Resolve the `route` why-slot for the trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/route.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same router lookup, same
+ * Ported from the retired Python `src/scripts/_cli/explain_last/route.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same router lookup, same
  * `None`-on-missing-router branch, same scrub passes, same key shape. No
  * behaviour changes.
  *

package/src/scripts/_cli/explain_last/scrubber.ts

@@ -1,8 +1,8 @@
 /**
  * PII / cost-metadata scrubber for the `explain last` trace.
  *
- * TypeScript twin of `src/scripts/_cli/explain_last/scrubber.py` (ADR-200).
- * Behaviour mirrors the Python original EXACTLY — same regex sources, same
+ * Ported from the retired Python `src/scripts/_cli/explain_last/scrubber.py` (ADR-200).
+ * Behaviour pins the historical contract exactly — same regex sources, same
  * resolution order, same idempotence, same long-string threshold and
  * summary text. No behaviour changes — latent bugs are replicated, not
  * fixed.

package/src/scripts/_cli/explain_last/sections/assumptions.ts

@@ -1,9 +1,9 @@
 /**
  * Render the `Assumptions` section.
  *
- * TypeScript twin of
+ * Ported from the retired Python
  * `src/scripts/_cli/explain_last/sections/assumptions.py` (ADR-200).
- * Byte-identical to the Python original — note the DOUBLE space before the
+ * byte-stable — downstream consumers and checksum gates pin these bytes — note the DOUBLE space before the
  * em-dash in the item line (`{ident}  — recorded`). No behaviour changes.
  */