@event4u/agent-config 8.4.1 → 8.6.0

package/src/scripts/check_surface_tiers.ts

@@ -2,7 +2,7 @@
 /**
  * Surface-tier boundary guard (road-to-install-contract-stability Phase 2).
  *
- * TypeScript twin of `src/scripts/check_surface_tiers.py` (ADR-200). The CLI
+ * Ported from the retired Python `src/scripts/check_surface_tiers.py` (ADR-200). The CLI
  * contract is mirrored EXACTLY — the `--skip-imports` flag + the
  * `AGENT_CONFIG_SKIP_SURFACE_TIER_CHECK` env kill-switch, exit codes (0 clean,
  * 1 violation(s), 2 argparse usage error), byte-identical finding + summary
@@ -10,7 +10,7 @@
  * same core→lab import boundary check. No behaviour changes — latent bugs
  * replicated.
  *
- * The Python original parses each `.py` under `src/scripts/` with the stdlib
+ * the retired Python implementation parses each `.py` under `src/scripts/` with the stdlib
  * `ast` module to find imports and the line numbers of imports lexically inside
  * a guarding `try/except`. This twin replicates that with a focused Python
  * import + try/except line scanner: it tracks each statement's START line (the

package/src/scripts/check_template_pin_drift.ts

@@ -2,7 +2,7 @@
 /**
  * Fail when `package.json.version` and the project-template pin drift.
  *
- * TypeScript twin of `src/scripts/check_template_pin_drift.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/check_template_pin_drift.py` (ADR-200,
  * Phase 4 / Wave 4c). CLI contract mirrored EXACTLY — `--allow-empty`
  * flag, exit codes (0 match / empty-allowed, 1 drift / missing / unreadable),
  * byte-identical messages, stdout/stderr split, same template-file

package/src/scripts/check_test_coverage_diff.ts

@@ -2,8 +2,8 @@
 /**
  * Coverage forcing-function — WARN-only (R3 of road-to-test-and-gate-integrity).
  *
- * TypeScript twin of `src/scripts/check_test_coverage_diff.py` (ADR-200,
- * Phase 4 / Wave 4c). Mirrors the Python CLI contract EXACTLY — `--base-ref`
+ * Ported from the retired Python `src/scripts/check_test_coverage_diff.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — `--base-ref`
  * flag, always exit 0 (warn-only by contract), stdout, byte-identical
  * messages, the git name-status read, the pragma scan, and the `evaluate`
  * core logic. No behaviour changes — latent matcher quirks replicated.

package/src/scripts/check_token_optimizer_freshness.ts

@@ -2,12 +2,12 @@
 /**
  * Token-Optimizer freshness validator.
  *
- * TypeScript twin of `src/scripts/check_token_optimizer_freshness.py` (ADR-200,
- * Phase 4 / Wave 4c). The CLI contract is mirrored EXACTLY — no flags,
+ * Ported from the retired Python `src/scripts/check_token_optimizer_freshness.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — no flags,
  * exit codes (0 clean, 1 drift / missing skill / unparseable), stdout/stderr
  * split, byte-identical messages, the same catalog-row parsing, the same
  * `resolve()` / `is_external()` logic and the same `_lib/agent_src`
- * resolution. No behaviour changes — latent bugs replicated.
+ * resolution. Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * Parses the catalog table inside the token-optimizer SKILL.md, verifies
  * every cited internal asset exists, and checks the trigger keywords against

package/src/scripts/check_trigger_evals.ts

@@ -2,13 +2,13 @@
 /**
  * Trigger-eval freshness + structural smoke gate (road-to-contract-integrity F4).
  *
- * TypeScript twin of `src/scripts/check_trigger_evals.py` (ADR-200). The CLI
+ * Ported from the retired Python `src/scripts/check_trigger_evals.py` (ADR-200). The CLI
  * contract is mirrored EXACTLY — `--today YYYY-MM-DD` / `--quiet` flags, exit
  * codes (0 fresh+valid, 1 regression(s), 2 bad --today / usage), the
  * stdout/stderr split (the ✅ summary on stdout, every ❌ on stderr),
  * byte-identical finding messages, the same glob (sorted), the same two
  * supported shapes, and the same ISO-date / age logic. No behaviour changes —
- * latent bugs replicated.
+ * historical quirks preserved (consumers pin the exact behaviour).
  *
  * `triggers.json` files encode each skill's behavioural intent; the surrounding
  * repo context drifts, so trigger sets need regression-locking. This gate is

package/src/scripts/check_update_banner.ts

@@ -2,7 +2,7 @@
 /**
  * Thin CLI wrapper: emit the daily update-check banner to stderr.
  *
- * TypeScript twin of `src/scripts/check_update_banner.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/check_update_banner.py` (ADR-200,
  * Phase 4 / Wave 4c). CLI contract mirrored EXACTLY — `--installed-version`,
  * `--cwd`, `--help`/`-h` flags; never raises, never exits non-zero;
  * banner (when emitted) goes to stderr; all other output suppressed.

package/src/scripts/ci_summary.ts

@@ -2,11 +2,11 @@
 /**
  * CI Summary — render a GitHub Step Summary from dispatcher run results.
  *
- * TypeScript twin of `src/scripts/ci_summary.py` (ADR-200 — Python→TS
- * migration, Phase 8 / Wave 8a). The CLI contract is mirrored EXACTLY:
+ * Ported from the retired Python `src/scripts/ci_summary.py` (ADR-200 — Python→TS
+ * migration, Phase 8 / Wave 8a). The CLI contract is pinned:
  * same flags (`--runs`, `--title`), same defaults, same stdout/env-file
  * behaviour, same byte-identical markdown output, same exit code (always
- * 0). No behaviour changes — latent bugs replicated.
+ * 0). Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * Consumes JSON files produced by `scripts/runtime_dispatcher.py run
  * --output FILE`. Each file is an ExecutionResult dump (see

package/src/scripts/ci_time_ratio.ts

@@ -2,7 +2,7 @@
 /**
  * CI-time / local-edit-time ratio (council file 07, Phase 2.3).
  *
- * TypeScript twin of `ci_time_ratio.py` (Phase 8 / Wave 8e).
+ * Ported from the retired Python `ci_time_ratio.py` (Phase 8 / Wave 8e).
  *
  * Samples the last N commits on a branch, classifies each by touched
  * paths (doc / skill / test / meta / mixed), and computes:

package/src/scripts/command_suggester/cooldown.ts

@@ -1,7 +1,7 @@
 /**
  * Suppress recently-shown suggestions per conversation.
  *
- * TypeScript twin of `src/scripts/command_suggester/cooldown.py`
+ * Ported from the retired Python `src/scripts/command_suggester/cooldown.py`
  * (ADR-200 py2ts).
  *
  * Cooldown key is `(command_name, evidence)` so two distinct triggers

package/src/scripts/command_suggester/index.ts

@@ -1,7 +1,7 @@
 /**
  * Context-aware command suggestion engine.
  *
- * TypeScript twin of `src/scripts/command_suggester/__init__.py`
+ * Ported from the retired Python `src/scripts/command_suggester/__init__.py`
  * (ADR-200 py2ts).
  *
  * Public API exposed for the always-on `command-suggestion` rule and for

package/src/scripts/command_suggester/loader.ts

@@ -1,7 +1,7 @@
 /**
  * Read command frontmatter into `CommandSpec` instances.
  *
- * TypeScript twin of `src/scripts/command_suggester/loader.py`
+ * Ported from the retired Python `src/scripts/command_suggester/loader.py`
  * (ADR-200 py2ts).
  *
  * Reuses the package's `validate_frontmatter.parse_frontmatter` twin

package/src/scripts/command_suggester/match.ts

@@ -1,7 +1,7 @@
 /**
  * Score eligible commands against a user message + recent context.
  *
- * TypeScript twin of `src/scripts/command_suggester/match.py`
+ * Ported from the retired Python `src/scripts/command_suggester/match.py`
  * (ADR-200 py2ts).
  *
  * Deterministic, no ML, no third-party deps. Two signals combine into

package/src/scripts/command_suggester/rank.ts

@@ -1,7 +1,7 @@
 /**
  * Rank scored matches into the final candidate list.
  *
- * TypeScript twin of `src/scripts/command_suggester/rank.py`
+ * Ported from the retired Python `src/scripts/command_suggester/rank.py`
  * (ADR-200 py2ts).
  *
  * Pipeline:

package/src/scripts/command_suggester/render.ts

@@ -1,7 +1,7 @@
 /**
  * Render ranked matches as a numbered-options block.
  *
- * TypeScript twin of `src/scripts/command_suggester/render.py`
+ * Ported from the retired Python `src/scripts/command_suggester/render.py`
  * (ADR-200 py2ts).
  *
  * Output strictly conforms to `user-interaction` Iron Law:

package/src/scripts/command_suggester/sanitize.ts

@@ -1,7 +1,7 @@
 /**
  * Sanitize matcher input to prevent self-echo and quoted-code triggering.
  *
- * TypeScript twin of `src/scripts/command_suggester/sanitize.py`
+ * Ported from the retired Python `src/scripts/command_suggester/sanitize.py`
  * (ADR-200 py2ts).
  *
  * The suggestion engine scores against the user's raw message and the

package/src/scripts/command_suggester/settings.ts

@@ -1,7 +1,7 @@
 /**
  * Read `commands.suggestion.*` from `.agent-settings.yml` into `Settings`.
  *
- * TypeScript twin of `src/scripts/command_suggester/settings.py`
+ * Ported from the retired Python `src/scripts/command_suggester/settings.py`
  * (ADR-200 py2ts). Mirror of the chat-history pattern:
  *
  *  - Default-permissive: a missing file or missing section returns

package/src/scripts/compile_router.ts

@@ -2,7 +2,7 @@
 /**
  * Compile rule frontmatter into `router.json`.
  *
- * TypeScript twin of `src/scripts/compile_router.py` (ADR-200, Phase 5). The
+ * Ported from the retired Python `src/scripts/compile_router.py` (ADR-200). The
  * CLI contract is mirrored EXACTLY — the positional argv flags (`--pretty`,
  * `--check`), exit codes (0 = wrote / up-to-date; 1 = stale under --check), the
  * stdout/stderr split, byte-identical messages, AND byte-identical generated
@@ -12,9 +12,9 @@
  *
  * Imports the `_lib/agent_settings` (`project_settings_path`,
  * `load_agent_settings`) and `_lib/agent_src` (`artefact_roots`) twins — the
- * SAME modules the Python original imports.
+ * SAME modules the retired Python implementation imports.
  *
- * No behaviour changes — latent Python quirks replicated.
+ * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * Reads `.agent-src.uncondensed/rules/*.md`; produces deterministic JSON
  * mapping kernel + tier-1 + tier-2 rules to their triggers and routed
@@ -33,7 +33,7 @@ type Json = unknown;
 type JsonObject = Record<string, Json>;
 
 const _HERE = fileURLToPath(import.meta.url);
-// _HERE === <repo>/src/scripts/compile_router.ts ; the Python original derives
+// _HERE === <repo>/src/scripts/compile_router.ts ; the retired Python implementation derives
 // ROOT = <file>.parent.parent.parent — two dirs up from src/scripts.
 export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 // ADR-017: rules now live across multiple source roots. Legacy

package/src/scripts/condense.ts

@@ -5,15 +5,15 @@
  * symlinks for the rest; opt into rule symlinks via
  * augment.rules_use_symlinks in .agent-settings.yml).
  *
- * TypeScript twin of `src/scripts/condense.py` (ADR-200 — Python→TS
+ * Ported from the retired Python `src/scripts/condense.py` (ADR-200 — Python→TS
  * migration, Phase 5). Mirrors the Python CLI surface EXACTLY — every
  * subcommand (`--sync`, `--list`, `--changed`, `--check`, `--check-hashes`,
  * `--clean-hashes`, `--mark-done <path>`, `--mark-all-done`,
  * `--generate-tools`, `--clean-tools`, `--project-augment`) — same flags,
  * exit codes, stdout/stderr split, byte-identical messages. No behaviour
- * changes; latent Python bugs replicated and flagged.
+ * changes; historical quirks preserved and flagged.
  *
- * Path handling note: the Python original uses `pathlib.Path` objects.
+ * Path handling note: the retired Python implementation uses `pathlib.Path` objects.
  * This twin uses absolute path strings (the host filesystem on the
  * supported platforms is POSIX). Logical relative paths are always POSIX
  * (forward-slash) strings, matching the Python `.as_posix()` keys.

package/src/scripts/condense_memory.ts

@@ -2,7 +2,7 @@
 /**
  * Input-side memory condensation — Phase 2 of step-16-telegraph-substance.
  *
- * TypeScript twin of `src/scripts/condense_memory.py` (ADR-200, Phase 7 /
+ * Ported from the retired Python `src/scripts/condense_memory.py` (ADR-200, Phase 7 /
  * dev-side memory). The public API and CLI contract mirror the Python
  * original EXACTLY — same exported names (snake_case kept deliberately),
  * same exit codes, stdout/stderr split, byte-identical messages, and

package/src/scripts/config/index.ts

@@ -6,7 +6,7 @@
 // read-only, lazy-PyYAML; they layer on top of `scripts/_lib/agent_settings`
 // for project-root anchoring.
 //
-// Twin of `src/scripts/config/__init__.py`. The Python package's
+// Ported from the retired Python `src/scripts/config/__init__.py` (ADR-200). The Python package's
 // `__init__.py` declares no public symbols (only the module docstring), so
 // this barrel intentionally re-exports nothing — importers reach into the
 // individual twins (`./presets.js`, `./profiles.js`, `./packs.js`,

package/src/scripts/config/packs.ts

@@ -18,7 +18,7 @@
 //   tsx src/scripts/config/packs.ts --packs laravel,finance-basic
 //   tsx src/scripts/config/packs.ts --legacy-all
 //
-// Twin of `src/scripts/config/packs.py`.
+// Ported from the retired Python `src/scripts/config/packs.py` (ADR-200).
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';

package/src/scripts/config/presets.ts

@@ -18,7 +18,7 @@
 // `developer` vs `block_on_risk.financial_paths` for `founder`) read the
 // merged knob bag returned by `resolve_preset`.
 //
-// Twin of `src/scripts/config/presets.py`.
+// Ported from the retired Python `src/scripts/config/presets.py` (ADR-200).
 import * as fs from 'node:fs';
 import { createRequire } from 'node:module';
 import * as path from 'node:path';

package/src/scripts/config/profile_explain.ts

@@ -14,7 +14,7 @@
 // Reuses the explain-modes two-views-over-one-envelope convention
 // (`docs/contracts/explain-modes.md`).
 //
-// Twin of `src/scripts/config/profile_explain.py`.
+// Ported from the retired Python `src/scripts/config/profile_explain.py` (ADR-200).
 
 // `any` mirrors Python's `dict[str, Any]` envelope; values are heterogeneous
 // (lists, ints, bools, the `?` placeholder string) and consumed only through

package/src/scripts/config/profiles.ts

@@ -18,7 +18,7 @@
 // block, the loader returns a structured warning state so `/onboard` can
 // surface "audience not yet picked".
 //
-// Twin of `src/scripts/config/profiles.py`.
+// Ported from the retired Python `src/scripts/config/profiles.py` (ADR-200).
 import * as fs from 'node:fs';
 import { createRequire } from 'node:module';
 import * as path from 'node:path';

package/src/scripts/config/session_profiles.ts

@@ -24,7 +24,7 @@
 // Pure functions are unit-testable; the `__main__` CLI is what the `/profile`
 // command shells out to.
 //
-// Twin of `src/scripts/config/session_profiles.py`.
+// Ported from the retired Python `src/scripts/config/session_profiles.py` (ADR-200).
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import { createRequire } from 'node:module';

package/src/scripts/context_hygiene_hook.ts

@@ -2,7 +2,7 @@
 /**
  * Platform-agnostic PostToolUse hook for the `context-hygiene` rule.
  *
- * TypeScript twin of `src/scripts/context_hygiene_hook.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/context_hygiene_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).
  *
@@ -39,7 +39,7 @@ import { atomic_write_json } from "./hooks/state_io.js";
 
 // NOTE: the Python docstring says `agents/runtime/state/`, but the code
 // constant is `agents/state/`. Replicated verbatim — this is a latent
-// docstring/code divergence in the Python original (ADR-200 § replicate
+// docstring/code divergence in the retired Python implementation (ADR-200 § replicate
 // latent bugs), and `STATE_FILE` is what the test suite asserts against.
 export const STATE_DIR = path.join("agents", "state");
 export const STATE_FILE = path.join(STATE_DIR, "context-hygiene.json");

package/src/scripts/cost_by_conversation.ts

@@ -2,7 +2,7 @@
 /**
  * Group cost-tracking sessions by conversation_id (the external runtime `conversation.mjs` `5b71c7a` ref).
  *
- * TypeScript twin of `src/scripts/cost_by_conversation.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/cost_by_conversation.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/cost_summary.ts

@@ -2,8 +2,8 @@
 /**
  * Emit `cost-summary/v1` JSON per `docs/contracts/cost-summary-schema.md`.
  *
- * TypeScript twin of `src/scripts/cost_summary.py` (ADR-200 — Python→TS
- * migration, Phase 8 / Wave 8e). The CLI contract is mirrored EXACTLY:
+ * Ported from the retired Python `src/scripts/cost_summary.py` (ADR-200 — Python→TS
+ * migration, Phase 8 / Wave 8e). The CLI contract is pinned:
  * same flags (`--input`, `--format json`), same exit code (0), same
  * byte-identical JSON output (json.dumps indent=2; PyFloat-aware so
  * `total_cost_usd` renders with a trailing `.0` like Python). The

package/src/scripts/council_cli.ts

@@ -2,7 +2,7 @@
 /**
  * Council CLI — `./agent-config council:{estimate,run,render}`.
  *
- * TypeScript twin of `council_cli.py` (py2ts Phase 1, ADR-200). Wraps
+ * Ported from the retired Python `council_cli.py` (ADR-200). Wraps
  * `ai_council/orchestrator` for non-interactive callers. Subcommands:
  *
  *   estimate  Bundle + estimate per-member cost (no API call, no spend).

package/src/scripts/council_prune.ts

@@ -1,7 +1,7 @@
 /**
  * Manual pruner for council artefacts.
  *
- * TypeScript twin of `src/scripts/council_prune.py` (ADR-200 — Python→TS
+ * Ported from the retired Python `src/scripts/council_prune.py` (ADR-200 — Python→TS
  * migration, Phase 1).
  *
  * Deletes council files older than `ai_council.session_retention_days`

package/src/scripts/cross_repo_retrieve.ts

@@ -2,7 +2,7 @@
 /**
  * Cross-repo retrieval — read-only, targeted, opt-in (ADR-032 Option A).
  *
- * TypeScript twin of `src/scripts/cross_repo_retrieve.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/cross_repo_retrieve.py` (ADR-200,
  * Phase 8 / Wave 8g). Mirrors the Python contract EXACTLY — positional
  * `query` + `--path-scope` / `--max-chunks` / `--format` / `--root` flags,
  * the retrieval envelope shape, the text-table render, opt-in / large-sibling
@@ -18,7 +18,7 @@
  * pulls in `workspace_secrets`). Those modules are not yet ported to
  * TypeScript and a `.ts` cannot import a `.py`, so the redaction + chunking
  * primitives are ported faithfully inline here and verified byte-identical
- * against the Python originals (differential-tested, no behavior divergence).
+ * against the retired Python implementations (differential-tested, no behavior divergence).
  * They carry no legacy-source-path literal, matching the `.py`.
  *
  * Scope guards (Option A):

package/src/scripts/discovery_stats.ts

@@ -2,15 +2,15 @@
 /**
  * Pretty-print the `stats` block from the committed discovery manifest.
  *
- * TypeScript twin of `src/scripts/discovery_stats.py` (ADR-200, Phase 8 /
- * Wave 8a). The CLI contract is mirrored EXACTLY — the single `--manifest`
+ * Ported from the retired Python `src/scripts/discovery_stats.py` (ADR-200, Phase 8 /
+ * Wave 8a). The CLI contract is pinned — the single `--manifest`
  * flag (default `dist/discovery/discovery-manifest.json`), exit codes
  * (0 printed · 1 manifest missing or malformed), the stdout/stderr split,
  * and byte-identical messages. Cheap sanity surface for developers: counts
  * by category, lifecycle, and trust level. Reads only the committed
  * manifest; no scan, no generation. See ADR-015.
  *
- * 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/evidence_report.ts

@@ -2,8 +2,8 @@
 /**
  * Evidence Report template automation.
  *
- * TypeScript twin of `src/scripts/evidence_report.py` (ADR-200). The CLI
- * contract mirrors the Python original EXACTLY — same subcommands
+ * Ported from the retired Python `src/scripts/evidence_report.py` (ADR-200). The CLI
+ * contract pins the historical contract exactly — same subcommands
  * (`init`, `add`, `git-state`), same flags, same exit codes (0 / 1 / 3),
  * same stdout/stderr split, byte-identical messages, the same
  * skeleton/provenance text, the same heading-insertion logic, and the
@@ -29,7 +29,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-// argparse `prog` is hardcoded to "evidence_report.py" in the Python original,
+// argparse `prog` is hardcoded to "evidence_report.py" in the retired Python implementation,
 // so usage strings stay byte-identical regardless of the `.py`/`.ts` filename.
 const PROG = 'evidence_report.py';
 // First line of the module docstring — argparse `description`.
@@ -182,7 +182,7 @@ function cmd_add(args: ParsedArgs, root: string): number {
             insert_at = i;
             break;
         }
-        // NOTE: dead branch in the Python original (in_target is false here);
+        // NOTE: dead branch in the retired Python implementation (in_target is false here);
         // replicated faithfully — never reached.
         if (in_target && line.startsWith('## ')) {
             insert_at = i;

package/src/scripts/extract_audit_patterns.ts

@@ -2,7 +2,7 @@
 /**
  * Mine repeated phase patterns from `agents/runtime/state/audit/*.jsonl`.
  *
- * TypeScript twin of `src/scripts/extract_audit_patterns.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/extract_audit_patterns.py` (ADR-200 —
  * Python→TS migration, Phase 8 / Wave 8g). Mirrors the Python CLI contract
  * EXACTLY — the `--audit-dir` / `--month` / `--min-count` / `--json` flags,
  * exit codes (0 ok / 2 min-count below floor), the stdout/stderr split,
@@ -16,7 +16,7 @@
  *
  * Read-only: never mutates the JSONL, never writes outside stdout.
  *
- * 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/first_run_gate_hook.ts

@@ -2,7 +2,7 @@
 /**
  * First-run gate — surface the marketplace-install-but-unscaffolded shape.
  *
- * TypeScript twin of `src/scripts/first_run_gate_hook.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/first_run_gate_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/gen_discovery_baseline.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env tsx
 /** Generate agents/evidence/notes/discovery-baseline.md for Phase 0.1.
  *
- * TypeScript twin of `src/scripts/gen_discovery_baseline.py` (ADR-200, Phase 8
- * / Wave 8h). Mirrors the Python CLI contract EXACTLY — no flags, exit 0,
+ * Ported from the retired Python `src/scripts/gen_discovery_baseline.py` (ADR-200, Phase 8
+ * / Wave 8h). The CLI contract is pinned — no flags, exit 0,
  * byte-identical stdout (`wrote {dest} — {n} lines`) and byte-identical written
  * `discovery-baseline.md` (except the generated UTC timestamp, which is
  * non-deterministic and excluded from golden parity). No behaviour changes:

package/src/scripts/generate_capabilities_index.ts

@@ -2,8 +2,8 @@
 /**
  * Generate `CAPABILITIES.yaml` — the package's capability-coverage index.
  *
- * TypeScript twin of `src/scripts/generate_capabilities_index.py` (ADR-200).
- * Mirrors the Python CLI contract EXACTLY — the `--check` flag, exit codes
+ * Ported from the retired Python `src/scripts/generate_capabilities_index.py` (ADR-200).
+ * The CLI contract is pinned — the `--check` flag, exit codes
  * (0 / 1 / 2), stdout/stderr split, and the byte-identical generated
  * `CAPABILITIES.yaml` (header comment block, `meta:` block, `capability_areas:`
  * by domain, `gaps:` block, the `json.dumps(..., ensure_ascii=False)` scalar

package/src/scripts/generate_capability_matrix.ts

@@ -2,8 +2,8 @@
 /**
  * Generate the cross-host capability matrix (road-to-competitive-borrow P1.3).
  *
- * TypeScript twin of `src/scripts/generate_capability_matrix.py` (ADR-200).
- * Mirrors the Python CLI contract EXACTLY — the `--check` / `--quiet` flags,
+ * Ported from the retired Python `src/scripts/generate_capability_matrix.py` (ADR-200).
+ * The CLI contract is pinned — the `--check` / `--quiet` flags,
  * exit codes (0 / 1 / 2), stdout/stderr split, the byte-identical
  * `docs/capability-matrix.md` (heading prose, the host-header table, the glyph
  * cells, ARTIFACTS row order), and the byte-identical

package/src/scripts/generate_catalog.ts

@@ -2,8 +2,8 @@
 /**
  * Generate llms.txt and docs/skills-catalog.md from SKILL.md frontmatter.
  *
- * TypeScript twin of `src/scripts/generate_catalog.py` (ADR-200, Phase 8
- * Wave 8a). Mirrors the Python CLI contract EXACTLY — same stdout lines,
+ * Ported from the retired Python `src/scripts/generate_catalog.py` (ADR-200, Phase 8
+ * Wave 8a). The CLI contract is pinned — same stdout lines,
  * same exit codes, byte-identical generated `llms.txt` + `docs/skills-catalog.md`.
  *
  * Reads name + description from each `dist/agent-src/skills/*\/SKILL.md` and

package/src/scripts/generate_command_flows.ts

@@ -2,12 +2,12 @@
 /**
  * Generate `docs/command-flows.md` — the Flows primary view (road-to-6.1.0 Step 9).
  *
- * TypeScript twin of `src/scripts/generate_command_flows.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/generate_command_flows.py` (ADR-200 —
  * Python→TS migration, Phase 8 / Wave 8a). The CLI contract is mirrored
  * EXACTLY: same flag (`--check`), same exit codes, same stdout/stderr
  * split, same byte-identical generated `docs/command-flows.md`. WRITER —
  * the rendered markdown matches the Python output byte-for-byte. No
- * behaviour changes — latent bugs replicated.
+ * behaviour changes — historical quirks preserved (consumers pin the exact behaviour).
  *
  * Turns the flat command list into a FLOW-organized view from two
  * validated sources:

package/src/scripts/generate_cookbook.ts

@@ -2,7 +2,7 @@
 /**
  * Generate the named cookbook (road-to-competitive-borrow P1.4).
  *
- * TypeScript twin of `src/scripts/generate_cookbook.py` (ADR-200). Mirrors the
+ * Ported from the retired Python `src/scripts/generate_cookbook.py` (ADR-200). Mirrors the
  * Python CLI contract EXACTLY — the `--check` / `--quiet` flags, exit codes
  * (0 / 1 / 2), stdout/stderr split, and the byte-identical generated
  * `docs/cookbook.md` (heading prose, the named-recipe sections, the four

package/src/scripts/generate_index.ts

@@ -2,8 +2,8 @@
 /**
  * Generate `agents/index.md` (internal) and `docs/catalog.md` (public).
  *
- * TypeScript twin of `src/scripts/generate_index.py` (ADR-200, Phase 8 /
- * Wave 8a). The CLI contract is mirrored EXACTLY — the single `--check`
+ * Ported from the retired Python `src/scripts/generate_index.py` (ADR-200, Phase 8 /
+ * Wave 8a). The CLI contract is pinned — the single `--check`
  * flag, exit codes (0 / 1 on drift), the stdout split, byte-identical
  * messages, AND byte-identical generated Markdown (both files are write
  * targets; both are sync-checked in CI via `--check`).
@@ -12,7 +12,7 @@
  * `docs/guidelines/` (via the `_lib/agent_src` twin's multi-root discovery)
  * and renders two artefact tables — one for maintainers, one for consumers.
  *
- * 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/generate_ownership_matrix.ts

@@ -2,8 +2,8 @@
 /**
  * Generate the file-ownership matrix.
  *
- * TypeScript twin of `src/scripts/generate_ownership_matrix.py` (ADR-200,
- * Phase 8 Wave 8a). Mirrors the Python CLI contract EXACTLY — flag
+ * Ported from the retired Python `src/scripts/generate_ownership_matrix.py` (ADR-200,
+ * Phase 8 Wave 8a). The CLI contract is pinned — flag
  * (`--check`), exit codes (0 / 1 / 2 / 3), stdout/stderr split, and the
  * byte-identical generated outputs (`json.dumps(payload, indent=2,
  * sort_keys=False)` + trailing newline, and the markdown render).

package/src/scripts/generate_pack_manifests.ts

@@ -2,7 +2,7 @@
 /**
  * Generate `pack.yaml` + `README.md` for every pack home.
  *
- * TypeScript twin of `src/scripts/generate_pack_manifests.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/generate_pack_manifests.py` (ADR-200 —
  * Python→TS migration, Phase 8 / Wave 8a). The CLI contract is mirrored
  * EXACTLY: same flag (`--check`), same exit codes, same stdout/stderr
  * split, same byte-identical generated `pack.yaml` + `README.md`. WRITER
@@ -10,7 +10,7 @@
  * PyYAML `safe_dump(meta, sort_keys=True, allow_unicode=True)` block-style
  * emission (`_py_safe_dump` below reproduces PyYAML's scalar-quoting +
  * block-collection layout for the value shapes this script emits). No
- * behaviour changes — latent bugs replicated.
+ * behaviour changes — historical quirks preserved (consumers pin the exact behaviour).
  *
  * Phase 4.4 of the monorepo migration (ADR-017). The manifests are
  * *derived* from frontmatter + `src/config/discovery/packs.yml`; they are