@event4u/agent-config 8.4.1 → 8.6.0

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`

package/src/scripts/trigger_coverage.ts

@@ -2,7 +2,7 @@
 /**
  * Trigger-coverage suite (roadmap Phase 2.1 / 2.2).
  *
- * TypeScript twin of `src/scripts/trigger_coverage.py` (ADR-200, Phase 8 /
+ * Ported from the retired Python `src/scripts/trigger_coverage.py` (ADR-200, Phase 8 /
  * Wave 8b). Mirrors the CLI contract EXACTLY — the `--json` flag, exit codes
  * (0 pass / 1 miss / 2 missing-router-or-PyYAML), the stdout/stderr split,
  * byte-identical human + JSON report.
@@ -25,7 +25,7 @@
  * A case fails when an expected rule is NOT in the fired set. Exit 1 on any
  * miss → the merge that would have shrunk the rule is blocked (2.2).
  *
- * 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/update_counts.ts

@@ -2,7 +2,7 @@
 /**
  * Sync package-content counts (skills/rules/commands/guidelines) across docs.
  *
- * TypeScript twin of `src/scripts/update_counts.py` (ADR-200, Phase 5). The
+ * Ported from the retired Python `src/scripts/update_counts.py` (ADR-200). The
  * CLI contract is mirrored EXACTLY — the single `--check` flag, exit codes
  * (0 = synced / updated; 1 = stale under --check, missing target), the
  * stdout/stderr split, and byte-identical messages AND byte-identical rewritten
@@ -11,9 +11,9 @@
  * call them 1:1.
  *
  * Imports the `_lib/agent_src` twin (`artefact_roots`, `iter_commands`) — the
- * SAME functions the Python original imports.
+ * SAME functions 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.
  *
  * Source of truth: `.agent-src.uncondensed/`.
  *
@@ -28,7 +28,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { artefact_roots, iter_commands } from './_lib/agent_src.js';
 
 const _HERE = fileURLToPath(import.meta.url);
-// _HERE === <repo>/src/scripts/update_counts.ts ; the Python original derives
+// _HERE === <repo>/src/scripts/update_counts.ts ; the retired Python implementation derives
 // REPO_ROOT = <file>.parent.parent.parent — two dirs up from src/scripts.
 export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
@@ -78,6 +78,23 @@ function _exists(p: string): boolean {
 }
 
 export function count(kind: string): number {
+    if (kind === 'router_rules') {
+        // Routed rule entries in the compiled router (kernel + tier_1 +
+        // tier_2). Read from dist/router.json — the artifact hosts consume —
+        // so prose citing "the router routes N rules" tracks the compiled
+        // truth, not a hand-typed snapshot.
+        const routerPath = path.join(REPO_ROOT, 'dist', 'router.json');
+        const router = JSON.parse(fs.readFileSync(routerPath, 'utf-8')) as {
+            kernel?: unknown[];
+            tier_1?: unknown[];
+            tier_2?: unknown[];
+        };
+        return (
+            (router.kernel?.length ?? 0) +
+            (router.tier_1?.length ?? 0) +
+            (router.tier_2?.length ?? 0)
+        );
+    }
     if (kind === 'guidelines') {
         // Guidelines live under docs/guidelines/{topic}/ — they are reference
         // material, not packaged artefacts. Recursive walk to count every .md.
@@ -150,6 +167,51 @@ export const TARGETS: ReadonlyArray<[string, ReadonlyArray<[string, string]>]> =
             ['(/badge/Rules-)(\\d+)(-)', 'rules'],
             ['(/badge/Guidelines-)(\\d+)(-)', 'guidelines'],
             ['(/badge/Personas-)(\\d+)(-)', 'personas'],
+            // Hero prose sentence: `**N skills, N commands, N governed rules**`
+            // (road-to-truth-and-reference-hygiene Phase 1: prose counts are
+            // generated, never hand-typed).
+            ['(\\*\\*)(\\d+)( skills, )', 'skills'],
+            ['( skills, )(\\d+)( commands, )', 'commands'],
+            ['( commands, )(\\d+)( governed rules\\*\\*)', 'rules'],
+            // Feature-list line: `— N skills + N commands, with a capability router`
+            ['(— )(\\d+)( skills \\+ )', 'skills'],
+            ['( skills \\+ )(\\d+)( commands,)', 'commands'],
+            // Work-journey line: `You don't memorize N commands`
+            ['(memorize )(\\d+)( commands)', 'commands'],
+        ],
+    ],
+    [
+        'docs/CLAIMS.md',
+        [
+            // The three count claims — their numbers are generated from the
+            // same source the gate checks, closing the ledger's own
+            // "count-source binding" debt (B1.2).
+            ['(- claim: )(\\d+)( skills \\(README hero)', 'skills'],
+            ['(- claim: )(\\d+)( commands\\.)', 'commands'],
+            ['(- claim: )(\\d+)( governed rules\\.)', 'rules'],
+        ],
+    ],
+    [
+        'docs/getting-started-by-role.md',
+        [
+            ['(ships )(\\d+)( skills, )', 'skills'],
+            ['( skills, )(\\d+)( governed rules, and )', 'rules'],
+            ['( governed rules, and )(\\d+)( commands\\.)', 'commands'],
+        ],
+    ],
+    [
+        'docs/featured-skills.md',
+        [
+            ['(subset of the )(\\d+)( skills)', 'skills'],
+            ['(Browse all )(\\d+)( skills)', 'skills'],
+            ['(all )(\\d+)( commands: \\[)', 'commands'],
+        ],
+    ],
+    [
+        'docs/governance-advantage.md',
+        [
+            ['(load all )(\\d+)( skills)', 'skills'],
+            ['(\\()(\\d+)( routed rules,)', 'router_rules'],
         ],
     ],
     [
@@ -204,7 +266,7 @@ export function apply_to_text(
     return [new_text, drifts];
 }
 
-const KINDS = ['skills', 'rules', 'commands', 'guidelines', 'personas'] as const;
+const KINDS = ['skills', 'rules', 'commands', 'guidelines', 'personas', 'router_rules'] as const;
 
 function parse_args(argv: readonly string[]): { check: boolean } {
     const args = { check: false };
@@ -234,7 +296,7 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     process.stdout.write(
         `📊  Truth: skills=${counts['skills']} rules=${counts['rules']} ` +
             `commands=${counts['commands']} guidelines=${counts['guidelines']} ` +
-            `personas=${counts['personas']}\n`,
+            `personas=${counts['personas']} router_rules=${counts['router_rules']}\n`,
     );
 
     let any_drift = false;

package/src/scripts/update_prices.ts

@@ -2,8 +2,8 @@
 /**
  * Refresh `agents/runtime/.agent-prices.md` from the LiteLLM model-prices feed.
  *
- * TypeScript twin of `src/scripts/update_prices.py` (ADR-200 — Python→TS
- * migration, Phase 8 / Wave 8g). Mirrors the Python CLI contract EXACTLY —
+ * Ported from the retired Python `src/scripts/update_prices.py` (ADR-200 — Python→TS
+ * migration, Phase 8 / Wave 8g). The CLI contract is pinned —
  * the `--check` / `--path` flags, exit codes (0 ok / 1 stale-or-missing in
  * --check), the stdout/stderr split, byte-identical messages, and the
  * byte-identical written `agents/runtime/.agent-prices.md`.
@@ -15,7 +15,7 @@
  * Network fetch + `today` (UTC date) are non-deterministic; golden parity
  * exercises `--check` (no network, fixed fixture) and the no-network write
  * path with `--path` to a temp file (timestamp line excluded). No behaviour
- * changes — latent Python quirks replicated.
+ * changes — historical quirks preserved (consumers pin the exact behaviour).
  */
 import * as fs from 'node:fs';
 import * as https from 'node:https';

package/src/scripts/validate_agent_settings.ts

@@ -2,14 +2,14 @@
 /**
  * Agent-settings schema validator (rule_loading_tier untangle, 2026-06-01).
  *
- * TypeScript twin of `src/scripts/validate_agent_settings.py` (ADR-200,
- * Phase 4 / Wave 4c). The CLI contract is mirrored EXACTLY — no flags,
+ * Ported from the retired Python `src/scripts/validate_agent_settings.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — no flags,
  * exit codes (0 every file validates, 1 schema violation, 3 bootstrap
  * failure), stdout output (GitHub `::error::` annotations + summary line),
  * the same template-placeholder substitution, the same checked-file set
  * (template + local settings via the `_lib/agent_settings` twin), and the
  * same Draft-07 enum/type constraints from the shared schema JSON. No
- * behaviour changes — latent bugs replicated.
+ * behaviour changes — historical quirks preserved (consumers pin the exact behaviour).
  *
  * DIVERGENCE NOTE (documented per ADR-200 §6): the underlying jsonschema
  * error PROSE is Python-version-dependent. This twin reproduces the schema's

package/src/scripts/validate_decision_engine.ts

@@ -2,8 +2,8 @@
 /**
  * Decision-engine settings validator (road-to-productization P2).
  *
- * TypeScript twin of `src/scripts/validate_decision_engine.py` (ADR-200,
- * Phase 4 / Wave 4c). Mirrors the Python CLI contract EXACTLY — no flags,
+ * Ported from the retired Python `src/scripts/validate_decision_engine.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — no flags,
  * exit codes (0 clean/warn, 1 hard error, 3 internal), stdout (the
  * `::error::` / `::warning::` GitHub-annotation lines + the summary), same
  * file set (template + project local settings) and order. No behaviour

package/src/scripts/validate_discovery_manifest.ts

@@ -3,13 +3,13 @@
  * Stale-manifest guard — re-builds the manifest in memory and diffs it
  * against the committed `dist/discovery/discovery-manifest.json`.
  *
- * TypeScript twin of `src/scripts/validate_discovery_manifest.py` (ADR-200,
- * Phase 4 / Wave 4c). The CLI contract is mirrored EXACTLY — `--quiet`
+ * Ported from the retired Python `src/scripts/validate_discovery_manifest.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — `--quiet`
  * flag, exit codes (0 match, 1 drift / missing committed manifest),
  * stdout/stderr split, byte-identical messages, and the same `generated_at`
  * normalization + sorted-key JSON comparison + first-diff-line report. The
  * scanner (`build_discovery_manifest.ts`) is run via the repo-local `tsx`
- * binary, mirroring how the Python original invoked the scanner via
+ * binary, mirroring how the retired Python implementation invoked the scanner via
  * `sys.executable`. No behaviour changes.
  *
  * Exit codes:

package/src/scripts/validate_frontmatter.ts

@@ -2,10 +2,10 @@
 /**
  * validate_frontmatter.ts — frontmatter validator (Draft-07 subset).
  *
- * TypeScript twin of `src/scripts/validate_frontmatter.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/validate_frontmatter.py` (ADR-200 —
  * Python→TS migration, Phase 4 / Wave 4a). The public surface, CLI flags,
- * exit codes, stdout/stderr split, and finding-message strings mirror the
- * Python original byte-for-byte. The Python original is deleted in the same
+ * exit codes, stdout/stderr split, and finding-message strings are pinned
+ * byte-for-byte by tests. The retired Python implementation was deleted in the same
  * PR; the dispatcher resolves this `.ts`.
  *
  * Validates the YAML frontmatter of an agent artefact (skill, rule, command,
@@ -19,7 +19,7 @@
  *   - apply_schema_defaults(data, schema) -> data (in place)
  *   - validate(data, schema) -> SchemaError[]
  *
- * No behaviour changes — latent Python quirks replicated. The lenient subset
+ * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour. The lenient subset
  * parser (used for schema validation) supports scalar / boolean / integer /
  * inline-list / block-list / one-level-nested-block. The `strict_yaml_error`
  * gate uses the `yaml` package as the source of truth (same parser real
@@ -835,7 +835,7 @@ export function _iter_artefacts(root: string): Array<[string, string]> {
     return targets;
 }
 
-// argparse parity. `prog` matches the Python original's `sys.argv[0]` basename
+// argparse parity. `prog` matches the retired Python implementation's `sys.argv[0]` basename
 // (`validate_frontmatter.py`) so the usage/error text is byte-identical to the
 // pre-migration CLI the golden corpus captured.
 const _PROG = 'validate_frontmatter.py';

package/src/scripts/validate_safe_paths.ts

@@ -2,12 +2,12 @@
 /**
  * Sensitive-path denylist — refuses files that almost certainly hold secrets or PII.
  *
- * TypeScript twin of `src/scripts/validate_safe_paths.py` (ADR-200, Phase 4 /
+ * Ported from the retired Python `src/scripts/validate_safe_paths.py` (ADR-200, Phase 4 /
  * Wave 4c). The public API and CLI contract are mirrored EXACTLY — same
  * exported snake_case names (`is_sensitive`, `assert_safe`,
  * `SensitivePathError`), same denylist regex / component set / token list,
  * same CLI exit codes (0 safe, 2 sensitive / usage), stdout/stderr split, and
- * byte-identical messages. No behaviour changes — latent bugs replicated.
+ * byte-identical messages. Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * Phase 0 of step-16-telegraph-substance. Gates Phase 2 (`scripts/condense_memory.py`):
  * any consumer-supplied path must pass `assert_safe()` before bytes are read or

package/src/scripts/validate_telegraph_carveouts.ts

@@ -2,12 +2,12 @@
 /**
  * Mechanical carve-out validator for telegraph-condensed replies.
  *
- * TypeScript twin of `src/scripts/validate_telegraph_carveouts.py` (ADR-200,
- * Phase 4 / Wave 4c). The CLI contract is mirrored EXACTLY — two positional
+ * Ported from the retired Python `src/scripts/validate_telegraph_carveouts.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — two positional
  * `pre` / `post` file args, exit codes (0 preserved, 1 drift, 2 missing
  * file), stdout/stderr split, byte-identical messages, the same carve-out
  * extractors and the same `difflib.unified_diff` rendering. No behaviour
- * changes — latent bugs replicated.
+ * changes — historical quirks preserved (consumers pin the exact behaviour).
  *
  * Given a pre-condensation reply and a post-condensation reply, assert that
  * every carve-out region from `.agent-src.uncondensed/rules/telegraph-speak.md`

package/src/scripts/verify_before_complete_hook.ts

@@ -2,7 +2,7 @@
 /**
  * Platform-agnostic hook for the `verify-before-complete` rule.
  *
- * TypeScript twin of `src/scripts/verify_before_complete_hook.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/verify_before_complete_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).
  *
@@ -40,7 +40,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 — latent docstring/code
-// divergence in the Python original (ADR-200 § replicate latent bugs).
+// divergence in the retired Python implementation (ADR-200 § replicate latent bugs).
 export const STATE_FILE = path.join("agents", "state", "verify-before-complete.json");
 
 // Tool names across platforms whose `command` / `tool_input.command` field

package/src/scripts/verify_physical_move.ts

@@ -2,7 +2,7 @@
 /**
  * Verify the post-move state matches the pre-move snapshot byte-for-byte.
  *
- * TypeScript twin of `src/scripts/verify_physical_move.py` (ADR-200, Phase 8 /
+ * Ported from the retired Python `src/scripts/verify_physical_move.py` (ADR-200, Phase 8 /
  * Wave 8b). Mirrors the CLI contract EXACTLY — the `--snapshot`, `--json`
  * flags, exit codes (0 OK / 1 regression / 2 snapshot-missing), the
  * stdout/stderr split, byte-identical human + JSON output.
@@ -11,7 +11,7 @@
  * this script), then loads the fresh outputs and compares them against
  * `dist/migration/pre-move-snapshot.json`.
  *
- * 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/wrapper_freshness_hook.ts

@@ -3,11 +3,11 @@
  * session_start concern — keep the project-local `./agent-config` wrapper
  * AND the installed `.git/hooks/pre-commit` gate fresh.
  *
- * TypeScript twin of `src/scripts/wrapper_freshness_hook.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/wrapper_freshness_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).
  *
- * Defense-in-depth twin of the update-command refresh (`upgrade` /
+ * Defense-in-depth companion of the update-command refresh (`upgrade` /
  * `refresh --project`). On every session_start the dispatcher runs this in
  * the consumer workspace; if a `./agent-config` wrapper exists there and
  * differs from the canonical template, it is re-stamped so an outdated,
@@ -70,7 +70,7 @@ function _isFile(p: string): boolean {
 /**
  * True when project_root is the agent-config package itself.
  *
- * TypeScript twin of `src/scripts/_cli/cmd_refresh.py::_is_source_repo`
+ * Ported from the retired Python `src/scripts/_cli/cmd_refresh.py::_is_source_repo`
  * (unported standalone — inlined here so the hook stays dependency-free
  * and crash-safe). The broader check (condensed output, packaged source,
  * or the package's own `package.json` name) makes the freshness self-heal