@event4u/agent-config 8.4.1 → 8.6.0

package/src/scripts/lint_no_python_twin_rationale.ts

@@ -0,0 +1,102 @@
+#!/usr/bin/env tsx
+/**
+ * Python-twin rationale guard (road-to-truth-and-reference-hygiene Phase 2).
+ *
+ * The py2ts migration (ADR-200) is closed and its Python originals are
+ * deleted; the parity scaffolding comments ("TypeScript twin of …", "latent
+ * Python quirks replicated", "byte-identical to the Python original") were
+ * swept on 2026-07-08 and re-attributed to their live consumers (tests,
+ * checksum gates, pinned CLI contracts). This lint keeps the residue from
+ * creeping back: a NEW comment that rationalises behaviour by fidelity to
+ * the deleted Python twin fails CI.
+ *
+ * Scope: comment lines in `src/scripts/**\/*.ts`. Historical provenance
+ * mentions ("ported from the retired Python `x.py` (ADR-200)") are fine —
+ * they state history, not a live contract; only the twin-rationale shapes
+ * below are banned.
+ *
+ * Exit codes: 0 clean · 1 findings.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const SCOPE = path.join(ROOT, 'src', 'scripts');
+
+/** Banned rationale shapes (case-insensitive). */
+export const BANNED: ReadonlyArray<[string, RegExp]> = [
+    ['twin-of', /\btwin of\b/i],
+    ['latent-quirks', /latent (?:python )?(?:quirks|bugs) replicated/i],
+    ['byte-identical-python', /byte-identical to the python/i],
+    ['python-original', /\bthe python original\b/i],
+];
+
+const COMMENT = /^\s*(\/\/|\*|\/\*)/;
+
+function* walk(dir: string): Generator<string> {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
+        a.name < b.name ? -1 : 1,
+    )) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) yield* walk(full);
+        else if (e.name.endsWith('.ts')) yield full;
+    }
+}
+
+export function scan_file(rel: string, text: string): string[] {
+    const findings: string[] = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i]!;
+        if (!COMMENT.test(line)) continue;
+        for (const [name, pat] of BANNED) {
+            if (pat.test(line)) {
+                findings.push(`${rel}:${i + 1}: ${name} — ${line.trim().slice(0, 100)}`);
+            }
+        }
+    }
+    return findings;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const QUIET = argv.includes('--quiet');
+    const findings: string[] = [];
+    for (const f of walk(SCOPE)) {
+        if (path.resolve(f) === path.resolve(_HERE)) continue; // this guard documents the shapes
+        const rel = path.relative(ROOT, f).split(path.sep).join('/');
+        findings.push(...scan_file(rel, fs.readFileSync(f, 'utf-8')));
+    }
+    if (findings.length === 0) {
+        if (!QUIET) process.stdout.write('✅  No Python-twin rationale in src/scripts comments.\n');
+        return 0;
+    }
+    process.stdout.write(`❌  Python-twin rationale reintroduced — ${findings.length} finding(s):\n`);
+    for (const f of findings) process.stdout.write(`    ${f}\n`);
+    process.stdout.write(
+        '\nFix: state the LIVE contract instead (which test/gate/consumer pins the\n' +
+            'behaviour) — never fidelity to the deleted Python original. See\n' +
+            'road-to-truth-and-reference-hygiene Phase 2.\n',
+    );
+    return 1;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/lint_one_off_age.ts

@@ -2,12 +2,12 @@
 /**
  * One-off-script age linter.
  *
- * TypeScript twin of `src/scripts/lint_one_off_age.py` (ADR-200, Phase 4 /
+ * Ported from the retired Python `src/scripts/lint_one_off_age.py` (ADR-200, Phase 4 /
  * Wave 4b). Mirrors the CLI contract EXACTLY — `--format {text,json}` /
  * `--root` argparse flags, exit codes (0 clean incl. warnings, 1 hard
  * fail, 3 internal error), stdout/stderr split, byte-identical finding
  * messages, the same scan tree (`<root>/scripts/_one_off`) and ordering
- * (sorted iterdir). No behaviour changes — latent quirks replicated
+ * (sorted iterdir). Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  * (e.g. `scan` walks `scripts/_one_off`, NOT the module-level
  * `ONE_OFF_DIR = src/scripts/_one_off`, which is unused).
  *

package/src/scripts/lint_orchestration_dsl.ts

@@ -2,8 +2,8 @@
 /**
  * Lint `.agent-config/orchestrations/*.yaml` pipeline files.
  *
- * TypeScript twin of `src/scripts/lint_orchestration_dsl.py` (ADR-200,
- * Phase 4 / Wave 4b). The CLI contract is mirrored EXACTLY — `--dir` /
+ * Ported from the retired Python `src/scripts/lint_orchestration_dsl.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is pinned — `--dir` /
  * `--file` flags, exit codes (0 clean, 1 hard failure, 2 file/schema-load
  * error), stdout/stderr split (all findings on stderr), byte-identical
  * finding messages, same scan order, same `resolve_logical` ref resolution,
@@ -51,7 +51,7 @@ const SUBAGENT_MODES = new Set([
 
 /**
  * Reuse the dispatcher's loader so the linter sees what the runtime sees.
- * The Python original calls `hooks.dispatch_hook._load_yaml`, which prefers
+ * the retired Python implementation calls `hooks.dispatch_hook._load_yaml`, which prefers
  * PyYAML (present in this environment) and falls back to a flat mini-parser
  * only when PyYAML is unavailable. Orchestration files use full nested YAML,
  * so the PyYAML path is the live one — `yaml` (npm) reproduces it.

package/src/scripts/lint_orchestrator_auto_detect.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env tsx
 // Auto-detection contract linter for command orchestrators (6.1.0 Step 1).
 //
-// TypeScript twin of src/scripts/lint_orchestrator_auto_detect.py. Every
+// TypeScript port of the retired Python src/scripts/lint_orchestrator_auto_detect.py. Every
 // command source under src/domains/**/command.md that opts into auto-detection
 // (front-matter `auto_detect: true`) MUST honor the non-interactive contract:
 // a body link to the contract doc + the `## Non-interactive & auto-detection`

package/src/scripts/lint_pack_boundaries.ts

@@ -2,12 +2,12 @@
 /**
  * Enforce cross-pack reference boundaries.
  *
- * TypeScript twin of `src/scripts/lint_pack_boundaries.py` (ADR-200, Phase 4 /
+ * Ported from the retired Python `src/scripts/lint_pack_boundaries.py` (ADR-200, Phase 4 /
  * Wave 4b). Mirrors the Python CLI contract exactly: `--format text|json`,
  * `--quiet`, same scan scope (packages/*\/.agent-src.uncondensed/), file
  * ordering, link regex, resolution semantics, finding messages, stdout/stderr
  * split, and exit codes (0 clean / skipped, 1 violations). No behaviour
- * changes — latent bugs replicated.
+ * changes — historical quirks preserved (consumers pin the exact behaviour).
  *
  * Walks every markdown link in every artefact under
  * `packages/*\/.agent-src.uncondensed/` and verifies the link target's pack is

package/src/scripts/lint_pack_dependencies.ts

@@ -2,7 +2,7 @@
 /**
  * Pack dependency + pack-graph lints.
  *
- * TypeScript twin of `src/scripts/lint_pack_dependencies.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/lint_pack_dependencies.py` (ADR-200,
  * Phase 4 / Wave 4b). Mirrors the Python CLI contract exactly: same checks,
  * finding messages, stdout/stderr split, and exit codes.
  *
@@ -15,7 +15,7 @@
  *
  * Exit codes: 0 = clean · 1 = drift and/or a cycle · 3 = internal error.
  *
- * The Python original imports generate_pack_manifests (`gpm`) for the manifest
+ * the retired Python implementation imports generate_pack_manifests (`gpm`) for the manifest
  * derivation. `gpm` has no TS twin yet (out of this batch's scope), so the
  * needed gpm internals are ported as private helpers below, mirroring the
  * Python source 1:1. They are prefixed `_gpm_` to mark their provenance.

package/src/scripts/lint_pack_first_win.ts

@@ -2,8 +2,8 @@
 /**
  * Pack first-win linter.
  *
- * TypeScript twin of `src/scripts/lint_pack_first_win.py` (ADR-200,
- * Phase 4 / Wave 4b). The CLI contract is mirrored EXACTLY — `main()`
+ * Ported from the retired Python `src/scripts/lint_pack_first_win.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is pinned — `main()`
  * IGNORES argv entirely (any flag, including the `--quiet` the Taskfile
  * passes, is silently accepted), exit codes (0 clean, 1 violations),
  * stdout/stderr split, byte-identical finding messages.

package/src/scripts/lint_persona_governance.ts

@@ -2,11 +2,11 @@
 /**
  * Lint persona governance — per-domain cap (hard) + citation floor (warn).
  *
- * TypeScript twin of `src/scripts/lint_persona_governance.py` (ADR-200,
- * Phase 4 / Wave 4b). Mirrors the Python CLI contract EXACTLY — `--quiet`
+ * Ported from the retired Python `src/scripts/lint_persona_governance.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is pinned — `--quiet`
  * flag read from argv at module load, persona enumeration + sorted ordering,
  * finding messages, output channel (emit → stdout; overflow summary on
- * stderr), exit codes. No behaviour changes — latent bugs replicated.
+ * stderr), exit codes. Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * Enforces the mechanical checks in
  * `.agent-src.uncondensed/rules/persona-governance.md`:

package/src/scripts/lint_positioning.ts

@@ -2,7 +2,7 @@
 /**
  * Positioning consistency lint for event4u/agent-config.
  *
- * TypeScript twin of `src/scripts/lint_positioning.py` (ADR-200, Phase 4 /
+ * Ported from the retired Python `src/scripts/lint_positioning.py` (ADR-200, Phase 4 /
  * Wave 4b). Mirrors the CLI contract EXACTLY — the `--quiet` argparse flag,
  * exit codes (0 clean, 1 drift, 2 missing PyYAML — inert here since `yaml`
  * is always present), byte-identical stdout (success line) and stderr

package/src/scripts/lint_profile_overlay_set_only.ts

@@ -2,8 +2,8 @@
 /**
  * lint_profile_overlay_set_only — freeze the set-only overlay invariant.
  *
- * TypeScript twin of `src/scripts/lint_profile_overlay_set_only.py` (ADR-200,
- * Phase 4 / Wave 4b). Mirrors the Python CLI contract EXACTLY — `--quiet`
+ * Ported from the retired Python `src/scripts/lint_profile_overlay_set_only.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is pinned — `--quiet`
  * flag from argv at module load, four YAML surfaces + sorted *.yml ordering,
  * finding messages (incl. Python `type(x).__name__` and `{x!r}` rendering),
  * stdout/stderr split, exit codes. No behaviour changes — latent bugs

package/src/scripts/lint_readme_jargon.ts

@@ -2,8 +2,8 @@
 /**
  * CI guard for README.md above-fold jargon density.
  *
- * TypeScript twin of `src/scripts/lint_readme_jargon.py` (ADR-200, Phase 4 /
- * Wave 4b). The CLI contract is mirrored EXACTLY — `--quiet` flag, exit
+ * Ported from the retired Python `src/scripts/lint_readme_jargon.py` (ADR-200, Phase 4 /
+ * Wave 4b). The CLI contract is pinned — `--quiet` flag, exit
  * codes (0 within budget, 1 over budget / missing), stdout/stderr split,
  * byte-identical finding messages, same noise-stripping order, same
  * whole-word watchlist matching.

package/src/scripts/lint_readme_size.ts

@@ -2,8 +2,8 @@
 /**
  * CI guard for README.md line budget.
  *
- * TypeScript twin of `src/scripts/lint_readme_size.py` (ADR-200, Phase 4 /
- * Wave 4b). The CLI contract is mirrored EXACTLY — `--quiet` flag, exit
+ * Ported from the retired Python `src/scripts/lint_readme_size.py` (ADR-200, Phase 4 /
+ * Wave 4b). The CLI contract is pinned — `--quiet` flag, exit
  * codes (0 within budget, 1 over budget / missing), stdout/stderr split,
  * byte-identical finding messages.
  *

package/src/scripts/lint_regression.ts

@@ -2,13 +2,13 @@
 /**
  * Detect lint regressions between the current branch and a baseline.
  *
- * TypeScript twin of `src/scripts/lint_regression.py` (ADR-200,
- * Phase 4 / Wave 4b). The CLI contract is mirrored EXACTLY — `--baseline`
+ * Ported from the retired Python `src/scripts/lint_regression.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is pinned — `--baseline`
  * / `--format` / `--repo-root` flags, exit codes (0 clean, 1 regressions /
  * new-files, 2 bad baseline / disjoint-result guard), stdout/stderr split,
  * byte-identical report text (text / json / markdown), the same disjoint
  * sanity guard, and the same worktree-based baseline strategy. snake_case
- * kept. No behaviour changes — latent bugs replicated.
+ * kept. Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * Runs skill_linter --all --format json on both the baseline (via a temp
  * `git worktree`) and the working tree, then compares results to find new

package/src/scripts/lint_roadmap_ci_steps.ts

@@ -2,12 +2,12 @@
 /**
  * Hard-Gate linter for the `roadmap-ci-steps-policy` rule.
  *
- * TypeScript twin of `src/scripts/lint_roadmap_ci_steps.py` (ADR-200,
- * Phase 4 / Wave 4b). The CLI contract is mirrored EXACTLY — `--quiet`
+ * Ported from the retired Python `src/scripts/lint_roadmap_ci_steps.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is pinned — `--quiet`
  * detected by argv membership (no argparse), exit codes (0 / 1),
  * stdout/stderr split, byte-identical messages, same scan scope
  * (`agents/roadmaps/*.md`, sorted) and detection order. No behaviour
- * changes — latent bugs replicated.
+ * changes — historical quirks preserved (consumers pin the exact behaviour).
  *
  * Forbids full-pipeline CI literals (`task ci`, `make test`, `npm run check`
  * etc.) inside `agents/roadmaps/*.md` checkbox steps or fenced bash blocks

package/src/scripts/lint_roadmap_complexity.ts

@@ -2,7 +2,7 @@
 /**
  * Phase 5.2 roadmap-complexity linter.
  *
- * TypeScript twin of `src/scripts/lint_roadmap_complexity.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/lint_roadmap_complexity.py` (ADR-200,
  * Phase 4 / Wave 4b). Mirrors the CLI contract EXACTLY — `--quiet` is a
  * bare `sys.argv` membership check (computed at import, NOT argparse, so
  * there is no real `-h`/`--help`), the per-roadmap `✅`/`❌` lines, the

package/src/scripts/lint_roadmap_later_disposition.ts

@@ -2,8 +2,8 @@
 /**
  * CI guard for the `later/` roadmap disposition.
  *
- * TypeScript twin of `src/scripts/lint_roadmap_later_disposition.py` (ADR-200,
- * Python→TypeScript migration). The CLI contract is mirrored EXACTLY — the
+ * Ported from the retired Python `src/scripts/lint_roadmap_later_disposition.py` (ADR-200,
+ * Python→TypeScript migration). The CLI contract is pinned — the
  * `--json` flag, the argparse usage / error text (`-h`/`--help` → exit 0,
  * unknown arg → exit 2), the scan order (`sorted(root.rglob("*.md"))` —
  * pathlib component-wise), byte-identical human + `--json` output

package/src/scripts/lint_role_experiences.ts

@@ -2,8 +2,8 @@
 /**
  * Linter for `agents/roles/<slug>/` role experiences.
  *
- * TypeScript twin of `src/scripts/lint_role_experiences.py` (ADR-200,
- * Phase 4 / Wave 4b). The CLI contract is mirrored EXACTLY —
+ * Ported from the retired Python `src/scripts/lint_role_experiences.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is pinned —
  * `--plain-language` flag, exit codes (0 pass / roles-dir-absent,
  * 1 failures), stdout/stderr split (all output on stdout), byte-identical
  * finding messages (including Python `sorted(set)` list repr), same scan

package/src/scripts/lint_rule_interactions.ts

@@ -2,7 +2,7 @@
 /**
  * Lint docs/contracts/rule-interactions.yml.
  *
- * TypeScript twin of `src/scripts/lint_rule_interactions.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/lint_rule_interactions.py` (ADR-200,
  * Phase 4 / Wave 4b). Mirrors the CLI contract EXACTLY — the `--quiet`
  * flag is a bare `sys.argv` membership check (NOT argparse, so there is no
  * real `-h`/`--help`), exit codes (1 on any failure, 0 clean), the

package/src/scripts/lint_rule_tiers.ts

@@ -2,7 +2,7 @@
 /**
  * Lint rule frontmatter for the `tier:` key.
  *
- * TypeScript twin of `src/scripts/lint_rule_tiers.py` (ADR-200, Phase 4 /
+ * Ported from the retired Python `src/scripts/lint_rule_tiers.py` (ADR-200, Phase 4 /
  * Wave 4b). Mirrors the Python CLI contract exactly: same scan scope, file
  * ordering, finding messages, stdout/stderr split, and exit codes.
  *

package/src/scripts/lint_showcase_sessions.ts

@@ -2,9 +2,9 @@
 /**
  * Showcase-sessions linter.
  *
- * TypeScript twin of `src/scripts/lint_showcase_sessions.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/lint_showcase_sessions.py` (ADR-200,
  * Phase 4 / Wave 4b). Gates `docs/showcase.md` ↔ `docs/showcase/sessions/`.
- * The CLI contract is mirrored EXACTLY — no flags (argv ignored), exit
+ * The CLI contract is pinned — no flags (argv ignored), exit
  * codes (0 clean, 1 violations), stdout/stderr split, byte-identical
  * finding messages, same reference regex and the same hand-rolled
  * frontmatter parser (including the `_<key>_nested` mapping trick).

package/src/scripts/lint_skill_frontmatter_safety.ts

@@ -1,6 +1,6 @@
 // P1.4 — dangerous-frontmatter linter (road-to-security-pillar.md).
 //
-// TypeScript twin of `src/scripts/lint_skill_frontmatter_safety.py` (ADR-200 —
+// Ported from the retired Python `src/scripts/lint_skill_frontmatter_safety.py` (ADR-200 —
 // Python→TS migration). Behaviour mirrors the Python module byte-for-byte.
 //
 // Enforces the execution-safety contract from the `runtime-safety` rule at the

package/src/scripts/lint_skill_originality.ts

@@ -2,7 +2,7 @@
 /**
  * Anti-duplicate originality gate (road-to-competitive-borrow P1.1).
  *
- * TypeScript twin of `src/scripts/lint_skill_originality.py` (ADR-096). The CLI
+ * Ported from the retired Python `src/scripts/lint_skill_originality.py` (ADR-096). The CLI
  * contract is mirrored EXACTLY — the `--strict` / `--json` / `--quiet` flags
  * (argparse; `-h`/`--help` exit 0, an unrecognized arg exits 2), exit codes
  * (0 = warn-only or strict-clean, 1 = strict + same-domain violation OR no

package/src/scripts/lint_skill_tools.ts

@@ -2,14 +2,14 @@
 /**
  * Block D · D1 meta-linter for `scripts/skill_tools/*.py`.
  *
- * TypeScript twin of `src/scripts/lint_skill_tools.py` (ADR-200,
- * Phase 4 / Wave 4b). The CLI contract is mirrored EXACTLY — `--json`
+ * Ported from the retired Python `src/scripts/lint_skill_tools.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is pinned — `--json`
  * / `--quiet` / `--tools-dir` flags, exit codes (0 clean, 1 violations,
  * 2 usage / missing-dir), stdout split (JSON or human), byte-identical
  * violation strings, same glob + sort order, same `_SAMPLE`/`__main__`
  * detection.
  *
- * The Python original parses each tool with `ast` to find imports and
+ * the retired Python implementation parses each tool with `ast` to find imports and
  * syntax errors. We replicate the import discovery with a focused
  * Python-import line scanner (handles `import a, b.c`, `from x.y import z`,
  * relative `from . import x`). It covers the real tools and the test

package/src/scripts/lint_ticket_buildable.ts

@@ -2,7 +2,7 @@
 /**
  * Lint ticket bundles for build-readiness.
  *
- * TypeScript twin of `src/scripts/lint_ticket_buildable.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/lint_ticket_buildable.py` (ADR-200,
  * Python→TypeScript migration). The behaviour is mirrored EXACTLY — NO argparse
  * (the entry point is `lint()`, which ignores argv entirely; an unknown flag is
  * silently ignored and the lint runs), the scan order
@@ -26,7 +26,7 @@
  * Exit codes: 0 = clean, 1 = lint failures, 3 = IO/setup error. Failures print as
  * ``path:reason``.
  *
- * The Python original uses `jsonschema.Draft7Validator`; this twin hand-rolls a
+ * the retired Python implementation uses `jsonschema.Draft7Validator`; this twin hand-rolls a
  * Draft-07 validator covering exactly the keyword set the two ticket schemas use
  * (type [string | array], required, additionalProperties [false], properties,
  * patternProperties, anyOf, pattern, enum, minLength, minItems, items, minimum,

package/src/scripts/lint_topics_yaml.ts

@@ -2,11 +2,11 @@
 /**
  * Linter for `.github/topics.yml`.
  *
- * TypeScript twin of `src/scripts/lint_topics_yaml.py` (ADR-200, Phase 4 /
- * Wave 4b). Mirrors the Python CLI contract EXACTLY — same scan target,
+ * Ported from the retired Python `src/scripts/lint_topics_yaml.py` (ADR-200, Phase 4 /
+ * Wave 4b). The CLI contract is pinned — same scan target,
  * finding messages (incl. Python `repr()` rendering of offending values),
  * stdout/stderr split, exit codes, and the `--quiet` flag read directly
- * from argv at module load. No behaviour changes — latent bugs replicated.
+ * from argv at module load. Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * Asserts:
  *   * file exists and parses as YAML

package/src/scripts/lint_trust_coherence.ts

@@ -2,12 +2,12 @@
 /**
  * Lint trust/safety coherence across the discovery manifest.
  *
- * TypeScript twin of `src/scripts/lint_trust_coherence.py` (ADR-200,
- * Phase 4 / Wave 4b). Mirrors the Python CLI contract EXACTLY — `--quiet`
+ * Ported from the retired Python `src/scripts/lint_trust_coherence.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is pinned — `--quiet`
  * / `--manifest` / `--router` / `--compiled-src` flags, finding messages,
  * stdout/stderr split (errors + summary on stderr; success on stdout),
  * SystemExit-on-missing-file semantics, exit codes. No behaviour changes —
- * latent bugs replicated.
+ * historical quirks preserved (consumers pin the exact behaviour).
  *
  * Walks the discovery manifest and asserts three invariants:
  *   1. advisory/restricted packs ship a `*safety-floor*` rule;

package/src/scripts/lint_value_dashboard.ts

@@ -2,10 +2,10 @@
 /**
  * Lint `docs/value.md` for structural invariants.
  *
- * TypeScript twin of `src/scripts/lint_value_dashboard.py` (ADR-200,
- * Phase 4 / Wave 4b). The CLI contract is mirrored EXACTLY — `--quiet`
+ * Ported from the retired Python `src/scripts/lint_value_dashboard.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is pinned — `--quiet`
  * flag, exit codes (0 / 1), stdout/stderr split, byte-identical messages,
- * same check order. No behaviour changes — latent bugs replicated.
+ * same check order. Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * Output: one violation per line in non-quiet mode; one-line summary in
  * quiet mode. Exit 0 on clean, 1 on any violation.

package/src/scripts/lint_workflow_security.ts

@@ -2,15 +2,15 @@
 /**
  * WARN-ONLY GitHub Actions workflow security linter.
  *
- * TypeScript twin of `src/scripts/lint_workflow_security.py` (ADR-200,
- * Python→TypeScript migration). The CLI contract is mirrored EXACTLY —
+ * Ported from the retired Python `src/scripts/lint_workflow_security.py` (ADR-200,
+ * Python→TypeScript migration). The CLI contract is pinned —
  * argparse flags (`--strict` / `--quiet` / `--json PATH`, `-h`/`--help`
  * exit 0, unknown arg → exit 2), the scan order (`sorted(glob("*.yml"))`
  * then `sorted(glob("*.yaml"))`), byte-identical finding lines, the
  * `json.dumps(..., indent=2)` (ensure_ascii) `--json` write, the allowlist
  * cap (exit 2 over 20 entries), the stdout/stderr split, and exit codes
  * (0 advisory / 1 strict+HIGH). snake_case kept; PyYAML `on:`→boolean-True
- * key quirk replicated. No behaviour changes — latent quirks replicated.
+ * key quirk replicated. Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * Severity model (council-locked 2026-06-13):
  *   HIGH  — pull_request_target / workflow_run + checkout of untrusted ref;

package/src/scripts/lint_workspace_boundary.ts

@@ -2,8 +2,8 @@
 /**
  * Workspace-boundary drift check — import-edge enforcement.
  *
- * TypeScript twin of `src/scripts/lint_workspace_boundary.py` (ADR-200,
- * Python→TypeScript migration). The CLI contract is mirrored EXACTLY — the
+ * Ported from the retired Python `src/scripts/lint_workspace_boundary.py` (ADR-200,
+ * Python→TypeScript migration). The CLI contract is pinned — the
  * `--quiet` flag, the `sorted(repo.glob(WORKSPACE_GLOB))` scan order (pathlib
  * component-wise), the FORBIDDEN-pattern set (Python `re` → JS `RegExp`, all
  * ASCII so a 1:1 translation), the `# boundary-exception:` pragma skip, the

package/src/scripts/mcp_parity_smoke.ts

@@ -17,7 +17,7 @@
 // Phase 5.1 of `road-to-cloudflare-mcp-hosting.md`. Governed by
 // `docs/contracts/mcp-cloud-scope.md` §A0-cloud.
 //
-// TS twin of mcp_parity_smoke.py (ADR-200 — Python→TS migration). Mirrors the
+// TS port of the retired Python mcp_parity_smoke.py (ADR-200). Mirrors the
 // Python wire surface byte-for-byte: stdout lines, the ✅ / ❌ / ⏭️ markers, the
 // argparse usage / error text (exit 2), and the exit codes. Imports resolve to
 // the already-ported mcp_server/{catalog,prompts,resources,tools}.ts twins —

package/src/scripts/mcp_render.ts

@@ -2,7 +2,7 @@
 /**
  * MCP config renderer — one `mcp.json` → per-tool output files.
  *
- * TypeScript twin of `mcp_render.py` (Phase 8 / Wave 8g).
+ * Ported from the retired Python `mcp_render.py` (Phase 8 / Wave 8g).
  *
  * Reads `mcp.json` at repo root (`{ "servers": { <name>: { command, args,
  * env, cwd } } }`), substitutes `${env:VAR}` placeholders from the

package/src/scripts/mcp_server/catalog.ts

@@ -10,7 +10,7 @@
 // `not_implemented` envelope contract live in
 // `docs/contracts/mcp-tool-stub-envelope.md`.
 //
-// TS twin of catalog.py (py2ts Phase 8). Mirrors the full public surface:
+// TS port of the retired Python catalog.py (ADR-200). Preserves the full public surface:
 //   - NOT_IMPLEMENTED_CODE, CatalogEntry, load_catalog, load_raw,
 //     install_hint, not_implemented_envelope.
 import * as fs from 'node:fs';

package/src/scripts/mcp_server/index.ts

@@ -13,7 +13,7 @@
 // Stability: experimental. Contract: `docs/contracts/mcp-phase-1-scope.md`.
 // Promotion to beta gated on `docs/contracts/mcp-beta-criteria.md`.
 //
-// TS twin of __init__.py (py2ts Phase 8). The Python package barrel exposes
+// TS port of the retired Python __init__.py (ADR-200). The Python package barrel exposes
 // exactly two module-level names: `__version__` and `SERVER_NAME`. Mirrored
 // here as `__version__` (Python wire-surface SemVer name preserved) and
 // SERVER_NAME.

package/src/scripts/mcp_server/metadata.ts

@@ -19,7 +19,7 @@
 // Stderr is the canonical surface in Phase 6; a wire-surface lift can
 // follow once the SDK supports it.
 //
-// TS twin of metadata.py (py2ts Phase 8). Mirrors the full public surface:
+// TS port of the retired Python metadata.py (ADR-200). Preserves the full public surface:
 //   - Signature type, read_package_version, compute_skill_set_signature,
 //     boot_log_line.
 import * as crypto from 'node:crypto';

package/src/scripts/mcp_server/prompts.ts

@@ -16,7 +16,7 @@
 // are skipped and surfaced in the second tuple element of `scan_*`
 // helpers (caller decides whether to log).
 //
-// TS twin of prompts.py (py2ts Phase 8). Mirrors the full public surface:
+// TS port of the retired Python prompts.py (ADR-200). Preserves the full public surface:
 //   PHASE_1_SKILLS, PromptKind, UserTypeMatch, SkillPrompt, load_skill,
 //   load_phase_1_prompts, scan_skills, scan_commands, load_all_prompts,
 //   to_mcp_prompt_meta, PromptCache. The leading-underscore helpers

package/src/scripts/mcp_server/resources.ts

@@ -15,7 +15,7 @@
 // first H1 line (`# Title`) is used as a title-style fallback, else the
 // filename-derived stem.
 //
-// TS twin of resources.py (py2ts Phase 8). Mirrors the full public surface:
+// TS port of the retired Python resources.py (ADR-200). Preserves the full public surface:
 //   ResourceKind, MIME_MARKDOWN, Resource, scan_rules, scan_guidelines,
 //   scan_contexts, load_all_resources, to_mcp_resource_meta, ResourceCache.
 //   Imports `_project_root` + `_strip_frontmatter` from prompts.ts

package/src/scripts/mcp_server/server.ts

@@ -21,7 +21,7 @@
 // `build_server` still accepts a plain `SkillPrompt[]` so the Phase-1
 // contract tests keep passing without touching their fixtures.
 //
-// TS twin of server.py (py2ts Phase 8). The Python module builds on the
+// TS port of the retired Python server.py (ADR-200). The Python module builds on the
 // `mcp` Python SDK (`mcp.server.Server`) and registers handlers via the
 // SDK decorators; the tests poke `server.request_handlers[...]`. There is
 // no `mcp` Python SDK in the TS runtime and the npm

package/src/scripts/mcp_server/telemetry.ts

@@ -19,7 +19,7 @@
 // `record_call` helper swallows OSError + ValueError and emits a single
 // warning to stderr.
 //
-// TS twin of telemetry.py (py2ts Phase 8). Mirrors the full public surface:
+// TS port of the retired Python telemetry.py (ADR-200). Preserves the full public surface:
 //   - Outcome type, TELEMETRY_REL_DIR, TELEMETRY_FILENAME, hash_client_id,
 //     build_record, record_call.
 import * as crypto from 'node:crypto';

package/src/scripts/mcp_server/tools.ts

@@ -27,7 +27,7 @@
 // TextContent block with the JSON-serialized payload, so MCP clients
 // can render structured output.
 //
-// TS twin of tools.py (py2ts Phase 8). Mirrors the full public surface:
+// TS port of the retired Python tools.py (ADR-200). Preserves the full public surface:
 //   STDIO_TRANSPORT, BuiltinTool, ToolHandler, ALLOWLIST, to_mcp_tool_meta,
 //   CATALOG_STUBS, STUB_NAMES, REGISTRY, ToolCache, boot_log_line.
 import * as fs from 'node:fs';

package/src/scripts/mcp_telemetry_health.ts

@@ -18,7 +18,7 @@
 //   ./scripts-run src/scripts/mcp_telemetry_health --allow-missing  # CI mode
 //   ./scripts-run src/scripts/mcp_telemetry_health --json           # machine-readable
 //
-// TS twin of mcp_telemetry_health.py (py2ts). Mirrors the full public
+// TS port of the retired Python mcp_telemetry_health.py (ADR-200). Mirrors the full public
 // surface: HealthReport, resolve_log_path, evaluate, main.
 import * as fs from 'node:fs';
 import * as path from 'node:path';