@deftai/directive 0.55.0

package/dist/session-parity.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+/**
+ * Golden-output parity harness (#1787 s1): runs BOTH the Python oracle
+ * (`scripts/verify_session_ritual.py`) and the ported TS session core over
+ * shared fixtures (cache-off) and diffs JSON stdout + exit codes.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { emitVerifyJson, newRitualStatePayload, ritualStep, verifySessionRitual, writeRitualState, } from "@deftai/directive-core/session";
+const FIXED_NOW = "2026-06-09T01:00:00Z";
+function initGitRepo(policy = { sessionRitualStalenessHours: 4 }) {
+    const root = mkdtempSync(join(tmpdir(), "deft-session-parity-"));
+    writeFileSync(join(root, "README.md"), "fixture\n", "utf8");
+    mkdirSync(join(root, "vbrief"), { recursive: true });
+    writeFileSync(join(root, "vbrief", "PROJECT-DEFINITION.vbrief.json"), JSON.stringify({
+        vBRIEFInfo: { version: "0.6" },
+        plan: { title: "T", status: "running", items: [], policy },
+    }), "utf8");
+    execFileSync("git", ["init", "-q"], { cwd: root, encoding: "utf8" });
+    execFileSync("git", ["config", "user.email", "parity@test.local"], {
+        cwd: root,
+        encoding: "utf8",
+    });
+    execFileSync("git", ["config", "user.name", "deft-parity"], { cwd: root, encoding: "utf8" });
+    execFileSync("git", ["add", "-A"], { cwd: root, encoding: "utf8" });
+    execFileSync("git", ["commit", "-q", "-m", "init"], {
+        cwd: root,
+        encoding: "utf8",
+        env: {
+            ...process.env,
+            GIT_AUTHOR_NAME: "deft-parity",
+            GIT_AUTHOR_EMAIL: "parity@test.local",
+            GIT_COMMITTER_NAME: "deft-parity",
+            GIT_COMMITTER_EMAIL: "parity@test.local",
+        },
+    });
+    const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" }).trim();
+    return { root, head };
+}
+function fakeGitRunner(head, worktree) {
+    return (_root, args) => {
+        if (args[0] === "rev-parse" && args[1] === "--verify" && args[2] === "HEAD") {
+            return { code: 0, stdout: head, stderr: "" };
+        }
+        if (args[0] === "rev-parse" && args[1] === "--show-toplevel") {
+            return { code: 0, stdout: worktree, stderr: "" };
+        }
+        return { code: 0, stdout: "", stderr: "" };
+    };
+}
+function writeFreshState(fixture, startedAt, gated = {}) {
+    const now = new Date(startedAt);
+    writeRitualState(fixture.root, newRitualStatePayload({
+        sessionId: "parity-session",
+        gitHead: fixture.head,
+        worktreePath: resolve(fixture.root),
+        startedAt: now,
+        quickSteps: {
+            alignment: ritualStep({ ok: true, ts: now }),
+            branch_policy: ritualStep({ ok: true, ts: now }),
+            triage_welcome: ritualStep({ ok: true, ts: now }),
+        },
+        gatedSteps: gated,
+    }));
+}
+function loadPyModule(_deftRoot, name, rel) {
+    return `spec = importlib.util.spec_from_file_location(${JSON.stringify(name)}, root / ${JSON.stringify(rel)})
+mod = importlib.util.module_from_spec(spec)
+sys.modules[${JSON.stringify(name)}] = mod
+spec.loader.exec_module(mod)`;
+}
+function runPythonVerify(deftRoot, fixture, scenario) {
+    const runnerSnippet = scenario.runner
+        ? `def runner(args, cwd):
+    return (0, "OK", "")`
+        : "";
+    const script = `import importlib.util, json, sys
+from datetime import datetime, UTC
+from pathlib import Path
+root = Path(${JSON.stringify(deftRoot)})
+fixture = Path(${JSON.stringify(fixture.root)})
+${loadPyModule(deftRoot, "verify_session_ritual", "scripts/verify_session_ritual.py")}
+${runnerSnippet}
+now = datetime.fromisoformat(${JSON.stringify(scenario.nowIso.replace("Z", "+00:00"))})
+kwargs = dict(tier=${JSON.stringify(scenario.tier)}, now=now, bypass=${scenario.bypass ? "True" : "False"})
+${scenario.runner ? "kwargs['runner'] = runner" : ""}
+result = mod.verify(fixture, **kwargs)
+print(json.dumps({"ready": result.code == 0, "exit_code": result.code, "tier": result.tier, "message": result.message, "state_path": str(result.state_path), "bypassed": result.bypassed, "would_fail_code": result.would_fail_code}, sort_keys=True))
+sys.exit(result.code)`;
+    const result = spawnSync("uv", ["run", "python", "-c", script], {
+        cwd: deftRoot,
+        encoding: "utf8",
+        env: { ...process.env, DEFT_CACHE_DISABLE: "1", PYTHONUTF8: "1" },
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+        exitCode: result.status ?? 2,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr: typeof result.stderr === "string" ? result.stderr : "",
+    };
+}
+function runTsVerify(fixture, scenario) {
+    const result = verifySessionRitual(fixture.root, {
+        tier: scenario.tier,
+        now: new Date(scenario.nowIso),
+        bypass: scenario.bypass,
+        runGit: fakeGitRunner(fixture.head, resolve(fixture.root)),
+        runner: scenario.runner,
+    });
+    return {
+        exitCode: result.code,
+        stdout: `${emitVerifyJson(result)}\n`,
+        stderr: "",
+    };
+}
+const mockGatedRunner = () => () => ({
+    code: 0,
+    stdout: "OK",
+    stderr: "",
+});
+export const PARITY_CASES = [
+    {
+        name: "quick-tier",
+        setup() {
+            const fixture = initGitRepo();
+            writeFreshState(fixture, FIXED_NOW);
+            return fixture;
+        },
+        tier: "quick",
+        bypass: false,
+        nowIso: FIXED_NOW,
+    },
+    {
+        name: "gated-tier",
+        setup() {
+            const fixture = initGitRepo();
+            writeFreshState(fixture, FIXED_NOW);
+            return fixture;
+        },
+        tier: "gated",
+        bypass: false,
+        nowIso: FIXED_NOW,
+        runner: mockGatedRunner(),
+    },
+    {
+        name: "stale-expiry",
+        setup() {
+            const fixture = initGitRepo({ sessionRitualStalenessHours: 1 });
+            writeFreshState(fixture, "2026-06-08T00:00:00Z");
+            return fixture;
+        },
+        tier: "quick",
+        bypass: false,
+        nowIso: FIXED_NOW,
+    },
+    {
+        name: "defer",
+        setup() {
+            const fixture = initGitRepo();
+            const now = new Date(FIXED_NOW);
+            writeRitualState(fixture.root, newRitualStatePayload({
+                sessionId: "parity-session",
+                gitHead: fixture.head,
+                worktreePath: resolve(fixture.root),
+                startedAt: now,
+                quickSteps: {
+                    alignment: ritualStep({ ok: true, ts: now }),
+                    branch_policy: ritualStep({ ok: true, ts: now }),
+                    triage_welcome: ritualStep({ ok: true, ts: now }),
+                },
+                gatedSteps: {
+                    doctor: ritualStep({ ok: true, ts: now, deferredReason: "operator deferred" }),
+                    cache_fresh: ritualStep({ ok: true, ts: now, deferredReason: "operator deferred" }),
+                },
+            }));
+            return fixture;
+        },
+        tier: "gated",
+        bypass: false,
+        nowIso: FIXED_NOW,
+    },
+    {
+        name: "skip",
+        setup() {
+            return initGitRepo();
+        },
+        tier: "quick",
+        bypass: true,
+        nowIso: FIXED_NOW,
+    },
+];
+function resolveDeftRoot() {
+    if (process.env.DEFT_ROOT !== undefined && process.env.DEFT_ROOT.length > 0) {
+        return resolve(process.env.DEFT_ROOT);
+    }
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+}
+export function runParity() {
+    const deftRoot = resolveDeftRoot();
+    const diffs = [];
+    for (const scenario of PARITY_CASES) {
+        const fixture = scenario.setup();
+        try {
+            const py = runPythonVerify(deftRoot, fixture, scenario);
+            const ts = runTsVerify(fixture, scenario);
+            diffs.push({
+                name: scenario.name,
+                exitMismatch: py.exitCode !== ts.exitCode,
+                stdoutMismatch: py.stdout !== ts.stdout,
+                pythonExit: py.exitCode,
+                tsExit: ts.exitCode,
+                pythonStdout: py.stdout,
+                tsStdout: ts.stdout,
+            });
+        }
+        finally {
+            rmSync(fixture.root, { recursive: true, force: true });
+        }
+    }
+    const ok = diffs.every((d) => !d.exitMismatch && !d.stdoutMismatch);
+    return { ok, diffs };
+}
+export function renderReport(result) {
+    if (result.ok) {
+        return `session parity: CLEAN -- Python and TS agree on ${result.diffs.length} case(s).`;
+    }
+    const lines = ["session parity: DIVERGENCE"];
+    for (const d of result.diffs) {
+        if (d.exitMismatch || d.stdoutMismatch) {
+            lines.push(`  case: ${d.name}`);
+            if (d.exitMismatch) {
+                lines.push(`    exit mismatch: python=${d.pythonExit} ts=${d.tsExit}`);
+            }
+            if (d.stdoutMismatch) {
+                lines.push(`    python stdout: ${JSON.stringify(d.pythonStdout)}`);
+                lines.push(`    ts stdout: ${JSON.stringify(d.tsStdout)}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    try {
+        const result = runParity();
+        if (result.ok) {
+            process.stdout.write(`${renderReport(result)}\n`);
+            process.exit(0);
+        }
+        process.stderr.write(`${renderReport(result)}\n`);
+        process.exit(1);
+    }
+    catch (err) {
+        process.stderr.write(`session parity: harness error -- ${String(err)}\n`);
+        process.exit(2);
+    }
+}
+//# sourceMappingURL=session-parity.js.map

package/dist/slice-parity.d.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+export interface CommandCapture {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface SliceFixtureOptions {
+    readonly seedRecords?: ReadonlyArray<Record<string, unknown>>;
+}
+export interface ParityCase {
+    readonly name: string;
+    readonly argv: string[];
+    readonly fixture?: SliceFixtureOptions;
+}
+export interface ParityDiff {
+    readonly caseName: string;
+    readonly exitMismatch: boolean;
+    readonly stdoutMismatch: boolean;
+    readonly stderrMismatch: boolean;
+    readonly pythonExit: number;
+    readonly tsExit: number;
+}
+export interface ParityResult {
+    readonly ok: boolean;
+    readonly diffs: ParityDiff[];
+}
+/** Strip volatile absolute paths, UUIDs, and timestamps before compare. */
+export declare function normalizeOutput(text: string): string;
+export declare function buildFixtureRepo(options?: SliceFixtureOptions): string;
+/** Diff one parity case between Python oracle and TS CLI. */
+export declare function diffCase(python: CommandCapture, ts: CommandCapture, caseName: string): ParityDiff;
+export declare const PARITY_CASES: readonly ParityCase[];
+/** Run all parity cases; returns aggregate result. */
+export declare function runParity(): ParityResult;
+export declare function renderReport(result: ParityResult): string;
+//# sourceMappingURL=slice-parity.d.ts.map

package/dist/slice-parity.js

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+/**
+ * Golden-output parity harness (#1727): runs BOTH the Python oracle
+ * (`scripts/slice_record_existing.py`) and the ported TS slice CLI with
+ * identical argv on throwaway fixtures, then diffs exit codes and
+ * normalised stdout/stderr (cache-off).
+ *
+ * Exit codes: 0 parity / 1 divergence / 2 harness setup error.
+ */
+import { spawnSync } from "node:child_process";
+import { appendFileSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+function sortKeysDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => sortKeysDeep(item));
+    }
+    if (value !== null && typeof value === "object") {
+        const obj = value;
+        const sorted = {};
+        for (const key of Object.keys(obj).sort()) {
+            sorted[key] = sortKeysDeep(obj[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+function seedJsonLine(record) {
+    return JSON.stringify(sortKeysDeep(record)).replace(/("(?:[^"\\]|\\.)*")|([:,])/g, (_match, str, sep) => str !== undefined ? str : sep === ":" ? ": " : ", ");
+}
+/** Strip volatile absolute paths, UUIDs, and timestamps before compare. */
+export function normalizeOutput(text) {
+    return text
+        .replace(/--project-root [^\s]+/g, "--project-root <ROOT>")
+        .replace(/slice_id=[0-9a-fA-F-]{36}/g, "slice_id=<UUID>")
+        .replace(/slice_id=[0-9a-fA-F-]{36}/g, "slice_id=<UUID>")
+        .replace(/"slice_id": "[0-9a-fA-F-]{36}"/g, '"slice_id": "<UUID>"')
+        .replace(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z/g, "<ISO>");
+}
+function runCapture(cmd, args, cwd) {
+    const result = spawnSync(cmd, args, {
+        cwd,
+        encoding: "utf8",
+        env: process.env,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+        exitCode: result.status ?? 2,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr: typeof result.stderr === "string" ? result.stderr : "",
+    };
+}
+export function buildFixtureRepo(options = {}) {
+    const root = mkdtempSync(join(tmpdir(), "deft-slice-parity-"));
+    mkdirSync(join(root, "vbrief", ".eval"), { recursive: true });
+    mkdirSync(join(root, ".git"));
+    const logPath = join(root, "vbrief", ".eval", "slices.jsonl");
+    for (const record of options.seedRecords ?? []) {
+        appendFileSync(logPath, `${seedJsonLine(record)}\n`, "utf8");
+    }
+    return root;
+}
+function resolveDeftRoot() {
+    if (process.env.DEFT_ROOT !== undefined && process.env.DEFT_ROOT.length > 0) {
+        return resolve(process.env.DEFT_ROOT);
+    }
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+}
+function runPythonSlice(deftRoot, repo, argv) {
+    return runCapture("uv", [
+        "run",
+        "python",
+        join(deftRoot, "scripts", "slice_record_existing.py"),
+        ...argv,
+        "--project-root",
+        repo,
+    ], deftRoot);
+}
+function runTsSlice(deftRoot, repo, argv) {
+    return runCapture("node", [
+        join(deftRoot, "packages", "core", "dist", "slice", "cli.js"),
+        ...argv,
+        "--project-root",
+        repo,
+    ], deftRoot);
+}
+/** Diff one parity case between Python oracle and TS CLI. */
+export function diffCase(python, ts, caseName) {
+    const pyOut = normalizeOutput(python.stdout);
+    const tsOut = normalizeOutput(ts.stdout);
+    const pyErr = normalizeOutput(python.stderr);
+    const tsErr = normalizeOutput(ts.stderr);
+    return {
+        caseName,
+        exitMismatch: python.exitCode !== ts.exitCode,
+        stdoutMismatch: pyOut !== tsOut,
+        stderrMismatch: pyErr !== tsErr,
+        pythonExit: python.exitCode,
+        tsExit: ts.exitCode,
+    };
+}
+export const PARITY_CASES = [
+    { name: "list-empty", argv: ["list"] },
+    {
+        name: "list-seeded",
+        argv: ["list"],
+        fixture: {
+            seedRecords: [
+                {
+                    slice_id: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+                    umbrella: 10,
+                    umbrella_url: "https://github.com/owner/repo/issues/10",
+                    sliced_at: "2026-05-14T17:00:00Z",
+                    actor: "manual:operator",
+                    children: [
+                        { n: 11, url: "https://github.com/owner/repo/issues/11", wave: 1, role: "manual" },
+                    ],
+                    expected_close_signal: "all-children-merged",
+                },
+            ],
+        },
+    },
+    {
+        name: "list-json-seeded",
+        argv: ["list", "--json"],
+        fixture: {
+            seedRecords: [
+                {
+                    slice_id: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+                    umbrella: 10,
+                    umbrella_url: "https://github.com/owner/repo/issues/10",
+                    sliced_at: "2026-05-14T17:00:00Z",
+                    actor: "manual:operator",
+                    children: [
+                        { n: 11, url: "https://github.com/owner/repo/issues/11", wave: 1, role: "manual" },
+                    ],
+                    expected_close_signal: "all-children-merged",
+                },
+            ],
+        },
+    },
+    {
+        name: "record-existing-skip-validation",
+        argv: [
+            "record-existing",
+            "--umbrella=1",
+            "--children=2,3",
+            "--repo=owner/repo",
+            "--skip-validation",
+            "--sliced-at=2026-05-14T17:00:00Z",
+        ],
+    },
+    {
+        name: "record-existing-idempotent",
+        argv: [
+            "record-existing",
+            "--umbrella=1",
+            "--children=2,3",
+            "--repo=owner/repo",
+            "--skip-validation",
+            "--sliced-at=2026-05-14T17:00:00Z",
+        ],
+        fixture: {
+            seedRecords: [
+                {
+                    slice_id: "bbbbbbbb-bbbb-cccc-dddd-eeeeeeeeeeee",
+                    umbrella: 1,
+                    umbrella_url: "https://github.com/owner/repo/issues/1",
+                    sliced_at: "2026-05-14T17:00:00Z",
+                    actor: "manual:operator",
+                    children: [
+                        { n: 2, url: "https://github.com/owner/repo/issues/2", wave: 1, role: "manual" },
+                        { n: 3, url: "https://github.com/owner/repo/issues/3", wave: 1, role: "manual" },
+                    ],
+                    expected_close_signal: "all-children-merged",
+                },
+            ],
+        },
+    },
+    {
+        name: "record-existing-dry-run",
+        argv: [
+            "record-existing",
+            "--umbrella=42",
+            "--children=100,101",
+            "--repo=owner/repo",
+            "--dry-run",
+            "--skip-validation",
+            "--sliced-at=2026-05-14T17:00:00Z",
+        ],
+    },
+    {
+        name: "duplicate-child",
+        argv: [
+            "record-existing",
+            "--umbrella=1",
+            "--children=2,2",
+            "--repo=owner/repo",
+            "--skip-validation",
+        ],
+    },
+    {
+        name: "umbrella-in-children",
+        argv: [
+            "record-existing",
+            "--umbrella=1",
+            "--children=1,2",
+            "--repo=owner/repo",
+            "--skip-validation",
+        ],
+    },
+    {
+        name: "wave-member-not-in-children",
+        argv: [
+            "record-existing",
+            "--umbrella=1",
+            "--children=2,3",
+            "--wave-2=999",
+            "--repo=owner/repo",
+            "--skip-validation",
+        ],
+    },
+    {
+        name: "cross-wave-collision",
+        argv: [
+            "record-existing",
+            "--umbrella=1",
+            "--children=2,3",
+            "--wave-1=2",
+            "--wave-2=2",
+            "--repo=owner/repo",
+            "--skip-validation",
+        ],
+    },
+    {
+        name: "default-subcommand",
+        argv: [
+            "--umbrella=1",
+            "--children=2",
+            "--repo=owner/repo",
+            "--skip-validation",
+            "--sliced-at=2026-05-14T17:00:00Z",
+        ],
+    },
+    {
+        name: "missing-project-root",
+        argv: ["list", "--project-root", "/no/such/deft-project-root-xyz"],
+    },
+];
+/** Run all parity cases; returns aggregate result. */
+export function runParity() {
+    const deftRoot = resolveDeftRoot();
+    const diffs = [];
+    for (const testCase of PARITY_CASES) {
+        const pyRepo = buildFixtureRepo(testCase.fixture);
+        const tsRepo = buildFixtureRepo(testCase.fixture);
+        try {
+            const python = runPythonSlice(deftRoot, pyRepo, testCase.argv);
+            const ts = runTsSlice(deftRoot, tsRepo, testCase.argv);
+            diffs.push(diffCase(python, ts, testCase.name));
+        }
+        finally {
+            rmSync(pyRepo, { recursive: true, force: true });
+            rmSync(tsRepo, { recursive: true, force: true });
+        }
+    }
+    const ok = diffs.every((d) => !d.exitMismatch && !d.stdoutMismatch && !d.stderrMismatch);
+    return { ok, diffs };
+}
+export function renderReport(result) {
+    if (result.ok) {
+        return `slice parity: CLEAN -- Python and TS agree on ${PARITY_CASES.length} case(s).`;
+    }
+    const lines = ["slice parity: DIVERGENCE"];
+    for (const d of result.diffs) {
+        if (d.exitMismatch || d.stdoutMismatch || d.stderrMismatch) {
+            lines.push(`  case: ${d.caseName}`);
+            if (d.exitMismatch)
+                lines.push(`    exit: python=${d.pythonExit} ts=${d.tsExit}`);
+            if (d.stdoutMismatch)
+                lines.push("    stdout mismatch");
+            if (d.stderrMismatch)
+                lines.push("    stderr mismatch");
+        }
+    }
+    return lines.join("\n");
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    try {
+        const result = runParity();
+        if (result.ok) {
+            process.stdout.write(`${renderReport(result)}\n`);
+            process.exit(0);
+        }
+        process.stderr.write(`${renderReport(result)}\n`);
+        process.exit(1);
+    }
+    catch (err) {
+        process.stderr.write(`slice parity: harness error -- ${String(err)}\n`);
+        process.exit(2);
+    }
+}
+//# sourceMappingURL=slice-parity.js.map

package/dist/slice.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+/** Run slice verbs with argv; returns process exit code. */
+export declare function run(argv: string[]): number;
+//# sourceMappingURL=slice.d.ts.map

package/dist/slice.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * Thin CLI entry for slice:record-existing / slice:list (#1727).
+ * Delegates to the core implementation at packages/core/dist/slice/cli.js.
+ */
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+function coreCliPath() {
+    return join(dirname(fileURLToPath(import.meta.url)), "../../core/dist/slice/cli.js");
+}
+/** Run slice verbs with argv; returns process exit code. */
+export function run(argv) {
+    const result = spawnSync(process.execPath, [coreCliPath(), ...argv], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (typeof result.stdout === "string" && result.stdout.length > 0) {
+        process.stdout.write(result.stdout);
+    }
+    if (typeof result.stderr === "string" && result.stderr.length > 0) {
+        process.stderr.write(result.stderr);
+    }
+    return result.status ?? 2;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=slice.js.map

package/dist/story-ready-parity.d.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+export interface ScenarioResult {
+    readonly name: string;
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface ParityScenario {
+    readonly name: string;
+    readonly vbriefRel: string;
+    readonly vbriefStatus?: string;
+    readonly envelopeRel: string | null;
+    readonly allowDirty?: boolean;
+    readonly dirty?: boolean;
+}
+export interface ParityResult {
+    readonly ok: boolean;
+    readonly scenarios: Array<{
+        readonly name: string;
+        readonly exitMismatch: boolean;
+        readonly pythonExit: number;
+        readonly tsExit: number;
+        readonly messageMismatch: boolean;
+        readonly pythonMessage: string;
+        readonly tsMessage: string;
+    }>;
+}
+/** Scenarios exercised by the parity harness (mirrors Python contract cases). */
+export declare const PARITY_SCENARIOS: readonly ParityScenario[];
+/** Normalise gate message for comparison (trim, collapse whitespace). */
+export declare function normaliseMessage(stdout: string, stderr: string, exitCode: number): string;
+/** Build a fixture repo for one scenario; return repo root + vbrief absolute path. */
+export declare function buildScenarioRepo(scenario: ParityScenario): {
+    root: string;
+    vbriefPath: string;
+    envelopePath: string | null;
+};
+/** Diff python vs TS gate outputs across all parity scenarios. */
+export declare function diffParity(python: ScenarioResult, ts: ScenarioResult): {
+    exitMismatch: boolean;
+    messageMismatch: boolean;
+    pythonMessage: string;
+    tsMessage: string;
+};
+/** Run all parity scenarios and return a structured result. */
+export declare function runParity(): ParityResult;
+/** Render a human-readable parity report (exported for unit tests). */
+export declare function renderReport(result: ParityResult): string;
+//# sourceMappingURL=story-ready-parity.d.ts.map