@event4u/agent-config 7.5.0 → 8.1.0

package/src/scripts/lint_roadmap_complexity.ts

@@ -42,6 +42,9 @@ const COUNCIL_PAT = /^## Council Round \d+\b/m;
 const VERDICT_PAT = /^### Verdict\b/m;
 // re.compile(r"^complexity:\s*(lightweight|structural)\s*$", re.MULTILINE)
 const COMPLEXITY_PAT = /^complexity:\s*(lightweight|structural)\s*$/m;
+// execution.mode (templates/roadmaps.md rule 18): nested under `execution:`.
+const EXEC_MODE_PAT = /^execution:[^\S\n]*\n(?:[ \t]+(?!mode:).*\n)*[ \t]+mode:[ \t]*([^\s#]+)/m;
+const EXEC_MODE_VALUES = new Set(['autonomous', 'phase-checkpoints', 'interactive']);
 
 // Plate / horizon detection — template rule 16 forbids time-boxed plates.
 const PLATE_PATS: ReadonlyArray<readonly [RegExp, string]> = [
@@ -161,7 +164,11 @@ function _check_no_plate(text: string, problems: string[]): void {
     }
 }
 
-function lint_roadmap(p: string, horizon_weeks: number): string[] {
+function lint_roadmap(
+    p: string,
+    horizon_weeks: number,
+    warnings?: string[],
+): string[] {
     const text = fs.readFileSync(p, 'utf-8');
     const line_count = _countChar(text, '\n') + (text && !text.endsWith('\n') ? 1 : 0);
     const problems: string[] = [];
@@ -180,9 +187,77 @@ function lint_roadmap(p: string, horizon_weeks: number): string[] {
     if (horizon_weeks <= 0) {
         _check_no_plate(text, problems);
     }
+    _check_execution_mode(fm, problems);
+    if (warnings) {
+        _check_autonomous_authoring(text, fm, warnings);
+    }
     return problems;
 }
 
+// Vague-step patterns (ask-when-uncertain trigger subset) — under
+// execution.mode: autonomous these guarantee mid-run ambiguity halts,
+// so they warn at authoring time instead. Warnings never fail the lint.
+const VAGUE_STEP_PATS: Array<[RegExp, string]> = [
+    [/\b(improve|optimi[sz]e)\b(?!.*\bby\b)/i, "'improve / optimize' without a measurable target"],
+    [/\bmake (it|this|.{0,30}) (better|cleaner|nicer)\b/i, "'make it better/cleaner'"],
+    [/\bclean ?up\b(?!.*\(<)/i, "'clean up' without named scope"],
+    [/\bfix (this|it)\b/i, "'fix this' without a symptom"],
+    [/\buse best practices\b/i, "'use best practices'"],
+    [/\bhandle errors properly\b/i, "'handle errors properly'"],
+];
+
+function _check_autonomous_authoring(text: string, fm: string, warnings: string[]): void {
+    const m = EXEC_MODE_PAT.exec(fm);
+    if (m === null || m[1]!.replace(/^['"]|['"]$/g, '') !== 'autonomous') {
+        return;
+    }
+    const deferred = _countMatches(/^\s*-\s*\[~\]/m, text);
+    if (deferred > 0) {
+        warnings.push(
+            `execution.mode: autonomous with ${deferred} pre-existing [~] deferred item(s) — ` +
+                'the deferred-resolution archival gate (roadmap-progress-sync Iron Law 3) ' +
+                'WILL interrupt the run at the end; resolve or re-author them now',
+        );
+    }
+    for (const rawLine of text.split('\n')) {
+        if (!/^\s*-\s*\[ \]/.test(rawLine)) {
+            continue;
+        }
+        for (const [re, label] of VAGUE_STEP_PATS) {
+            if (re.test(rawLine)) {
+                warnings.push(
+                    `vague step under execution.mode: autonomous (${label}): ` +
+                        `"${rawLine.trim().slice(0, 80)}" — vagueness resolves cheaply at ` +
+                        'authoring time, expensively as a mid-run ambiguity halt',
+                );
+                break;
+            }
+        }
+    }
+}
+
+function _check_execution_mode(fm: string, problems: string[]): void {
+    if (!fm || !/^execution:/m.test(fm)) {
+        return; // absent field = interactive default — valid
+    }
+    const m = EXEC_MODE_PAT.exec(fm);
+    if (m === null) {
+        problems.push(
+            "'execution:' frontmatter block present but no 'mode:' key found " +
+                "(expected execution.mode: autonomous | phase-checkpoints | interactive " +
+                'per templates/roadmaps.md rule 18)',
+        );
+        return;
+    }
+    const value = m[1]!.replace(/^['"]|['"]$/g, '');
+    if (!EXEC_MODE_VALUES.has(value)) {
+        problems.push(
+            `unknown execution.mode '${value}' — allowed: autonomous | ` +
+                'phase-checkpoints | interactive (templates/roadmaps.md rule 18)',
+        );
+    }
+}
+
 function main(): number {
     const roadmaps = _globRoadmaps();
     const horizon_weeks = _read_horizon_weeks();
@@ -196,7 +271,11 @@ function main(): number {
     const summary: Array<[string, string]> = [];
     for (const roadmap of roadmaps) {
         const rel = _relPosix(roadmap, REPO_ROOT);
-        const problems = lint_roadmap(roadmap, horizon_weeks);
+        const warnings: string[] = [];
+        const problems = lint_roadmap(roadmap, horizon_weeks, warnings);
+        for (const w of warnings) {
+            process.stderr.write(`⚠️  ${rel}\n    - ${w}\n`);
+        }
         const text = fs.readFileSync(roadmap, 'utf-8');
         const complexity = _read_complexity(_frontmatter(text)) ?? 'untagged';
         summary.push([rel, complexity]);

package/src/scripts/lint_subagent_determinism.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env tsx
+/**
+ * Lint subagent determinism — the ADR-109 guarantees the schema mini-validator
+ * cannot express.
+ *
+ * `validate_frontmatter` (the schema gate) covers type / enum / required /
+ * pattern, but its mini-validator ignores JSON-Schema `const` and `uniqueItems`.
+ * This lint closes that gap for `src/subagents/*.md`:
+ *
+ *   1. `schema_version` MUST equal `subagent-v1` (schema `const`).
+ *   2. `discovery.visible` MUST be exactly `false` — default-off (schema `const`).
+ *   3. `tools` MUST have no duplicate entries (schema `uniqueItems`).
+ *   4. `name` MUST match the filename stem (addressable-handle invariant).
+ *   5. `name` MUST be globally unique across the subagent category
+ *      (projection-path collision guard — two units would overwrite each other
+ *      in `.claude/agents/`).
+ *
+ * Exit codes: 0 clean, 1 any violation.
+ *
+ * See ADR-109 (§ 6 determinism) and `src/scripts/schemas/subagent.schema.json`.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { parse_frontmatter } from './validate_frontmatter.js';
+
+const QUIET = process.argv.includes('--quiet');
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+const SUBAGENT_DIR = path.join(REPO, 'src', 'subagents');
+
+function _listSubagents(dir: string): string[] {
+    if (!fs.existsSync(dir)) {
+        return [];
+    }
+    return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith('.md'))
+        .sort()
+        .map((f) => path.join(dir, f));
+}
+
+function main(dir: string = SUBAGENT_DIR): number {
+    const findings: string[] = [];
+    const namesSeen = new Map<string, string>();
+
+    for (const file of _listSubagents(dir)) {
+        const rel = path.relative(REPO, file);
+        const stem = path.basename(file, '.md');
+        const text = fs.readFileSync(file, 'utf-8');
+        const [data] = parse_frontmatter(text);
+        if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+            findings.push(`${rel}: no parseable frontmatter`);
+            continue;
+        }
+        const fm = data as Record<string, unknown>;
+
+        if (fm.schema_version !== 'subagent-v1') {
+            findings.push(`${rel}: schema_version must be 'subagent-v1' (got ${JSON.stringify(fm.schema_version)})`);
+        }
+
+        const discovery = fm.discovery;
+        const visible =
+            discovery !== null && typeof discovery === 'object' && !Array.isArray(discovery)
+                ? (discovery as Record<string, unknown>).visible
+                : undefined;
+        if (visible !== false) {
+            findings.push(`${rel}: discovery.visible must be exactly false (default-off; got ${JSON.stringify(visible)})`);
+        }
+
+        const tools = fm.tools;
+        if (Array.isArray(tools)) {
+            const seen = new Set<unknown>();
+            const dupes = new Set<unknown>();
+            for (const t of tools) {
+                if (seen.has(t)) {
+                    dupes.add(t);
+                }
+                seen.add(t);
+            }
+            if (dupes.size > 0) {
+                findings.push(`${rel}: tools has duplicate entr(y/ies): ${[...dupes].map((d) => JSON.stringify(d)).join(', ')}`);
+            }
+        }
+
+        const name = fm.name;
+        if (typeof name !== 'string' || name !== stem) {
+            findings.push(`${rel}: name must match the filename stem '${stem}' (got ${JSON.stringify(name)})`);
+        } else {
+            const prior = namesSeen.get(name);
+            if (prior !== undefined) {
+                findings.push(`${rel}: duplicate subagent name '${name}' (also in ${prior}) — projection-path collision`);
+            } else {
+                namesSeen.set(name, rel);
+            }
+        }
+    }
+
+    if (findings.length > 0) {
+        process.stdout.write('❌ subagent determinism:\n');
+        for (const f of findings.sort()) {
+            process.stdout.write(`  - ${f}\n`);
+        }
+        return 1;
+    }
+
+    if (!QUIET) {
+        process.stdout.write(
+            `✅  subagent determinism: ${namesSeen.size} subagent(s) clean.\n`,
+        );
+    }
+    return 0;
+}
+
+const _isCliEntry =
+    process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry) {
+    process.exit(main());
+}
+
+export { main };

package/src/scripts/measure_augment_budget.ts

@@ -16,8 +16,10 @@
  * 2. `always`-type rules under `.augment/rules/` — full body injected.
  * 3. `auto`-type rules — only a registry stub is injected per rule.
  *
- * The 49,512-char ceiling is the empirical limit observed against the
- * Augment Code workspace prompt (2026-05-08 baseline).
+ * The cap comes from `src/config/budgets.yml`
+ * (augment_workspace_guidelines) — the single source of truth for the
+ * budget gates. The internal cap is deliberately below the verified
+ * platform maximum recorded there.
  *
  * Exit codes: 0 = under fail threshold, 1 = at/above fail threshold,
  * 3 = internal error.
@@ -39,10 +41,48 @@ export const TREND_FILE = path.join(
     '.augment-budget-history.jsonl',
 );
 
-// Augment workspace-guidelines ceiling — empirical 2026-05-08.
-export const TOTAL_CAP = 49_512;
-export const WARN_THRESHOLD = 0.85;
-export const FAIL_THRESHOLD = 0.95;
+// Budget caps — loaded from src/config/budgets.yml (single source of truth).
+export const BUDGETS_FILE = path.join(REPO_ROOT, 'src', 'config', 'budgets.yml');
+
+interface BudgetConfig {
+    platform_max_chars: number;
+    total_cap_chars: number;
+    warn_threshold: number;
+    fail_threshold: number;
+}
+
+function _load_budget_config(): BudgetConfig {
+    // Tiny purpose-built reader (keys are flat scalars) — avoids a hard yaml
+    // dependency in a script that must run before `npm ci` in some flows.
+    const text = fs.readFileSync(BUDGETS_FILE, 'utf-8');
+    const section = text.split(/^augment_workspace_guidelines:\s*$/m)[1] ?? '';
+    const num = (key: string): number => {
+        const m = new RegExp(`^\\s+${key}:\\s*([0-9.]+)\\s*$`, 'm').exec(section);
+        if (!m) {
+            throw new Error(`budgets.yml: missing augment_workspace_guidelines.${key}`);
+        }
+        return Number(m[1]);
+    };
+    const cfg: BudgetConfig = {
+        platform_max_chars: num('platform_max_chars'),
+        total_cap_chars: num('total_cap_chars'),
+        warn_threshold: num('warn_threshold'),
+        fail_threshold: num('fail_threshold'),
+    };
+    if (cfg.total_cap_chars > cfg.platform_max_chars) {
+        throw new Error(
+            `budgets.yml: total_cap_chars (${cfg.total_cap_chars}) must never exceed ` +
+                `platform_max_chars (${cfg.platform_max_chars})`,
+        );
+    }
+    return cfg;
+}
+
+const _BUDGET = _load_budget_config();
+export const PLATFORM_MAX = _BUDGET.platform_max_chars;
+export const TOTAL_CAP = _BUDGET.total_cap_chars;
+export const WARN_THRESHOLD = _BUDGET.warn_threshold;
+export const FAIL_THRESHOLD = _BUDGET.fail_threshold;
 
 // Stub template Augment injects for `type: auto` rules.
 function STUB(desc: string, p: string): string {

package/src/scripts/measure_patterns.ts

@@ -21,8 +21,9 @@
  *   7. Runtime boundary disclaimer
  *   8. Anti-sycophancy rules in "Do NOT"
  *
- * NOTE: the .py reads from the legacy `.agent-src.uncondensed/skills`
- * literal; this faithful twin replicates it byte-for-byte.
+ * NOTE: scans `src/skills` — the canonical source-of-truth skill library.
+ * (The pre-py2ts .py read the now-removed legacy condensed-source skills
+ * corpus; repointed here so the scanner runs on the live tree.)
  */
 
 import * as fs from 'node:fs';
@@ -32,7 +33,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/measure_patterns.ts → parents[2] is the repo root.
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
-const SKILLS_DIR = path.join(ROOT, '.agent-src.uncondensed', 'skills');
+const SKILLS_DIR = path.join(ROOT, 'src', 'skills');
 
 type Tier = number | string;
 

package/src/scripts/measure_skill_reduction.ts

@@ -20,11 +20,11 @@
  *     measure_skill_reduction
  *     measure_skill_reduction --json
  *
- * NOTE: the .py references the legacy `.agent-src.uncondensed/skills`
- * literal; this faithful twin replicates it byte-for-byte. When the
- * directory is absent the .py raises an uncaught FileNotFoundError
- * (iterdir on a missing dir) → exit 1, empty stdout; this twin mirrors
- * that by throwing, so the dispatcher / Node surfaces a non-zero exit.
+ * NOTE: scans `src/skills` — the canonical source-of-truth skill library.
+ * (The pre-py2ts .py read the now-removed legacy condensed-source skills
+ * corpus; repointed here so the scanner runs on the live tree.) When
+ * the directory is absent the scanner throws (iterdir on a missing dir) →
+ * non-zero exit, empty stdout.
  */
 
 import * as fs from 'node:fs';
@@ -35,7 +35,7 @@ import { parse as parseYaml } from 'yaml';
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/measure_skill_reduction.ts → parents[2] is the repo root.
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
-const SKILLS_DIR = path.join(REPO_ROOT, '.agent-src.uncondensed', 'skills');
+const SKILLS_DIR = path.join(REPO_ROOT, 'src', 'skills');
 const TARGET_REDUCTION = 0.4;
 const PHASE_3_USER_TYPES = ['consultant', 'creator'] as const;
 

package/src/scripts/migration_status.ts

@@ -2,7 +2,7 @@
 /**
  * migration_status.ts — Python→TypeScript migration dashboard.
  *
- * Phase 1 Step 13 of `agents/roadmaps/road-to-typescript-only-scripts.md`.
+ * Phase 1 Step 13 of `agents/roadmaps/archive/road-to-typescript-only-scripts.md`.
  *
  * Counts the remaining tracked `.py` files (via `git ls-files '*.py'`),
  * buckets them into the roadmap's migration categories, compares each
@@ -100,6 +100,10 @@ const EXCLUDED_PREFIXES: readonly string[] = [
     '.claude/',
     '.augment/',
     'internal/bench/',
+    // Eval fixtures simulate CONSUMER project files (a python DB model the
+    // structure-grounding eval reads as foreign source) — carve-out, not
+    // package source. Same class as the internal/bench/ trap fixtures.
+    'internal/evals/',
     'tmp/',
     '.tmp/',
 ];
@@ -225,7 +229,7 @@ function renderDashboard(
     lines.push('');
     lines.push(
         'Tracks remaining tracked `.py` files per roadmap phase of ' +
-            '`agents/roadmaps/road-to-typescript-only-scripts.md`. ' +
+            '`agents/roadmaps/archive/road-to-typescript-only-scripts.md`. ' +
             'Baseline = Phase 1 snapshot (hardcoded in the script).',
     );
     lines.push('');

package/src/scripts/mine_missing_guardrails.ts

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * A4 — Ablation-mining (learning-loop #1). Correlate rule *absence* with failure
+ * across INDEPENDENT runs (distinct `work_id`) and surface *missing-guardrail*
+ * candidates for the human to promote via `learning-to-rule-or-skill`.
+ *
+ * Read-only over `audit-log-v1` (`agents/runtime/state/audit/*.jsonl`). Raw
+ * counts only — NO auto-promotion, NO mutation. Correlation, not causation:
+ * every candidate carries the confounding caveat. A candidate is a *question*
+ * for a human, never an answer.
+ *
+ * Signal (per phase P, rule R):
+ *   - `success_with_rule`     = success lines in P where R ∈ rules_applied
+ *   - `failure_without_rule`  = blocked/error lines in P where R ∉ rules_applied
+ *   R is a candidate when its absence co-occurs with failure often enough
+ *   (`failure_without_rule` ≥ --min-count, over ≥2 distinct failing work_ids)
+ *   AND R is otherwise a success-associated rule in P (`success_with_rule` ≥ 1).
+ *
+ * Exit 0 always (an empty audit log is a valid state, not an error).
+ */
+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), '..', '..');
+export const DEFAULT_AUDIT_DIR = path.join(ROOT, 'agents', 'runtime', 'state', 'audit');
+export const SCHEMA_VERSION = 1;
+const FAILURE_OUTCOMES = new Set(['blocked', 'error']);
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Rec = Record<string, any>;
+
+/** Read audit-log-v1 phase records from `*.jsonl` (or one `<month>.jsonl`). */
+export function loadRecords(auditDir: string, month: string | null = null): Rec[] {
+    const out: Rec[] = [];
+    let files: string[];
+    if (month) {
+        files = [path.join(auditDir, `${month}.jsonl`)];
+    } else {
+        let names: string[] = [];
+        try {
+            names = fs.readdirSync(auditDir);
+        } catch {
+            return out;
+        }
+        files = names.filter((n) => n.endsWith('.jsonl')).sort().map((n) => path.join(auditDir, n));
+    }
+    for (const p of files) {
+        let text: string;
+        try {
+            text = fs.readFileSync(p, 'utf-8');
+        } catch {
+            continue;
+        }
+        for (const raw of text.split('\n')) {
+            const line = raw.trim();
+            if (!line) continue;
+            let rec: Rec;
+            try {
+                rec = JSON.parse(line) as Rec;
+            } catch {
+                continue;
+            }
+            if (rec.schema_version !== SCHEMA_VERSION) continue;
+            if (rec.type === 'supersede' || rec.type === 'note') continue;
+            if (typeof rec.phase !== 'string' || typeof rec.outcome !== 'string') continue;
+            if (!Array.isArray(rec.rules_applied)) continue;
+            out.push(rec);
+        }
+    }
+    return out;
+}
+
+export interface Candidate {
+    phase: string;
+    rule: string;
+    success_with_rule: number;
+    failure_without_rule: number;
+    failure_work_ids: string[];
+    success_without_rule: number;
+    failure_with_rule: number;
+}
+
+export function mineCandidates(records: Rec[], minCount: number): Candidate[] {
+    const phases = new Set<string>();
+    const rules = new Set<string>();
+    for (const r of records) {
+        phases.add(r.phase as string);
+        for (const rule of r.rules_applied as string[]) rules.add(rule);
+    }
+    const out: Candidate[] = [];
+    for (const phase of [...phases].sort()) {
+        const inPhase = records.filter((r) => r.phase === phase);
+        for (const rule of [...rules].sort()) {
+            let succWith = 0;
+            let succWithout = 0;
+            let failWith = 0;
+            const failWithoutIds = new Set<string>();
+            for (const r of inPhase) {
+                const has = (r.rules_applied as string[]).includes(rule);
+                const isSuccess = r.outcome === 'success';
+                const isFailure = FAILURE_OUTCOMES.has(r.outcome as string);
+                if (isSuccess && has) succWith += 1;
+                else if (isSuccess && !has) succWithout += 1;
+                else if (isFailure && has) failWith += 1;
+                else if (isFailure && !has) {
+                    failWithoutIds.add(typeof r.work_id === 'string' ? r.work_id : (r.id as string));
+                }
+            }
+            const failWithout = failWithoutIds.size;
+            // Candidate: absence co-occurs with failure across ≥2 distinct runs,
+            // and the rule is otherwise success-associated in this phase.
+            if (failWithout >= minCount && failWithout >= 2 && succWith >= 1) {
+                out.push({
+                    phase,
+                    rule,
+                    success_with_rule: succWith,
+                    failure_without_rule: failWithout,
+                    failure_work_ids: [...failWithoutIds].sort(),
+                    success_without_rule: succWithout,
+                    failure_with_rule: failWith,
+                });
+            }
+        }
+    }
+    // Strongest signal first: most distinct failing runs, then most successes-with.
+    out.sort(
+        (a, b) =>
+            b.failure_without_rule - a.failure_without_rule ||
+            b.success_with_rule - a.success_with_rule ||
+            (a.phase < b.phase ? -1 : a.phase > b.phase ? 1 : a.rule < b.rule ? -1 : 1),
+    );
+    return out;
+}
+
+const CONFOUND_NOTE =
+    'Correlation, NOT causation. A rule absent from failing runs may reflect the ' +
+    'task type or phase shape, not a missing guardrail. Low N inflates noise. ' +
+    'Each candidate is a question for a human — promote (or reject) only via ' +
+    'learning-to-rule-or-skill. Never auto-add a rule from this output.';
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    let auditDir = DEFAULT_AUDIT_DIR;
+    let month: string | null = null;
+    let minCount = 2;
+    let asJson = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--audit-dir') auditDir = argv[++i] ?? auditDir;
+        else if (a === '--month') month = argv[++i] ?? null;
+        else if (a === '--min-count') minCount = parseInt(argv[++i] ?? '2', 10) || 2;
+        else if (a === '--json') asJson = true;
+    }
+    const records = loadRecords(auditDir, month);
+    const candidates = mineCandidates(records, minCount);
+    if (asJson) {
+        process.stdout.write(
+            JSON.stringify(
+                { schema_version: SCHEMA_VERSION, records: records.length, min_count: minCount, confounding: CONFOUND_NOTE, candidates },
+                null,
+                2,
+            ) + '\n',
+        );
+        return 0;
+    }
+    if (records.length === 0) {
+        process.stdout.write('missing-guardrails: no audit-log-v1 records found (nothing to mine).\n');
+        return 0;
+    }
+    if (candidates.length === 0) {
+        process.stdout.write(`missing-guardrails: ${records.length} record(s), 0 candidates (min-count ${minCount}).\n`);
+        return 0;
+    }
+    process.stdout.write(`missing-guardrails: ${candidates.length} candidate(s) from ${records.length} record(s):\n\n`);
+    for (const c of candidates) {
+        process.stdout.write(
+            `  [${c.phase}] rule '${c.rule}' — absent in ${c.failure_without_rule} failing run(s), ` +
+                `present in ${c.success_with_rule} success(es). ` +
+                `(fail-with-rule ${c.failure_with_rule}, success-without ${c.success_without_rule})\n`,
+        );
+    }
+    process.stdout.write(`\n⚠️  ${CONFOUND_NOTE}\n`);
+    return 0;
+}
+
+const _isCli =
+    process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCli) process.exit(main());

package/src/scripts/parity/phase_gate.ts

@@ -2,7 +2,7 @@
 /**
  * phase_gate.ts — Python→TypeScript migration phase gate.
  *
- * Phase 1 Step 10 of `agents/roadmaps/road-to-typescript-only-scripts.md`.
+ * Phase 1 Step 10 of `agents/roadmaps/archive/road-to-typescript-only-scripts.md`.
  *
  * Reads `src/scripts/parity/phase-manifest.json` and enforces:
  *

package/src/scripts/parity/replay.ts

@@ -196,6 +196,27 @@ export function runReplay(options: ReplayOptions): ReplayReport {
     const tsScript = `${scriptBase}.ts`;
     const tsxCommand = resolveTsxCommand(cwd);
 
+    // Local python-skip guard (teardown D2): the replay harness is migration
+    // tooling — it byte-compares a live `python3 <script>.py` run against the
+    // tsx twin, which requires BOTH the runtime and the original `.py` to
+    // exist. Post-teardown neither holds; fail fast with a clear message
+    // instead of a spawn error, so the python-free-env shim retirement does
+    // not depend on porting this harness to a frozen-golden design.
+    if (spawnSync("python3", ["--version"], { encoding: "utf8" }).status !== 0) {
+        return {
+            script: options.script,
+            status: "fail",
+            cases: options.caseDirs.map((caseDir) => ({
+                caseDir,
+                diffs: [],
+                error:
+                    "python3 unavailable — the golden-replay harness needs the pre-teardown " +
+                    "python runtime plus the original .py; freeze the baseline to a TS golden " +
+                    "instead (teardown D2 medium-term).",
+            })),
+        };
+    }
+
     const cases: CaseResult[] = [];
     for (const caseDirRaw of options.caseDirs) {
         const caseDir = path.resolve(cwd, caseDirRaw);