@event4u/agent-config 8.4.1 → 8.5.0

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';

package/src/scripts/sync_github_metadata.ts

@@ -2,8 +2,8 @@
 /**
  * Sync `.github/topics.yml` + `.github/about.yml` to the GitHub repo.
  *
- * TypeScript twin of `src/scripts/sync_github_metadata.py` (ADR-200, Phase 5).
- * The CLI contract is mirrored EXACTLY — every flag (`--apply`, `--strict`,
+ * Ported from the retired Python `src/scripts/sync_github_metadata.py` (ADR-200).
+ * The CLI contract is pinned — every flag (`--apply`, `--strict`,
  * `--quiet`, `--repo`), exit codes (0 = synced / applied; 2 = drift under
  * `--strict` dry-run; 1 = error via SystemExit — missing token, unresolvable
  * repo, HTTP/transport error), the stdout/stderr split, byte-identical
@@ -14,7 +14,7 @@
  * against a stub with zero network. Error-swallowing is mirrored exactly:
  * any HTTP / transport failure raises `ExitError` → message to stderr, exit 1.
  *
- * No behaviour changes — latent Python quirks replicated. NOTE: the audit log
+ * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour. NOTE: the audit log
  * path mirrors the CODE constant (`agents/notes/visibility-sync-audit.md`),
  * not the docstring's `agents/evidence/notes/…` — DIVERGENCE CANDIDATE below.
  *
@@ -32,7 +32,7 @@ type Json = unknown;
 type JsonObject = Record<string, Json>;
 
 const _HERE = fileURLToPath(import.meta.url);
-// _HERE === <repo>/src/scripts/sync_github_metadata.ts ; the Python original
+// _HERE === <repo>/src/scripts/sync_github_metadata.ts ; the retired Python implementation
 // derives ROOT = <file>.parents[2] — two dirs up from src/scripts.
 export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 

package/src/scripts/sync_gitignore.ts

@@ -2,7 +2,7 @@
 /**
  * Sync the `event4u/agent-config` block in a project's `.gitignore`.
  *
- * TypeScript twin of `src/scripts/sync_gitignore.py` (ADR-200, Phase 5). The
+ * Ported from the retired Python `src/scripts/sync_gitignore.py` (ADR-200). The
  * CLI contract is mirrored EXACTLY — every flag (`--path`, `--template`,
  * `--dry-run`, `--replace`, `--cleanup-legacy`, `--quiet`), exit codes
  * (0 = no change / changed / dry-run; 2 = invalid args / template missing),
@@ -11,7 +11,7 @@
  * unified-diff format). Exported helpers keep their Python snake_case names so
  * the ported pytest suite can call them 1:1.
  *
- * No behaviour changes — latent Python quirks replicated.
+ * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * Reads the canonical block body from `src/config/gitignore-block.txt` and
  * ensures every managed entry is present in `.gitignore` between the
@@ -37,7 +37,7 @@ export const DEFAULT_GITIGNORE = '.gitignore';
 
 const _HERE = fileURLToPath(import.meta.url);
 // _HERE === <repo>/src/scripts/sync_gitignore.ts ; parents[2] of the .py file
-// is the repo root — two dirs up from src/scripts. The Python original derives
+// is the repo root — two dirs up from src/scripts. the retired Python implementation derives
 // DEFAULT_TEMPLATE = <file>.parent.parent.parent / "src" / "config" /
 // "gitignore-block.txt".
 export const DEFAULT_TEMPLATE = path.join(

package/src/scripts/sync_yaml_rt.ts

@@ -1,7 +1,7 @@
 /**
  * Round-trip YAML layer for `.agent-settings.yml` syncs.
  *
- * TypeScript twin of `src/scripts/sync_yaml_rt.py` (ADR-200). Self-
+ * Ported from the retired Python `src/scripts/sync_yaml_rt.py` (ADR-200). Self-
  * contained, zero-dependency. Implements a narrow YAML subset with the
  * property *user-line preservation*: every line in the user input that
  * `parse` attaches to a `Node` is reproduced character-for-character by
@@ -35,7 +35,7 @@
  *  - `heal_user_block(user, template) -> Node`
  *  - `sync(user_text, template_text) -> string`
  *
- * 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).
  */
 
 // --- Public node ----------------------------------------------------

package/src/scripts/telegraph_stats.ts

@@ -2,7 +2,7 @@
 /**
  * Telegraph per-session / per-conversation / lifetime token-delta lens.
  *
- * TypeScript twin of `src/scripts/telegraph_stats.py` (ADR-200 — Python→TS
+ * Ported from the retired Python `src/scripts/telegraph_stats.py` (ADR-200 — Python→TS
  * migration, Phase 8 / Wave 8e). Public surface mirrors the Python module
  * exactly: same CLI flags (`--input`, `--format`), same exit code (0), same
  * stdout, and byte-identical `json.dumps(..., indent=2)` output.

package/src/scripts/tool_registry.ts

@@ -2,8 +2,8 @@
 /**
  * Tool Registry — manages available external tools and their permissions.
  *
- * TypeScript twin of `src/scripts/tool_registry.py` (ADR-200 — Python→TS
- * migration, Phase 8 / Wave 8e). The CLI contract is mirrored EXACTLY:
+ * Ported from the retired Python `src/scripts/tool_registry.py` (ADR-200 — Python→TS
+ * migration, Phase 8 / Wave 8e). The CLI contract is pinned:
  * same flags (`--format text|json`, `--validate-tools [...]`), same exit
  * codes (0 on success / valid, 1 when validation finds errors), same
  * byte-identical text + JSON output (json.dumps indent=2), same emoji

package/src/scripts/tools/adapter_errors.ts

@@ -1,7 +1,7 @@
 /**
  * Shared error types for tool adapters.
  *
- * TypeScript twin of `src/scripts/tools/adapter_errors.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/tools/adapter_errors.py` (ADR-200 —
  * Python→TS migration, Phase 1 / tools adapter cluster). Public API mirrors
  * the Python module exactly (snake_case kept deliberately — fidelity over TS
  * idiom): the `AdapterErrorType` string enum, the `AdapterError` value shape

package/src/scripts/tools/base_adapter.ts

@@ -9,7 +9,7 @@
  *
  * No real API calls are made by the base — adapters return structured results.
  *
- * TypeScript twin of `src/scripts/tools/base_adapter.py` (ADR-200 — Python→TS
+ * Ported from the retired Python `src/scripts/tools/base_adapter.py` (ADR-200 — Python→TS
  * migration, Phase 1 / tools adapter cluster). Public API mirrors the Python
  * module exactly (snake_case kept deliberately — fidelity over TS idiom):
  * the `ToolAction` / `ToolResult` value shapes, `ToolResult.to_dict()` with

package/src/scripts/tools/github_adapter.ts

@@ -5,7 +5,7 @@
  * Write actions remain scaffold-only (never auto-executed).
  * Falls back to scaffold data when no token is present.
  *
- * TypeScript twin of `src/scripts/tools/github_adapter.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/tools/github_adapter.py` (ADR-200 —
  * Python→TS migration, Phase 1 / tools adapter cluster). Public API mirrors
  * the Python module exactly (snake_case kept deliberately): the
  * `read_pr` / `read_issue` / `list_files` / `read_commit` / `create_pr`

package/src/scripts/tools/jira_adapter.ts

@@ -5,7 +5,7 @@
  * set. Write actions remain scaffold-only (never auto-executed). Falls back to
  * scaffold data when no credentials are present.
  *
- * TypeScript twin of `src/scripts/tools/jira_adapter.py` (ADR-200 — Python→TS
+ * Ported from the retired Python `src/scripts/tools/jira_adapter.py` (ADR-200 — Python→TS
  * migration, Phase 1 / tools adapter cluster). Public API mirrors the Python
  * module exactly (snake_case kept deliberately): the
  * `read_ticket` / `search_tickets` / `add_comment` / `transition_ticket`