@event4u/agent-config 8.4.0 → 8.5.0

package/src/scripts/release.ts

@@ -2,8 +2,8 @@
 /**
  * End-to-end release automation for `event4u/agent-config` (TypeScript twin).
  *
- * TypeScript twin of `src/scripts/release.py` (ADR-200, py2ts migration).
- * The CLI contract mirrors the Python original EXACTLY — same flags, same
+ * Ported from the retired Python `src/scripts/release.py` (ADR-200).
+ * The CLI contract pins the historical contract exactly — same flags, same
  * exit codes, same stdout/stderr split, byte-identical emitted output, same
  * subprocess argv/cwd/env. No behaviour changes — latent quirks are
  * replicated and flagged inline, not fixed.
@@ -145,7 +145,7 @@ class ArgparseExit extends Error {
 
 /**
  * Mirror of `subprocess.CalledProcessError`. Thrown by `run()` when a command
- * fails with `check=True` and output is NOT captured — the Python original
+ * fails with `check=True` and output is NOT captured — the retired Python implementation
  * lets `CalledProcessError` propagate in that path. The CLI entry guard does
  * NOT catch this, so it surfaces (non-zero exit + traceback), matching Python.
  */
@@ -680,7 +680,7 @@ function latest_tag(): string | null {
  *
  * `test_trend_line` — optional pre-computed `Tests: N (+M …)` footer
  * (road-to-feedback-followups P3.2). Computed by the caller so tests don't
- * trigger a recursive pytest collection.
+ * trigger a recursive vitest collection.
  */
 function render_changelog_entry(
     version: string,
@@ -770,32 +770,40 @@ function _changelog_line(c: Commit): string {
 // ─── test-count trend (road-to-feedback-followups P3.2) ───────────────────────
 
 const _TEST_COUNT_LINE_RE = /^Tests:\s+(\d+)/m;
-const _PYTEST_COLLECTED_RE = /^(\d+)\s+tests?\s+collected/m;
 
 /**
- * Return the count from `pytest --collect-only -q` on the current tree.
- * Returns null when pytest isn't available or collection fails — the trend
- * line is informational, never a release blocker.
+ * Return the collected vitest test-case count on the current tree
+ * (`npx vitest list`, one line per case; ~14s wall). Returns null when
+ * collection fails — the trend line is informational, never a release
+ * blocker. (Replaced the dead `pytest --collect-only` probe on 2026-07-08,
+ * road-to-truth-and-reference-hygiene Phase 3: the Python suite was retired
+ * with ADR-200, so the old probe always degraded to null and the `Tests:`
+ * footer silently vanished from release notes.)
  */
 function _count_tests_current(): number | null {
-    // Release-time pytest-collection probe: python-test-tooling, not package
-    // runtime — there is no tsx equivalent of pytest collection. Degrades to
-    // null (informational trend line dropped) when python3/pytest is absent.
-    const res = spawnSync('python3', ['-m', 'pytest', '--collect-only', '-q'], {
+    // Recursion/cost guard: `npx vitest list` inside a vitest-driven release
+    // test would collect the whole suite from within the suite (the child
+    // inherits VITEST=… from the runner) — the exact recursion the caller
+    // comment warns about. Degrade to null there, same as any other
+    // collection failure.
+    if (process.env['VITEST'] !== undefined) {
+        return null;
+    }
+    const res = spawnSync('npx', ['vitest', 'list'], {
         cwd: REPO_ROOT,
         encoding: 'utf-8',
         stdio: ['ignore', 'pipe', 'pipe'],
-        timeout: 120_000,
+        timeout: 180_000,
     });
     if (res.error) {
-        // FileNotFoundError (ENOENT) or TimeoutExpired (ETIMEDOUT) → None.
+        // ENOENT or ETIMEDOUT → null (informational line dropped).
         return null;
     }
     if ((res.status ?? 1) !== 0) {
         return null;
     }
-    const match = _PYTEST_COLLECTED_RE.exec(res.stdout ?? '');
-    return match ? Number.parseInt(match[1] as string, 10) : null;
+    const lines = (res.stdout ?? '').split('\n').filter((l) => l.trim().length > 0);
+    return lines.length > 0 ? lines.length : null;
 }
 
 /**
@@ -1833,7 +1841,10 @@ function main(argv: readonly string[] | null = null): number {
     }
 
     const today = todayIso();
-    const test_trend_line = _render_test_trend_line(prev);
+    // Dry-run stays fast: the trend line costs a full vitest collection
+    // (~15s+), which `--dry-run exits 0 without needing …` contracts (and
+    // the release test) assume never runs. Real releases compute it.
+    const test_trend_line = args.dry_run ? null : _render_test_trend_line(prev);
     const [full, body] = render_changelog_entry(target, prev, commits, today, {
         test_trend_line,
     });
@@ -1922,8 +1933,8 @@ if (_isCliEntry() || process.argv[1] === _HERE) {
     try {
         // main() can return an int directly OR throw SystemExitError via die();
         // both flow into process.exitCode. CalledProcessError is intentionally
-        // NOT caught here, so it propagates (non-zero + traceback), matching the
-        // Python original letting subprocess.CalledProcessError raise.
+        // NOT caught here, so it propagates (non-zero + traceback) — the historical
+        // contract let subprocess errors raise.
         process.exitCode = main(process.argv.slice(2));
     } catch (e) {
         if (e instanceof SystemExitError || e instanceof ArgparseExit) {

package/src/scripts/render_benchmark_md.ts

@@ -2,7 +2,7 @@
 /**
  * Render `docs/benchmark.md` from the latest paired A/B bench reports.
  *
- * TypeScript twin of `src/scripts/render_benchmark_md.py` (ADR-200, Phase 8 /
+ * Ported from the retired Python `src/scripts/render_benchmark_md.py` (ADR-200, Phase 8 /
  * Wave 8b). Mirrors the CLI contract EXACTLY — the `--quiet` flag, exit code,
  * the stdout/stderr split, byte-identical stdout AND byte-identical rendered
  * `docs/benchmark.md`. The renderer is deterministic — it does not run any
@@ -15,7 +15,7 @@
  * If no reports exist yet, the script writes a placeholder document — never
  * errors out, so the file is always a real description of the bench state.
  *
- * No behaviour changes — latent Python quirks replicated. The only volatile
+ * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour. The only volatile
  * value is the embedded `utc_iso()` timestamp; golden parity for this script
  * pins on structure + the deterministic placeholder/report shape, not on the
  * second-precision timestamp.

package/src/scripts/render_value_md.ts

@@ -2,7 +2,7 @@
 /**
  * Render `docs/value.md` from the latest `value-v1` JSON report.
  *
- * TypeScript twin of `src/scripts/render_value_md.py` (ADR-200, Phase 8
+ * Ported from the retired Python `src/scripts/render_value_md.py` (ADR-200, Phase 8
  * / Wave 8b). The public surface and rendered output mirror the Python
  * original EXACTLY — same module-level path constants (exposed through a
  * mutable test seam so the pytest `monkeypatch.setattr` injection ports
@@ -412,7 +412,7 @@ function render_placeholder(): string {
 /**
  * Mirror `Path.relative_to(REPO_ROOT)` — throws when `p` is NOT under the
  * repo root (Python `ValueError`). The default `OUT_PATH` is always in-repo
- * (`docs/value.md`); replicated for fidelity with the Python original.
+ * (`docs/value.md`); replicated for fidelity with the retired Python implementation.
  */
 function _relativeToRepo(p: string): string {
     const abs = path.resolve(p);

package/src/scripts/roadmap_progress_hook.ts

@@ -2,7 +2,7 @@
 /**
  * Platform-agnostic PostToolUse hook for the `roadmap-progress-sync` rule.
  *
- * TypeScript twin of `src/scripts/roadmap_progress_hook.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/roadmap_progress_hook.py` (ADR-200 —
  * Python→TS migration, Phase 6 / hooks). Public API mirrors the Python
  * module exactly (snake_case kept deliberately — fidelity over TS idiom).
  *

package/src/scripts/router_telemetry.ts

@@ -2,7 +2,7 @@
 /**
  * Local replay of the router against a corpus — pure, no API spend.
  *
- * TypeScript twin of `src/scripts/router_telemetry.py` (ADR-089 —
+ * Ported from the retired Python `src/scripts/router_telemetry.py` (ADR-089 —
  * Python→TS migration, Phase 7). Mirrors the Python CLI contract
  * exactly: flags (`--corpus`, `--sample-cap`, `--profile`, `--out`,
  * `--quiet`), exit codes, stdout/stderr split, byte-identical messages,

package/src/scripts/run_skill_evals.ts

@@ -2,8 +2,8 @@
 /**
  * Quantitative skill-eval orchestrator (skill-writing § 7).
  *
- * TypeScript twin of `src/scripts/run_skill_evals.py` (ADR-200 — Python→TS
- * migration, Phase 8 / Wave 8e). The CLI contract is mirrored EXACTLY:
+ * Ported from the retired Python `src/scripts/run_skill_evals.py` (ADR-200 — Python→TS
+ * migration, Phase 8 / Wave 8e). The CLI contract is pinned:
  * same subcommands (`scaffold`, `aggregate`, `report`), same flags
  * (`--run`), same exit codes (0 success; 1 on `sys.exit(msg)` errors),
  * same byte-identical stdout / stderr prose and byte-identical written

package/src/scripts/runtime_dispatcher.ts

@@ -2,7 +2,7 @@
 /**
  * Runtime Dispatcher — resolves execution type and drives real handler execution.
  *
- * TypeScript twin of `src/scripts/runtime_dispatcher.py` (ADR-200). Mirrors the
+ * Ported from the retired Python `src/scripts/runtime_dispatcher.py` (ADR-200). Mirrors the
  * Python public surface and CLI contract EXACTLY — `ExecutionRequest`,
  * `DispatchResult`, `dispatch`, `run`, the `resolve` / `run` subcommands, the
  * legacy flat `--skill` flag, `--format text|json`, `--root`, `--cwd`,

package/src/scripts/runtime_handler.ts

@@ -2,7 +2,7 @@
 /**
  * Runtime Handler — executes a skill's declared command and captures the result.
  *
- * TypeScript twin of `src/scripts/runtime_handler.py` (ADR-200, Phase 8 /
+ * Ported from the retired Python `src/scripts/runtime_handler.py` (ADR-200, Phase 8 /
  * Wave 8h). Library module imported by the still-Python `runtime_dispatcher`
  * (the `.py` stays in place); this `.ts` twin sits beside it. Mirrors the
  * Python public surface EXACTLY — `DEFAULT_ENV_ALLOWLIST`, `ExecutionResult`,

package/src/scripts/runtime_registry.ts

@@ -2,8 +2,8 @@
 /**
  * Runtime Registry — discovers skills with execution metadata.
  *
- * TypeScript twin of `src/scripts/runtime_registry.py` (ADR-200, Phase 8 /
- * Wave 8h). Mirrors the Python CLI contract EXACTLY — `--root`, `--format`
+ * Ported from the retired Python `src/scripts/runtime_registry.py` (ADR-200, Phase 8 /
+ * Wave 8h). The CLI contract is pinned — `--root`, `--format`
  * (text|json), `--validate` flags, exit codes (0 ok / valid, 1 invalid),
  * byte-identical stdout/stderr, and byte-identical `json.dumps(indent=2)`
  * output. No behaviour changes.
@@ -18,7 +18,7 @@
  *     tsx scripts/runtime_registry.ts [--root ROOT] [--format text|json]
  *
  * Library role: `runtime_dispatcher.py` imports `SkillRuntime` and
- * `build_registry` from the Python original — the `.py` stays in place so the
+ * `build_registry` from the retired Python implementation — the `.py` stays in place so the
  * still-Python dispatcher keeps importing it. This `.ts` twin sits beside it.
  *
  * Imports the SAME primitives the `.py` imports from `skill_linter`:

package/src/scripts/score_skill_selection.ts

@@ -2,7 +2,7 @@
 /**
  * Selection-accuracy scorer (council file 05, Phase 2.2).
  *
- * TypeScript twin of `src/scripts/score_skill_selection.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/score_skill_selection.py` (ADR-200 —
  * Python→TS migration, Phase 8 / Wave 8c). Mirrors the CLI contract EXACTLY:
  * flags (`--predictions`, `--baseline`, `--source`, `--out`), exit codes
  * (0 / 2 when neither --predictions nor --baseline given), byte-identical

package/src/scripts/security_audit_config.ts

@@ -1,6 +1,6 @@
 // P3.1 — consumer-facing agent-config security audit (road-to-security-pillar.md).
 //
-// TypeScript twin of `src/scripts/security_audit_config.py` (ADR-200 —
+// Ported from the retired Python `src/scripts/security_audit_config.py` (ADR-200 —
 // Python→TS migration). Behaviour mirrors the Python module byte-for-byte.
 //
 // Points the Phase-1 detection logic at a *consumer's assembled* agent config —
@@ -101,7 +101,7 @@ function _category(f: sl.Finding): string {
  * traversal *structure* (component recursion, `**` self-then-subdirs depth-first,
  * `is_file` filter, first-seen dedup) is replicated faithfully; intra-directory
  * entry order follows `fs.readdirSync`. Multi-file-per-pattern consumer trees can
- * therefore differ in finding order from the Python original on platforms where
+ * therefore differ in finding order from the retired Python implementation on platforms where
  * scandir != readdir. The golden test pins one-file-per-pattern fixtures so the
  * order is unambiguous; the clean real-`src/` path emits no findings.
  */

package/src/scripts/skill_collision_clusters.ts

@@ -2,7 +2,7 @@
 /**
  * Skill-collision cluster analysis (Phase 2.2 of step-1-v2-feedback-followup).
  *
- * TypeScript twin of `skill_collision_clusters.py` (Phase 8 / Wave 8e).
+ * Ported from the retired Python `skill_collision_clusters.py` (Phase 8 / Wave 8e).
  *
  * Walks `.agent-src.uncondensed/skills/<id>/SKILL.md`, extracts the
  * `description` frontmatter, computes pairwise keyword overlap, and groups

package/src/scripts/skill_discovery.ts

@@ -2,7 +2,7 @@
 /**
  * Skill discovery recommender — local-only, explained, no network.
  *
- * TypeScript twin of `skill_discovery.py` (Phase 8 / Wave 8e).
+ * Ported from the retired Python `skill_discovery.py` (Phase 8 / Wave 8e).
  *
  * Phase 3 of `road-to-leaner-core-and-discovery`. Turns existing local signals
  * (skill catalog frontmatter, role shortlists, optional local-analytics JSONL)

package/src/scripts/skill_linter.ts

@@ -2,16 +2,16 @@
 /**
  * skill_linter.ts — minimal skill/rule linter for agent-config repositories.
  *
- * TypeScript twin of `src/scripts/skill_linter.py` (ADR-200, Phase 4 Wave 4a).
+ * Ported from the retired Python `src/scripts/skill_linter.py` (ADR-200).
  * The public CLI contract is mirrored EXACTLY: same flags (`--all`,
  * `--changed`, `--format`, `--pairs`, `--duplicates`, `--condensation-quality`,
  * `--strict-warnings`, `--report`, `--repo-root`, `--quiet`, positional paths),
  * same exit codes (0 pass / 1 warn-with-strict / 2 fail / 3 malice-or-internal),
- * same stdout/stderr split, and byte-for-byte finding messages. No behaviour
- * changes — latent Python quirks are replicated.
+ * same stdout/stderr split, and byte-for-byte finding messages (pinned by tests). No behaviour
+ * changes — historical quirks are preserved.
  *
  * Dependencies: imports the `validate_frontmatter` twin (local, ported because
- * the Python original is a later-wave dependency) and the `_lib/agent_src`
+ * the retired Python implementation is a later-wave dependency) and the `_lib/agent_src`
  * twin for multi-root artefact resolution.
  *
  * MVP checks:
@@ -1136,8 +1136,9 @@ function _stripWing3CarveOuts(text: string): string {
     // `## Do NOT` strip: Python uses MULTILINE|DOTALL → `^##` matches at every
     // line start. `\Z` = end of string (no trailing-newline subtlety needed).
     out = out.replace(/^##\s+Do NOT\s*$[\s\S]*?(?=^##\s+|$(?![\s\S]))/gm, '');
-    // `**WHEN NOT to use this**` strip — LATENT PYTHON BUG REPLICATED: the
-    // Python original passes only DOTALL|IGNORECASE (NO MULTILINE), so the
+    // `**WHEN NOT to use this**` strip — HISTORICAL PYTHON-ERA BUG, PRESERVED
+    // (goldens pin it): the retired implementation passed only
+    // DOTALL|IGNORECASE (NO MULTILINE), so the
     // `^##\s+` alternative in its lookahead matches only at string position 0,
     // never at a mid-text line start. With no `**WHEN` after the first one, the
     // non-greedy `.*?` therefore consumes to end-of-string — stripping every
@@ -2781,7 +2782,7 @@ function lint_execution_quality(p: string, text: string): Issue[] {
     const hasVerificationSection = sectionHeadersLower.some((h) =>
         ['verify', 'validat', 'test', 'acceptance', 'quality gate'].some((kw) => h.includes(kw)),
     );
-    // hasAntipatternSection computed in the Python original but never used downstream.
+    // hasAntipatternSection computed in the retired Python implementation but never used downstream.
     void sectionHeadersLower.some((h) =>
         ['do not', "don't", 'gotcha', 'anti-pattern', 'avoid'].some((kw) => h.includes(kw)),
     );

package/src/scripts/skill_overlap.ts

@@ -2,9 +2,9 @@
 /**
  * Structural overlap detection across skills (description + triggers).
  *
- * TypeScript twin of `src/scripts/skill_overlap.py` (ADR-200, Phase 8 /
+ * Ported from the retired Python `src/scripts/skill_overlap.py` (ADR-200, Phase 8 /
  * Wave 8b). The public surface, CLI contract, exit codes, stderr text,
- * stdout text, and rendered markdown mirror the Python original EXACTLY
+ * stdout text, and rendered markdown mirror the retired Python implementation EXACTLY
  * — same custom frontmatter parser, same tokenizer + stopword set, same
  * symbol-path regex, same Jaccard math with `round(x, 3)` banker's
  * rounding, same thresholds, same `combinations` pair order, same sort

package/src/scripts/skill_preview.ts

@@ -2,7 +2,7 @@
 /**
  * Skill preview — non-destructive "what will this skill do?" summary.
  *
- * TypeScript twin of `src/scripts/skill_preview.py` (ADR-200 — Python→TS
+ * Ported from the retired Python `src/scripts/skill_preview.py` (ADR-200 — Python→TS
  * migration, Phase 8 / Wave 8e). Public surface mirrors the Python module
  * exactly: `load_preview` / `render_plain` / `render_technical` / `PreviewError`,
  * the CLI flags (`name`, `--technical`, `--format text|json`), the exit codes

package/src/scripts/skill_tools/audit_persona_coverage.ts

@@ -2,8 +2,8 @@
 /**
  * Block D · D3 — audit_persona_coverage.
  *
- * TypeScript twin of `src/scripts/skill_tools/audit_persona_coverage.py`
- * (ADR-200, Phase 8 Wave 8h). Mirrors the Python CLI contract EXACTLY —
+ * Ported from the retired Python `src/scripts/skill_tools/audit_persona_coverage.py`
+ * (ADR-200, Phase 8 Wave 8h). The CLI contract is pinned —
  * flags (`--skills-dir`, `--personas-dir`, `--json`), exit code (0 always),
  * stdout split, byte-identical human table AND byte-identical JSON
  * (`json.dump(..., indent=2)`, ensure_ascii default).
@@ -23,7 +23,7 @@
  * Output: per-persona citation count + tier + status (ok / under-cited / orphan).
  * Exit code: 0 always (this is an advisory tool, not a CI gate).
  *
- * No behaviour changes — latent Python quirks replicated.
+ * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';

package/src/scripts/skill_tools/audit_user_type_coverage.ts

@@ -2,8 +2,8 @@
 /**
  * Block D · D3 — audit_user_type_coverage.
  *
- * TypeScript twin of `src/scripts/skill_tools/audit_user_type_coverage.py`
- * (ADR-200, Phase 8 Wave 8h). Mirrors the Python CLI contract EXACTLY —
+ * Ported from the retired Python `src/scripts/skill_tools/audit_user_type_coverage.py`
+ * (ADR-200, Phase 8 Wave 8h). The CLI contract is pinned —
  * flags (`--user-types-dir`, `--search-root`, `--json`), exit code (0
  * always), stdout split, byte-identical human table AND byte-identical JSON
  * (`json.dump(..., indent=2)`, ensure_ascii default).
@@ -27,7 +27,7 @@
  * Output: per-user-type reference count + status (ok / never-referenced /
  * orphan). Exit code: 0 always (advisory, not a CI gate).
  *
- * No behaviour changes — latent Python quirks replicated.
+ * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';

package/src/scripts/skill_tools/index.ts

@@ -1,7 +1,7 @@
 /**
  * Block D pilot tools for skill discovery and persona auditing.
  *
- * TypeScript twin of `src/scripts/skill_tools/__init__.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/skill_tools/__init__.py` (ADR-200,
  * Phase 8 Wave 8h). The Python package marker carries only a module
  * docstring; this index mirrors it as the package entry comment.
  *

package/src/scripts/skill_tools/run_block_d_eval.ts

@@ -2,8 +2,8 @@
 /**
  * Block D · D5 — eval gate runner.
  *
- * TypeScript twin of `src/scripts/skill_tools/run_block_d_eval.py`
- * (ADR-200, Phase 8 Wave 8h). Mirrors the Python CLI contract EXACTLY —
+ * Ported from the retired Python `src/scripts/skill_tools/run_block_d_eval.py`
+ * (ADR-200, Phase 8 Wave 8h). The CLI contract is pinned —
  * flags (`--skills-dir`, `--personas-dir`, `--corpus-dir`, `--json`), exit
  * codes (0 pass / 1 fail), stdout split, byte-identical human summary AND
  * byte-identical JSON (`json.dump(..., indent=2)`, ensure_ascii default).
@@ -21,7 +21,7 @@
  *
  * Pilot pass = ≥ 2 / 3 tools pass. Anything less → kill switch.
  *
- * No behaviour changes — latent Python quirks replicated.
+ * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';

package/src/scripts/skill_tools/score_skill_relevance.ts

@@ -2,8 +2,8 @@
 /**
  * Block D · D2 — score_skill_relevance.
  *
- * TypeScript twin of `src/scripts/skill_tools/score_skill_relevance.py`
- * (ADR-200, Phase 8 Wave 8h). Mirrors the Python CLI contract EXACTLY —
+ * Ported from the retired Python `src/scripts/skill_tools/score_skill_relevance.py`
+ * (ADR-200, Phase 8 Wave 8h). The CLI contract is pinned —
  * flags (`--task`, `--skills-dir`, `--top`, `--json`, `--sample`), exit
  * codes (0 / 2), stdout/stderr split, byte-identical human table AND
  * byte-identical JSON (`json.dump(..., indent=2)`, ensure_ascii default).
@@ -28,7 +28,7 @@
  *
  * Output: ranked list with integer scores 0–100, descending. Ties break on name.
  *
- * No behaviour changes — latent Python quirks replicated.
+ * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';

package/src/scripts/skill_tools/suggest_skill_for_task.ts

@@ -2,8 +2,8 @@
 /**
  * Block D · D4 — suggest_skill_for_task.
  *
- * TypeScript twin of `src/scripts/skill_tools/suggest_skill_for_task.py`
- * (ADR-200, Phase 8 Wave 8h). Mirrors the Python CLI contract EXACTLY —
+ * Ported from the retired Python `src/scripts/skill_tools/suggest_skill_for_task.py`
+ * (ADR-200, Phase 8 Wave 8h). The CLI contract is pinned —
  * flags (`--task`, `--skills-dir`, `--personas-dir`, `--top`, `--json`,
  * `--sample`), exit codes (0 / 2), stdout/stderr split, byte-identical
  * human output AND byte-identical JSON (`json.dump(..., indent=2)`,
@@ -22,7 +22,7 @@
  *
  * Output: ranked combos with `skill`, `score`, `personas[]`, and `why`.
  *
- * No behaviour changes — latent Python quirks replicated.
+ * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  */
 import * as path from 'node:path';
 import * as fs from 'node:fs';

package/src/scripts/skill_trigger_eval.ts

@@ -2,12 +2,12 @@
 /**
  * Skill trigger evaluation runner.
  *
- * TypeScript twin of `src/scripts/skill_trigger_eval.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/skill_trigger_eval.py` (ADR-200,
  * Phase 8 / Wave 8b). The public surface, CLI contract, exit codes,
  * stdout/stderr split, byte-for-byte messages, the on-disk key gate
  * (0600 + `sk-ant-` prefix), the controlling-terminal confirmation gate,
  * and the written JSON (Python `json.dumps(asdict(result), indent=2)` +
- * trailing newline) mirror the Python original EXACTLY. No behaviour
+ * trailing newline) mirror the retired Python implementation EXACTLY. No behaviour
  * changes.
  *
  * Design notes preserved:

package/src/scripts/skill_usage_collect.ts

@@ -2,7 +2,7 @@
 /**
  * Collect skill-activation signal from Claude Code session jsonl.
  *
- * TypeScript twin of `src/scripts/skill_usage_collect.py` (ADR-200, Phase 8 /
+ * Ported from the retired Python `src/scripts/skill_usage_collect.py` (ADR-200, Phase 8 /
  * Wave 8b). Mirrors the CLI contract EXACTLY — the `--project-slug`, `--out`,
  * `--quiet` flags, exit codes, the stdout/stderr split, byte-identical
  * messages AND the byte-identical appended JSONL (`json.dumps(rec,
@@ -16,7 +16,7 @@
  * Emits one JSONL record per (session, turn, slug, kind), append-only, deduped
  * on the (session_id, turn_idx, slug, kind) tuple.
  *
- * No behaviour changes — latent Python quirks replicated.
+ * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  */
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';

package/src/scripts/skill_usage_report.ts

@@ -2,9 +2,9 @@
 /**
  * Aggregate `agents/runtime/metrics/skill-usage.jsonl` into a per-skill report.
  *
- * TypeScript twin of `src/scripts/skill_usage_report.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/skill_usage_report.py` (ADR-200,
  * Phase 8 / Wave 8b). The public surface, CLI contract, exit code,
- * stdout text, and rendered markdown mirror the Python original EXACTLY
+ * stdout text, and rendered markdown mirror the retired Python implementation EXACTLY
  * — same record grouping, same 30-day window math, same status
  * classification, same known-slug discovery roots, same sort key, same
  * byte-for-byte report body. No behaviour changes.

package/src/scripts/smoke_path_resolution.ts

@@ -2,8 +2,8 @@
 /**
  * Smoke-test path resolution against the package's own `.augment/` projection.
  *
- * TypeScript twin of `src/scripts/smoke_path_resolution.py` (ADR-200, Phase 8
- * / Wave 8h). Mirrors the Python CLI contract EXACTLY — no flags, exit codes
+ * Ported from the retired Python `src/scripts/smoke_path_resolution.py` (ADR-200, Phase 8
+ * / Wave 8h). The CLI contract is pinned — no flags, exit codes
  * (0 all entries resolve, 1 one or more misses, 3 no `.augment/rules/`),
  * byte-identical stdout/stderr. No behaviour changes.
  *

package/src/scripts/smoke_quickstart.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env tsx
 /** Structural smoke-test for the README Quickstart path.
  *
- * TypeScript twin of `src/scripts/smoke_quickstart.py` (ADR-200, Phase 8 /
- * Wave 8h). Mirrors the Python CLI contract EXACTLY — no flags, exit codes
+ * Ported from the retired Python `src/scripts/smoke_quickstart.py` (ADR-200, Phase 8 /
+ * Wave 8h). The CLI contract is pinned — no flags, exit codes
  * (0 green, 1 one or more checks failed, 2 setup error), byte-identical
  * stdout/stderr (`::error::…` GitHub-annotation lines, the ✅/❌ summary). No
  * behaviour changes.
@@ -79,7 +79,7 @@ function _checkInstallerRuns(tmpdir: string): [number, string | null] {
     // ADR-020: --project is reserved for maintainers; CI is a maintainer context.
     const env = { ...process.env, AGENT_CONFIG_DEV_MODE: '1' };
     // Run the installer's `.ts` twin via the repo-local tsx binary (was
-    // `python3 install.py`; the Python original is deleted).
+    // `python3 install.py`; the retired Python implementation is deleted).
     const result = spawnSync(TSX_BIN, cmd, {
         encoding: 'utf-8',
         timeout: 60000,
@@ -128,7 +128,7 @@ function _checkDefaultProfile(settings: string): number {
  * the same parse the runtime uses: extract the `decision_engine` block from the
  * settings YAML, feed it to `parse()`, and assert the result is a
  * `DecisionEngineSettings`. A parser rejection is reported via `_fail` so the
- * `::error::` annotation matches the Python original's failure shape.
+ * `::error::` annotation matches the retired Python implementation's failure shape.
  */
 function _checkDecisionEngineBlock(settings: string): number {
     const parsed: unknown = parseYaml(fs.readFileSync(settings, 'utf-8'), { version: '1.1' });

package/src/scripts/snapshot_agent_outputs.ts

@@ -2,7 +2,7 @@
 /**
  * Snapshot the agent-config build outputs for byte-identity verification.
  *
- * TypeScript twin of `src/scripts/snapshot_agent_outputs.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/snapshot_agent_outputs.py` (ADR-200,
  * Phase 8 / Wave 8b). Mirrors the CLI contract EXACTLY — the `--out` flag,
  * exit codes, the stdout/stderr split, byte-identical stdout AND the
  * byte-identical written snapshot JSON (`json.dumps(indent=2,
@@ -22,7 +22,7 @@
  * `_SKIP_NAMES`) for `verify_physical_move.ts`, mirroring the Python
  * `from snapshot_agent_outputs import (...)`.
  *
- * No behaviour changes — latent Python quirks replicated.
+ * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  */
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';

package/src/scripts/spotcheck_thin_root.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env tsx
 /** Phase 6.6 platform spot-check via AI council.
  *
- * TypeScript twin of `src/scripts/spotcheck_thin_root.py` (ADR-200, Phase 8 /
+ * Ported from the retired Python `src/scripts/spotcheck_thin_root.py` (ADR-200, Phase 8 /
  * Wave 8h). Mirrors the Python contract — no flags, exit 0, the two
  * `Running … / ✅  Wrote …` stderr lines, and byte-identical written
  * `thin-root-platform-spotcheck.md` / `.json`. No behaviour changes.
@@ -73,7 +73,7 @@ interface ResponseRow {
 
 /**
  * Run the live council in-process via the `ai_council` TS twins. Returns the
- * council responses as plain rows. Mirrors the Python original's
+ * council responses as plain rows. Mirrors the retired Python implementation's
  * `consult(members, question, budget, table=table, rounds=1)` call exactly
  * (same members, prompt, max_tokens, budget). `table` + `rounds` ride in the
  * twin's `opts` argument.

package/src/scripts/surface-tiers.yml

@@ -35,6 +35,7 @@ clusters:
   ai_council: lab         # multi-model council orchestration, external API deps
   command_suggester: lab # context-aware command suggestion engine, pilot
   cost: lab              # cost tracking / budget gate (observability, Node .mjs)
+  mcp_exec: lab          # compiled safety envelope for MCP exec-tier tools (run_tests pilot)
   mcp_server: lab        # MCP stdio server, separate runtime, pilot distribution
   media: lab             # shared adapter substrate for ai-video / ai-image
   parity: lab            # py2ts parity rigs (compare / coverage-diff), migration tooling

package/src/scripts/sync_agent_settings.ts

@@ -2,7 +2,7 @@
 /**
  * Sync `.agent-settings.yml` against the template + profile (additive merge).
  *
- * TypeScript twin of `src/scripts/sync_agent_settings.py` (ADR-200).
+ * Ported from the retired Python `src/scripts/sync_agent_settings.py` (ADR-200).
  * Applies the section-aware merge rules documented in
  * `docs/guidelines/agent-infra/layered-settings.md`:
  *
@@ -32,7 +32,7 @@
  *     0 — already in sync, or changes applied (or --dry-run ran cleanly)
  *     2 — drift detected under --check, or invalid arguments / missing files
  *
- * No behaviour changes vs. the Python original — latent bugs replicated.
+ * No behaviour changes vs. the retired Python implementation — historical quirks preserved (consumers pin the exact behaviour).
  */
 
 import * as fs from 'node:fs';