@event4u/agent-config 8.4.0 → 8.5.0

package/src/scripts/build_proof.ts

@@ -83,6 +83,12 @@ function render(): string {
     }
     L.push('');
     L.push(`**${backed.length} backed claim(s)** — all evidence pointers resolve in CI.`);
+    L.push('');
+    L.push('Artefact counts in public prose (skills, commands, governed rules,');
+    L.push('guidelines, personas) are **generated from source and CI-drift-checked**:');
+    L.push('`update_counts.ts` writes the numbers, `check_artefact_count_messaging.ts`');
+    L.push('fails the build on any count-shaped prose mention that drifts from the');
+    L.push('source count — or on two different numbers for the same artefact kind.');
     if (unbacked.length > 0) {
         L.push('');
         L.push(`We also publish our **debt**: ${unbacked.length} claim(s) are logged as`);

package/src/scripts/build_rule_trigger_matrix.ts

@@ -2,7 +2,7 @@
 /**
  * Build agents/settings/contexts/rule-trigger-matrix.md.
  *
- * TypeScript twin of `src/scripts/build_rule_trigger_matrix.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/build_rule_trigger_matrix.py` (ADR-200,
  * Phase 8 / Wave 8g). Mirrors the Python contract EXACTLY — same generated
  * markdown (byte-identical), same `CLASSIFICATION` table, same stdout
  * (`✅  Wrote …` line) + stderr (unclassified-rule warning) split, exit codes
@@ -340,7 +340,7 @@ function emit(): number {
     lines.push('');
     lines.push('**Source:** Phase 1 of `road-to-rule-hardening.md` (self-check audit) +');
     lines.push('Phase 1 of `road-to-context-layer-maturity.md` (`load_context:` inventory).');
-    lines.push('**Generated by:** `scripts/build_rule_trigger_matrix.py` — re-run after rule');
+    lines.push('**Generated by:** `src/scripts/build_rule_trigger_matrix.ts` — re-run after rule');
     lines.push("set changes. Manual classifications live in the script's `CLASSIFICATION`");
     lines.push('table; size and context-chain columns are derived from the rule files.');
     lines.push('');

package/src/scripts/capture_showcase_session.ts

@@ -2,7 +2,7 @@
 /**
  * capture_showcase_session.ts — wrap and measure showcase sessions.
  *
- * TypeScript twin of `src/scripts/capture_showcase_session.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/capture_showcase_session.py` (ADR-200 —
  * Python→TS migration, Phase 8 / Wave 8g). Mirrors the Python CLI contract
  * EXACTLY — the `capture` / `metrics` subcommands, every flag, exit codes
  * (0 success / 1 user error / 2 metric-gate pending), the stdout/stderr
@@ -24,8 +24,8 @@
  *
  * `commit_sha` (git HEAD) and `started`/`ended` (now) are non-deterministic;
  * golden parity supplies fixed timestamps via `--started`/`--ended` and
- * excludes `commit_sha`. No behaviour changes — latent Python quirks
- * replicated.
+ * excludes `commit_sha`. No behaviour changes — historical quirks
+ * preserved.
  */
 import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';

package/src/scripts/chat_history.ts

@@ -1,6 +1,6 @@
 // Persistent chat-history log for crash recovery.
 //
-// TypeScript twin of `src/scripts/chat_history.py` (ADR-200 — Python→TS
+// Ported from the retired Python `src/scripts/chat_history.py` (ADR-200 — Python→TS
 // migration). Public API mirrors the Python module exactly (snake_case kept
 // deliberately) so callers — including the MCP tools layer
 // (`src/scripts/mcp_server/tools.ts`) — depend on one source of truth.

package/src/scripts/check_always_budget.ts

@@ -3,7 +3,7 @@
  * Always-rule budget gate (Phases 7.1 + 7.4 of road-to-pr-34-followups,
  * extended by Phase 0.2 of road-to-structural-optimization).
  *
- * TypeScript twin of `src/scripts/check_always_budget.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/check_always_budget.py` (ADR-200 —
  * Python→TS migration, Phase 4 / Wave 4a). Mirrors the Python CLI
  * contract exactly: flags (`--quiet`, `--no-trend`), exit codes
  * (0 = pass/warn, 1 = fail, 3 = internal error), stdout/stderr split,

package/src/scripts/check_artefact_checksums.ts

@@ -2,14 +2,14 @@
 /**
  * Phase-6 checksum-stability gate (monorepo Phase 2, ADR-015).
  *
- * TypeScript twin of `src/scripts/check_artefact_checksums.py` (ADR-200,
- * Phase 4 / Wave 4c). The CLI contract is mirrored EXACTLY — `--manifest`
+ * Ported from the retired Python `src/scripts/check_artefact_checksums.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — `--manifest`
  * / `--quiet` flags, exit codes (0 match, 1 drift / malformed / missing),
  * stdout/stderr split, byte-identical messages, the same per-artefact
  * checksum recomputation and the same error truncation (first 20 + "… and N
- * more"). No behaviour changes — latent bugs replicated.
+ * more"). Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
- * The Python original imports `_artefact_checksum` + `_CATEGORY_SCHEMA` from
+ * the retired Python implementation imports `_artefact_checksum` + `_CATEGORY_SCHEMA` from
  * `build_discovery_manifest.py` (which has no TS twin yet). To keep the TS
  * twin self-contained AND in lockstep, the checksum primitive is ported
  * inline here from `build_discovery_manifest._artefact_checksum` /

package/src/scripts/check_artefact_count_messaging.ts

@@ -0,0 +1,197 @@
+#!/usr/bin/env tsx
+/**
+ * Artefact-count messaging gate (road-to-truth-and-reference-hygiene Phase 1).
+ *
+ * Generalises `check_command_count_messaging.ts` (which stays wired as
+ * `task check-command-count` — its badge/browse anchors are required-check
+ * contract surface and are NOT removed here) from commands-only to every
+ * artefact kind: any count-shaped prose mention of skills / commands /
+ * governed rules / guidelines / personas on a flagship public surface must
+ * equal the canonical source count, and no surface may carry two DIFFERENT
+ * numbers for the same kind (the 150-vs-162-vs-166 failure mode that
+ * motivated this gate).
+ *
+ * Ownership split:
+ *   - `update_counts.ts` GENERATES the numbers into anchored positions
+ *     (badges + prose) and `--check`s those exact anchors.
+ *   - THIS gate SCANS the flagship surfaces for any count-shaped phrase —
+ *     anchored or not — so a hand-typed new sentence with a stale number
+ *     fails CI even though no anchor covers it yet.
+ *   - `check_command_count_messaging.ts` keeps the command-specific
+ *     active-vs-shim split checks.
+ *
+ * Scope: flagship surfaces only (SURFACES below). Dated census / analysis
+ * snapshots (SKILL_CENSUS, skills-taxonomy, positioning-evidence, …) carry
+ * point-in-time counts by design and are deliberately out of scope — the
+ * gate's charter is the surfaces a fresh reader treats as current.
+ *
+ * Exit codes: 0 clean · 1 drift or internal inconsistency.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { canonical_counts } from './check_command_count_messaging.js';
+import { count } from './update_counts.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** Flagship public prose surfaces (repo-relative). Missing files are skipped
+ * with a warning so a doc rename does not hard-break the gate. */
+export const SURFACES: readonly string[] = [
+    'README.md',
+    'AGENTS.md',
+    'llms.txt',
+    'docs/CLAIMS.md',
+    'docs/getting-started.md',
+    'docs/getting-started-by-role.md',
+    'docs/architecture.md',
+    'docs/command-flows.md',
+    'docs/governance-advantage.md',
+    'docs/featured-skills.md',
+    'docs/featured-commands.md',
+    'docs/proof.md',
+    'site/src/content/docs/index.mdx',
+    'site/src/content/docs/claims.md',
+];
+
+/** kind → canonical-count resolver. "governed rules" is the canonical total
+ * phrasing for rules; bare "N rules" is NOT matched (too many legitimate
+ * subset scopes: kernel rules, router rules, maintainer-only rules …). */
+const KIND_PATTERNS: ReadonlyArray<[string, RegExp]> = [
+    ['skills', /(~?)(\d+)\+?\s+skills\b/g],
+    ['commands', /(~?)(\d+)\+?\s+commands\b/g],
+    ['rules', /(~?)(\d+)\+?\s+governed rules\b/g],
+    ['guidelines', /(~?)(\d+)\+?\s+guidelines\b/g],
+    ['personas', /(~?)(\d+)\+?\s+personas\b/g],
+];
+
+export interface Finding {
+    file: string;
+    line: number;
+    kind: string;
+    found: number;
+    expected: number;
+    approx: boolean;
+}
+
+export function canonical_for(kind: string): number {
+    if (kind === 'commands') {
+        // Prose command mentions carry the ACTIVE count (total − shims),
+        // matching the hero badge owned by check_command_count_messaging.
+        const [, , active] = canonical_counts();
+        return active;
+    }
+    return count(kind);
+}
+
+/** Scan one text body; returns findings + the per-kind numbers seen. */
+export function scan_text(
+    rel: string,
+    text: string,
+    expected: Readonly<Record<string, number>>,
+): { findings: Finding[]; seen: Record<string, Set<number>> } {
+    const findings: Finding[] = [];
+    const seen: Record<string, Set<number>> = {};
+    const lines = text.split('\n');
+    for (const [kind, pattern] of KIND_PATTERNS) {
+        for (let i = 0; i < lines.length; i++) {
+            const re = new RegExp(pattern.source, pattern.flags);
+            for (const m of lines[i]!.matchAll(re)) {
+                const found = Number.parseInt(m[2]!, 10);
+                (seen[kind] ??= new Set()).add(found);
+                const exp = expected[kind]!;
+                const approx = m[1] === '~';
+                if (found !== exp || approx) {
+                    findings.push({ file: rel, line: i + 1, kind, found, expected: exp, approx });
+                }
+            }
+        }
+    }
+    return { findings, seen };
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const QUIET = argv.includes('--quiet');
+    const expected: Record<string, number> = {};
+    for (const [kind] of KIND_PATTERNS) {
+        expected[kind] = canonical_for(kind);
+    }
+    process.stdout.write(
+        `Canonical: skills=${expected['skills']} commands=${expected['commands']} ` +
+            `rules=${expected['rules']} guidelines=${expected['guidelines']} ` +
+            `personas=${expected['personas']}\n`,
+    );
+
+    const allFindings: Finding[] = [];
+    const global_seen: Record<string, Set<number>> = {};
+    for (const rel of SURFACES) {
+        const p = path.join(ROOT, rel);
+        if (!fs.existsSync(p)) {
+            process.stderr.write(`  ⚠️  surface missing (skipped): ${rel}\n`);
+            continue;
+        }
+        const { findings, seen } = scan_text(rel, fs.readFileSync(p, 'utf-8'), expected);
+        allFindings.push(...findings);
+        for (const [kind, nums] of Object.entries(seen)) {
+            for (const n of nums) (global_seen[kind] ??= new Set()).add(n);
+        }
+    }
+
+    // Internal-inconsistency check — the regression case this gate exists
+    // for: multiple DIFFERENT numbers for one kind across the surfaces.
+    const inconsistent: string[] = [];
+    for (const [kind, nums] of Object.entries(global_seen)) {
+        if (nums.size > 1) {
+            inconsistent.push(`${kind}: {${[...nums].sort((a, b) => a - b).join(', ')}}`);
+        }
+    }
+
+    if (allFindings.length === 0 && inconsistent.length === 0) {
+        if (!QUIET) {
+            process.stdout.write('✅  All artefact-count prose in sync with source.\n');
+        }
+        return 0;
+    }
+
+    process.stdout.write(
+        `❌  Artefact-count messaging drift — ${allFindings.length} mismatch(es):\n`,
+    );
+    for (const f of allFindings) {
+        const tag = f.approx ? ' (approximation "~" not allowed on flagship surfaces)' : '';
+        process.stdout.write(
+            `    ${f.file}:${f.line}: ${f.kind} says ${f.found}, expected ${f.expected}${tag}\n`,
+        );
+    }
+    for (const line of inconsistent) {
+        process.stdout.write(`    internal inconsistency — ${line}\n`);
+    }
+    process.stdout.write(
+        '\nFix: run `./scripts-run src/scripts/update_counts` for anchored positions,\n' +
+            'or correct the prose to the canonical number (never hand-type a new one).\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 {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/check_augment_description_cap.ts

@@ -3,11 +3,11 @@
  * Auto-rule description-length CI gate (Phase 1.3 of
  * road-to-augment-limit-fit).
  *
- * TypeScript twin of `src/scripts/check_augment_description_cap.py` (ADR-200,
- * Phase 4 / Wave 4c). The CLI contract is mirrored EXACTLY — no flags, exit
+ * Ported from the retired Python `src/scripts/check_augment_description_cap.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — no flags, exit
  * codes (0 pass, 1 over-cap), stdout/stderr split, byte-identical finding
  * messages, same scan scope (`.agent-src.uncondensed/rules/*.md`) and file
- * ordering. No behaviour changes — latent bugs replicated.
+ * ordering. Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * For every `type: auto` rule under `.agent-src.uncondensed/rules/`,
  * fail CI when the frontmatter `description:` exceeds DESC_CAP chars.

package/src/scripts/check_augmentignore.ts

@@ -2,7 +2,7 @@
 /**
  * Advisory check for `.augmentignore` (road-to-governance-cleanup F6.3).
  *
- * TypeScript twin of `src/scripts/check_augmentignore.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/check_augmentignore.py` (ADR-200,
  * Phase 4 / Wave 4c). CLI contract mirrored EXACTLY — `--quiet` flag,
  * always exits 0, byte-identical advisory messages, same staleness /
  * min-useful-lines thresholds, stdout-only output.

package/src/scripts/check_beta_review_markers.ts

@@ -2,12 +2,12 @@
 /**
  * Beta-review-marker checker for `docs/contracts/`.
  *
- * TypeScript twin of `src/scripts/check_beta_review_markers.py` (ADR-200,
- * Phase 4 / Wave 4c). The CLI contract is mirrored EXACTLY — `--json`
+ * Ported from the retired Python `src/scripts/check_beta_review_markers.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — `--json`
  * flag, exit codes (0 clean, 1 violations, 3 internal error), stdout/stderr
  * split, byte-identical messages, the same scan order and the same date
  * arithmetic (`keep-beta-until` ≤ today + 90 days). No behaviour changes —
- * latent bugs replicated.
+ * historical quirks preserved (consumers pin the exact behaviour).
  *
  * Every contract whose frontmatter declares `stability: beta` MUST carry
  * exactly one of `promote-to: stable` | `keep-beta-until: YYYY-MM-DD` |

package/src/scripts/check_bite_sized_granularity.ts

@@ -2,7 +2,7 @@
 /**
  * Bite-sized task granularity gate for structural roadmaps (P1.5).
  *
- * TypeScript twin of `src/scripts/check_bite_sized_granularity.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/check_bite_sized_granularity.py` (ADR-200,
  * Phase 4 / Wave 4c). This module is a pure library (no CLI / main); the
  * Python module is imported as a test surface. The exported API mirrors the
  * Python public API EXACTLY:

package/src/scripts/check_cluster_patterns.ts

@@ -2,17 +2,22 @@
 /**
  * Cluster-pattern compliance check.
  *
- * TypeScript twin of `src/scripts/check_cluster_patterns.py` (ADR-200,
- * Phase 4 / Wave 4c). The CLI contract is mirrored EXACTLY — no flags,
+ * Ported from the retired Python `src/scripts/check_cluster_patterns.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — no flags,
  * exit codes (0 clean, 1 pattern violations, 3 internal error),
  * stdout/stderr split, byte-identical finding messages, the same
  * locked-clusters table parse, the same domains slug map (via the
  * `_lib/agent_src` twin), and the same dispatcher-structure checks. No
- * behaviour changes — latent bugs replicated.
+ * behaviour changes — historical quirks preserved (consumers pin the exact behaviour).
  *
  * Compares each cluster dispatcher against the Phase 1 reference patterns
  * (`fix`, `optimize`, `feature`).
  *
+ * Phase 4 additions (ADR-115): every `routes_to:` entry on a dispatcher must
+ * resolve to a real src/domains command slug, and the `## Dispatch` section
+ * must document the bare-invocation behaviour (menu / default route /
+ * detection fallback) per command-clusters.md § Bare invocation.
+ *
  * Exit codes: 0 = clean, 1 = pattern violations, 3 = internal error.
  */
 
@@ -212,6 +217,45 @@ export function check_dispatcher(cluster: string, slug_map: Map<string, string>)
     if (body.includes('## Sub-commands') && !TABLE_HEADER_RE.test(body)) {
         rep.errors.push('Sub-commands table header must be `| Sub-command | Routes to | Purpose |`');
     }
+
+    // routes_to entries must resolve to real commands (Phase 4 / ADR-115).
+    const routesRaw = fm['routes_to'];
+    if (routesRaw !== undefined) {
+        const m = /^\[(.*)\]$/.exec(routesRaw.trim());
+        const entries = m
+            ? (m[1] as string)
+                  .split(',')
+                  .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+                  .filter((s) => s.length > 0)
+            : [];
+        for (const entry of entries) {
+            // routes_to entries name either a command slug or a skill
+            // (e.g. `git-commit` routes to the `git-workflow` skill).
+            const skillPath = path.join(ROOT, 'src', 'skills', entry, 'SKILL.md');
+            if (!slug_map.has(entry) && !_isFile(skillPath)) {
+                rep.errors.push(
+                    `routes_to entry \`${entry}\` resolves to no src/domains command slug ` +
+                        'and no src/skills skill',
+                );
+            }
+        }
+    }
+
+    // Bare-invocation story (Phase 4 / ADR-115): the Dispatch section must say
+    // what a bare `/<cluster>` does — a menu, a default route, or detection.
+    const dispatchIdx = body.indexOf('## Dispatch');
+    if (dispatchIdx !== -1) {
+        const rest = body.slice(dispatchIdx + '## Dispatch'.length);
+        const nextSection = rest.search(/\n## /);
+        const section = nextSection === -1 ? rest : rest.slice(0, nextSection);
+        if (!/menu|bare|no argument|unknown or missing|detection|default/i.test(section)) {
+            rep.errors.push(
+                '`## Dispatch` must document the bare-invocation behaviour ' +
+                    '(menu, default route, or detection fallback) per ' +
+                    'command-clusters.md § Bare invocation',
+            );
+        }
+    }
     return rep;
 }
 

package/src/scripts/check_command_count_messaging.ts

@@ -2,8 +2,8 @@
 /**
  * Command-count messaging gate (road-to-pr-34-followups 1.2).
  *
- * TypeScript twin of `src/scripts/check_command_count_messaging.py`
- * (ADR-200, Phase 4 / Wave 4c). Mirrors the Python CLI contract EXACTLY —
+ * Ported from the retired Python `src/scripts/check_command_count_messaging.py`
+ * (ADR-200, Phase 4 / Wave 4c). The CLI contract is pinned —
  * `--quiet` flag (positional anywhere in argv), exit codes (0 clean,
  * 1 drift, 1 no-commands-dir via stderr), stdout/stderr split,
  * byte-identical messages, same canonical-count derivation

package/src/scripts/check_condensation.ts

@@ -2,7 +2,7 @@
 /**
  * Condensation quality checker for agent-config packages.
  *
- * TypeScript twin of `src/scripts/check_condensation.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/check_condensation.py` (ADR-200 —
  * Python→TS migration, Phase 4 / Wave 4a). Mirrors the Python CLI
  * contract exactly: flags (`--format text|json`, `--summary`, `--root`),
  * exit codes (0 = clean, 1 = issues found, 3 = internal error),
@@ -19,7 +19,7 @@
  *   Iron Laws / numbered) preserved per `preservation-guard`: heading
  *   verbatim at original level, structural-unit survival.
  *
- * The Python original imports `_rewrite_paths` from `condense.py` to
+ * the retired Python implementation imports `_rewrite_paths` from `condense.py` to
  * normalise the source side through the same path transformations the
  * condenseor applies. `condense.py` is not yet ported (later phase), so
  * that path-rewriter chain is replicated faithfully below as a private

package/src/scripts/check_condensed_paths.ts

@@ -2,7 +2,7 @@
 /**
  * Validate condensed-output paths in `dist/agent-src/rules/*.md`.
  *
- * TypeScript twin of `src/scripts/check_condensed_paths.py` (ADR-200). Mirrors
+ * Ported from the retired Python `src/scripts/check_condensed_paths.py` (ADR-200). Mirrors
  * the Python CLI contract EXACTLY — same `--quiet` flag, same exit codes
  * (0 clean, 1 violations, 3 internal error), same stdout/stderr split, same
  * finding text, same forbidden-substring set, same frontmatter parsing, same
@@ -49,14 +49,14 @@ import type * as YamlModule from 'yaml';
 
 // ESM-standard `require` shim. The bare `require` global is present when this
 // module is *imported* (tsx injects it) but absent when the module is the
-// directly-executed CLI entry, so resolve it explicitly here to mirror the
-// Python original's lazy `import yaml` in both execution modes.
+// directly-executed CLI entry, so resolve it explicitly here to preserve the
+// historical lazy `import yaml` semantics in both execution modes.
 const _require = createRequire(import.meta.url);
 
 const QUIET = process.argv.includes('--quiet');
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
-// _HERE === <repo>/src/scripts ; the Python original derives ROOT from
+// _HERE === <repo>/src/scripts ; the retired Python implementation derives ROOT from
 // Path(__file__).resolve().parent.parent.parent which is the repo root
 // (src/scripts/check_condensed_paths.py → up three dirs).
 const ROOT = path.resolve(_HERE, '..', '..');
@@ -160,8 +160,8 @@ function _split_frontmatter(text: string): [Frontmatter | null, string] {
     }
     let fm: unknown;
     try {
-        // version '1.1' matches PyYAML's safe_load semantics used by the
-        // Python original (yaml.safe_load).
+        // version '1.1' matches the PyYAML safe_load semantics the frontmatter
+        // corpus was authored against (yaml.safe_load).
         fm = YAML.parse(fmText, { version: '1.1' });
     } catch {
         return [null, text];

package/src/scripts/check_context_paths.ts

@@ -2,7 +2,7 @@
 /**
  * Context-file path & orphan checker.
  *
- * TypeScript twin of `src/scripts/check_context_paths.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/check_context_paths.py` (ADR-200,
  * Phase 4 / Wave 4c). CLI contract mirrored EXACTLY — `--format`
  * (text/json) and `--root` flags, exit codes (0 clean, 1 violations,
  * 3 internal error), byte-identical messages, stdout-only output, same

package/src/scripts/check_council_config_location.ts

@@ -2,12 +2,12 @@
 /**
  * CI guard: council config lives in `.ai-council.yml`, never `.agent-settings.yml`.
  *
- * TypeScript twin of `src/scripts/check_council_config_location.py` (ADR-200).
- * The CLI contract is mirrored EXACTLY — `--quiet` flag, exit codes (0 clean,
+ * Ported from the retired Python `src/scripts/check_council_config_location.py` (ADR-200).
+ * The CLI contract is pinned — `--quiet` flag, exit codes (0 clean,
  * 1 at least one violation), byte-identical finding messages, same scan globs
  * (sorted), same fence tracking, same negation / `ai_council:` block detection,
  * and the same `<!-- council-config-allowed -->` escape pragma. No behaviour
- * changes — latent bugs replicated.
+ * changes — historical quirks preserved (consumers pin the exact behaviour).
  *
  * Per ADR-104 (superseding ADR-093) the council reads a dedicated
  * `.ai-council.yml` resolved ALWAYS from the user-global location

package/src/scripts/check_council_layout.ts

@@ -2,8 +2,8 @@
 /**
  * CI guard for the `ai-council` skill's output-path convention.
  *
- * TypeScript twin of `src/scripts/check_council_layout.py` (ADR-200,
- * Phase 4 / Wave 4c). Mirrors the Python CLI contract EXACTLY — `--quiet`
+ * Ported from the retired Python `src/scripts/check_council_layout.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — `--quiet`
  * flag (positional anywhere in argv), exit codes (0 clean, 1 violations),
  * stdout, byte-identical finding messages, same `agents/` scan,
  * sorted-iterdir + sorted-rglob ordering, same exemptions. No behaviour

package/src/scripts/check_council_references.ts

@@ -2,8 +2,8 @@
 /**
  * CI guard for the council clause of the `no-roadmap-references` rule.
  *
- * TypeScript twin of `src/scripts/check_council_references.py` (ADR-200,
- * Phase 4 / Wave 4a). The CLI contract is mirrored EXACTLY — `--quiet`
+ * Ported from the retired Python `src/scripts/check_council_references.py` (ADR-200,
+ * Phase 4 / Wave 4a). The CLI contract is pinned — `--quiet`
  * flag, exit codes (0 clean, 1 forbidden refs), stdout/stderr split,
  * byte-identical finding + footer text, same scan roots / order, and the
  * same STRUCTURAL_CARVEOUTS logic. No behaviour changes — latent bugs

package/src/scripts/check_discovery_determinism.ts

@@ -2,12 +2,12 @@
 /**
  * Determinism check — runs the discovery scanner twice and diffs the output.
  *
- * TypeScript twin of `src/scripts/check_discovery_determinism.py` (ADR-200,
- * Phase 4 / Wave 4c). The CLI contract is mirrored EXACTLY — no flags,
+ * Ported from the retired Python `src/scripts/check_discovery_determinism.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — no flags,
  * exit codes (0 deterministic, 1 drift), stdout/stderr split, byte-identical
  * messages, and the same `generated_at` normalization + sorted-key JSON
  * comparison. The scanner itself (`build_discovery_manifest.ts`) is run via the
- * repo-local `tsx` binary, mirroring how the Python original invoked the
+ * repo-local `tsx` binary, mirroring how the retired Python implementation invoked the
  * scanner via `sys.executable`. No behaviour changes.
  *
  * Exit codes:

package/src/scripts/check_gate_paths.ts

@@ -2,13 +2,13 @@
 /**
  * Gate path-integrity check (R2 of road-to-test-and-gate-integrity).
  *
- * TypeScript twin of `src/scripts/check_gate_paths.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/check_gate_paths.py` (ADR-200,
  * Phase 4 / Wave 4c). CLI contract mirrored EXACTLY — no flags, exit
  * codes (0 all resolve, 1 missing / out-of-tree, 2 a gate failed to
  * import / lacks GATE_CORE_PATHS), byte-identical messages, stdout/stderr
  * split, same gate list / source-tree roots.
  *
- * The Python original read each gate's ACTUAL enforced paths via that
+ * the retired Python implementation read each gate's ACTUAL enforced paths via that
  * module's `GATE_CORE_PATHS` attribute (`importlib.import_module`) — it
  * did NOT re-declare a copy of the path strings. The gate `.py` modules are
  * gone (ADR-200); the ported `.ts` twins each export `GATE_CORE_PATHS`, so
@@ -72,7 +72,7 @@ function _is_under_source_tree(p: string): boolean {
  * missing-or-empty GATE_CORE_PATHS — surfaced as exit 2 by `main`.
  *
  * The gate `.py` modules are gone (ADR-200); the `.ts` twins each export a
- * module-level `GATE_CORE_PATHS`. The Python original read the gate's REAL
+ * module-level `GATE_CORE_PATHS`. the retired Python implementation read the gate's REAL
  * paths via `importlib` + `getattr` and never copied them — this keeps that
  * property by importing the twin and reading its exported constant. A `tsx`
  * subprocess (not an in-process dynamic `import()`) is used so this function
@@ -147,7 +147,7 @@ function collect_gate_paths(gate_modules: readonly string[]): Map<string, string
     if ((typeof proc.status === 'number' ? proc.status : 1) !== 0) {
         // tsx unavailable or crashed before producing JSON — treat as an
         // import failure (exit 2 path), matching the "a gate failed to import"
-        // semantics of the Python original.
+        // semantics of the retired Python implementation.
         const err = new Error(
             (proc.stderr ?? '').trim() || 'gate introspection failed',
         ) as Error & { kind: string };

package/src/scripts/check_iron_law_prominence.ts

@@ -3,8 +3,8 @@
  * Iron Law prominence checker — enforces that any rule file declaring an
  * "Iron Law" places it at the top of the file at H2 level.
  *
- * TypeScript twin of `src/scripts/check_iron_law_prominence.py` (ADR-200,
- * Phase 4 / Wave 4c). The CLI contract is mirrored EXACTLY — positional
+ * Ported from the retired Python `src/scripts/check_iron_law_prominence.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — positional
  * paths (default `.agent-src.uncondensed/rules`), `--format` / `--quiet`
  * flags, exit codes (0 clean, 1 violations, 3 internal error),
  * stdout/stderr split, byte-identical finding messages, and the same

package/src/scripts/check_kernel_rule_bundle.ts

@@ -2,13 +2,13 @@
 /**
  * check_kernel_rule_bundle — Phase 4.2 of road-to-always-budget-relief.
  *
- * TypeScript twin of `src/scripts/check_kernel_rule_bundle.py` (ADR-200,
- * Phase 4 / Wave 4c). The CLI contract is mirrored EXACTLY — `--base-ref`
+ * Ported from the retired Python `src/scripts/check_kernel_rule_bundle.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — `--base-ref`
  * / `--label` / `--event-path` / `--files` flags, exit codes (0 pass,
  * 1 fail, 3 internal error), stdout/stderr split, byte-identical finding
  * messages, the same git-diff invocation, base-ref candidate order, and
  * PR-label parsing from the GitHub event JSON. No behaviour changes —
- * latent bugs replicated.
+ * historical quirks preserved (consumers pin the exact behaviour).
  *
  * Fails when a single PR (or commit range) modifies more than one
  * kernel rule under `.agent-src.uncondensed/rules/`. Override via the