opensquid 0.5.395

package/dist/hooks/versioning-gate.js

@@ -0,0 +1,245 @@
+/**
+ * Versioning gate — pre-commit check enforcing per-commit patch bumps
+ * (v0.6.3). Wired into the PreToolUse hook for `git commit` commands.
+ *
+ * Problem this fixes: I keep batching multiple fixes into one commit
+ * and bumping the minor (or no bump at all) instead of one patch per
+ * fix. The discipline rule was memorized (`mem-d2cc0e78`) but rules
+ * I can ignore aren't structural protection. This gate makes the
+ * discipline mechanical — if your commit touches source code AND
+ * doesn't include a manifest version bump in the same commit, it
+ * gets rejected before `git commit` runs.
+ *
+ * Detection:
+ *   1. `git diff --cached --name-only` → list of staged files
+ *   2. If no `src/**` files staged → allow (docs/CI/config commits
+ *      don't need version bumps)
+ *   3. If `src/**` files staged → require a manifest (Cargo.toml or
+ *      package.json) to also be staged with a `version` line diff
+ *   4. Otherwise → block with actionable message
+ *
+ * Fail-open invariant: any error running git or parsing output →
+ * allow with a stderr warning (per the honesty-ledger + workflow-gate
+ * precedent — never block on opensquid's own bug).
+ *
+ * Emergency override: `OPENSQUID_SKIP_VERSION_GATE=1` bypasses with a
+ * loud stderr warning. For genuine emergencies (revert commits,
+ * generated-code-only diffs, etc.) where the discipline doesn't
+ * apply.
+ */
+import { exec as execCb } from "node:child_process";
+import { promisify } from "node:util";
+const exec = promisify(execCb);
+export async function evaluateVersioningGate(input = {}) {
+    if (checkOverrideEnv()) {
+        return {
+            block: false,
+            stderr: "🦑 [opensquid versioning-gate] BYPASSED via OPENSQUID_SKIP_VERSION_GATE=1\n",
+        };
+    }
+    const cwd = input.cwd ?? process.cwd();
+    // List staged files. `--no-renames` keeps the output simple (renames
+    // appear as both old + new path rather than `R100\told\tnew`).
+    let stagedFiles;
+    try {
+        const { stdout } = await exec("git diff --cached --name-only --no-renames", {
+            cwd,
+            maxBuffer: 1024 * 1024,
+        });
+        stagedFiles = stdout
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean);
+    }
+    catch (err) {
+        return {
+            block: false,
+            stderr: `[opensquid versioning-gate] git diff failed (proceeding): ${err instanceof Error ? err.message : err}\n`,
+        };
+    }
+    if (stagedFiles.length === 0) {
+        // Nothing staged — git commit will fail on its own with no need
+        // for this gate to intervene.
+        return { block: false, stderr: "" };
+    }
+    const sourceFiles = stagedFiles.filter(isSourceFile);
+    if (sourceFiles.length === 0) {
+        // Docs / CI / config / fixtures / etc. — no source change, no bump needed.
+        return { block: false, stderr: "" };
+    }
+    const manifests = stagedFiles.filter(isManifestFile);
+    if (manifests.length === 0) {
+        return {
+            block: true,
+            stderr: buildBlockMessage(sourceFiles, []),
+        };
+    }
+    // At least one manifest is staged — check that at least one has a
+    // version-line diff (just touching the manifest without bumping
+    // version doesn't count).
+    let bumpedManifest = null;
+    for (const m of manifests) {
+        const jump = await readManifestVersionBump(cwd, m);
+        if (jump) {
+            bumpedManifest = { path: m, jump };
+            break;
+        }
+    }
+    if (!bumpedManifest) {
+        return {
+            block: true,
+            stderr: buildBlockMessage(sourceFiles, manifests),
+        };
+    }
+    // 0.7.23 / D5 — catch-up bump detection. The PATCH-ONLY rule
+    // ([[feedback_pre1_versioning]] v4) says every src commit = exactly
+    // one patch bump. A jump like 0.7.10 → 0.7.14 in a single commit
+    // means previous src commits skipped their bumps. Don't BLOCK
+    // (legitimate explicit catch-ups exist), but surface a loud warning
+    // so the skip is visible.
+    const { jump } = bumpedManifest;
+    if (jump && isMultiPatchJump(jump)) {
+        return {
+            block: false,
+            stderr: `🦑 [opensquid versioning-gate] WARN: catch-up bump detected (${jump.from} → ${jump.to})\n` +
+                `  PATCH-ONLY rule says one patch per commit. A multi-patch jump in one\n` +
+                `  commit usually means earlier src commits shipped without bumps. Drift D5.\n`,
+        };
+    }
+    return { block: false, stderr: "" };
+}
+/**
+ * Is this a source file that should trigger version-bump enforcement?
+ * Generous definition: anything under `src/` for any language we support.
+ */
+export function isSourceFile(p) {
+    // src/ at any depth (top-level or nested workspace member)
+    return /(^|\/)src\//.test(p);
+}
+/** Is this the repo's version manifest? */
+export function isManifestFile(p) {
+    const base = p.split("/").pop() ?? "";
+    return base === "Cargo.toml" || base === "package.json";
+}
+/**
+ * Look at the staged diff of a manifest and return the version jump
+ * (from → to). Returns null when the diff doesn't touch a `version`
+ * line at all.
+ *
+ * Exported for direct testing.
+ */
+export async function readManifestVersionBump(cwd, manifestPath) {
+    let diff;
+    try {
+        const { stdout } = await exec(`git diff --cached --no-color -U0 -- ${quoteShell(manifestPath)}`, { cwd, maxBuffer: 1024 * 1024 });
+        diff = stdout;
+    }
+    catch {
+        return null;
+    }
+    return parseVersionJumpFromDiff(diff);
+}
+/**
+ * Parse `+`/`-` lines from a manifest diff and extract the version
+ * jump. Cargo: `version = "..."`. package.json: `"version": "..."`.
+ *
+ * Anchor discipline:
+ *   - Cargo (TOML, line-oriented) → anchor `^version` so we don't
+ *     match a dep with `version = "..."` in `[dependencies.foo]`.
+ *   - package.json (JSON, can be MINIFIED single-line) → do NOT
+ *     anchor; `"version"` can appear mid-line in minified JSON.
+ *
+ * Exported for direct testing.
+ */
+export function parseVersionJumpFromDiff(diff) {
+    let oldVersion = null;
+    let newVersion = null;
+    for (const line of diff.split("\n")) {
+        if (line.startsWith("+++") || line.startsWith("---"))
+            continue;
+        const sign = line[0];
+        if (sign !== "+" && sign !== "-")
+            continue;
+        const body = line.slice(1).trim();
+        let v = null;
+        const cargoMatch = body.match(/^version\s*=\s*"([^"]+)"/);
+        if (cargoMatch)
+            v = cargoMatch[1];
+        if (v === null) {
+            const npmMatch = body.match(/"version"\s*:\s*"([^"]+)"/);
+            if (npmMatch)
+                v = npmMatch[1];
+        }
+        if (v === null)
+            continue;
+        if (sign === "+")
+            newVersion = v;
+        else
+            oldVersion = v;
+    }
+    if (!newVersion)
+        return null;
+    // New-version only (e.g. brand-new manifest with no prior `version`
+    // line) is still a valid "version bump" — treat oldVersion as empty.
+    return { from: oldVersion ?? "", to: newVersion };
+}
+/**
+ * Detect a multi-patch jump: same major.minor, but patch advances by
+ * more than 1 (catch-up bump).
+ *
+ * Returns false for:
+ *   - First-time bumps (from === "")
+ *   - Same-patch (no actual jump, shouldn't happen with proper diff)
+ *   - Minor/major bumps (those are user-authorized; PATCH-ONLY rule
+ *     forbids the agent from naming them but doesn't make them "drift")
+ *   - Non-SemVer version strings (best-effort parse)
+ *
+ * Exported for direct testing.
+ */
+export function isMultiPatchJump(jump) {
+    const oldParts = parseSemver(jump.from);
+    const newParts = parseSemver(jump.to);
+    if (!oldParts || !newParts)
+        return false;
+    // Only flag same-major.minor with patch jump > 1.
+    if (oldParts.major !== newParts.major)
+        return false;
+    if (oldParts.minor !== newParts.minor)
+        return false;
+    return newParts.patch > oldParts.patch + 1;
+}
+function parseSemver(v) {
+    const m = v.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!m)
+        return null;
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+function quoteShell(s) {
+    // Defensive single-quote shell escape. Manifest paths are usually
+    // boring but we don't trust them blindly.
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function buildBlockMessage(sourceFiles, manifests) {
+    const srcSample = sourceFiles.slice(0, 5).join(", ") + (sourceFiles.length > 5 ? ", ..." : "");
+    const lines = [
+        `🦑 [opensquid versioning-gate] commit blocked — source changes without a version bump`,
+        `  source files staged (${sourceFiles.length}): ${srcSample}`,
+    ];
+    if (manifests.length === 0) {
+        lines.push(`  No Cargo.toml or package.json staged.`, `  Bump the patch version (per mem-d2cc0e78 — fix per commit, not batched), \`git add\` the manifest, then re-commit.`);
+    }
+    else {
+        lines.push(`  Manifest(s) staged but no version-line diff: ${manifests.join(", ")}`, `  Bump the version field (Cargo.toml: \`version = "x.y.z"\`, package.json: \`"version": "x.y.z"\`), re-stage, then re-commit.`);
+    }
+    lines.push(`  Override (genuine emergency): set OPENSQUID_SKIP_VERSION_GATE=1 for this command.`);
+    return lines.join("\n") + "\n";
+}
+/**
+ * Emergency-override env var. Loud stderr warning on bypass so it
+ * always shows up in scrollback / CI logs. Exported for the test
+ * suite.
+ */
+export function checkOverrideEnv() {
+    return process.env.OPENSQUID_SKIP_VERSION_GATE === "1";
+}
+//# sourceMappingURL=versioning-gate.js.map

package/dist/hooks/versioning-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioning-gate.js","sourceRoot":"","sources":["../../src.legacy/hooks/versioning-gate.ts"],"names":[],"mappings":"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"}

package/dist/hooks/versioning-gate.test.js

@@ -0,0 +1,368 @@
+/**
+ * Versioning-gate tests — exercise against real git repos in tmpdirs.
+ * The gate's logic depends on actual `git diff --cached` output shape,
+ * so synthesized state wouldn't catch the same class of bug that
+ * v0.6.1 transcript-walker missed against real Claude Code shapes
+ * (per the v0.6.2 lesson). Each test inits a fresh tmp git repo,
+ * sets up the staged state we want, runs the gate, asserts.
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { execSync } from "node:child_process";
+import * as crypto from "node:crypto";
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { checkOverrideEnv, evaluateVersioningGate, isManifestFile, isMultiPatchJump, isSourceFile, parseVersionJumpFromDiff, } from "./versioning-gate.js";
+// ---------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------
+let repoDir;
+beforeEach(async () => {
+    repoDir = path.join(os.tmpdir(), `opensquid-ver-${crypto.randomUUID()}`);
+    await fs.mkdir(repoDir, { recursive: true });
+    // Minimal git init that doesn't depend on the user's global config.
+    execSync("git init -q", { cwd: repoDir });
+    execSync("git config user.email test@example.com", { cwd: repoDir });
+    execSync("git config user.name 'Test'", { cwd: repoDir });
+});
+afterEach(async () => {
+    await fs.rm(repoDir, { recursive: true, force: true });
+    delete process.env.OPENSQUID_SKIP_VERSION_GATE;
+});
+async function writeFile(rel, content) {
+    const full = path.join(repoDir, rel);
+    await fs.mkdir(path.dirname(full), { recursive: true });
+    await fs.writeFile(full, content, "utf8");
+}
+function stage(rel) {
+    execSync(`git add ${rel}`, { cwd: repoDir });
+}
+function commit(message) {
+    execSync(`git commit -q -m '${message}'`, { cwd: repoDir });
+}
+/** Initial commit so subsequent `git diff --cached` against HEAD works. */
+async function seedInitial() {
+    await writeFile("README.md", "# seed\n");
+    stage("README.md");
+    commit("initial");
+}
+// ---------------------------------------------------------------------
+// Pure helper tests (no git involvement)
+// ---------------------------------------------------------------------
+describe("isSourceFile", () => {
+    it("matches src/ at repo root", () => {
+        expect(isSourceFile("src/index.ts")).toBe(true);
+        expect(isSourceFile("src/hooks/foo.ts")).toBe(true);
+    });
+    it("matches nested src/ in workspace member", () => {
+        expect(isSourceFile("crates/engine/src/lib.rs")).toBe(true);
+        expect(isSourceFile("packages/x/src/foo.js")).toBe(true);
+    });
+    it("does not match top-level files outside src/", () => {
+        expect(isSourceFile("README.md")).toBe(false);
+        expect(isSourceFile("Cargo.toml")).toBe(false);
+        expect(isSourceFile("package.json")).toBe(false);
+        expect(isSourceFile("CHANGELOG.md")).toBe(false);
+        expect(isSourceFile(".github/workflows/ci.yml")).toBe(false);
+        expect(isSourceFile("tests/foo.test.ts")).toBe(false);
+    });
+    it("does not match 'srcfoo/' (false-prefix)", () => {
+        expect(isSourceFile("srcfoo/bar.ts")).toBe(false);
+    });
+});
+describe("isManifestFile", () => {
+    it("matches root-level manifests", () => {
+        expect(isManifestFile("Cargo.toml")).toBe(true);
+        expect(isManifestFile("package.json")).toBe(true);
+    });
+    it("matches nested manifests (workspace members)", () => {
+        expect(isManifestFile("crates/engine/Cargo.toml")).toBe(true);
+        expect(isManifestFile("packages/x/package.json")).toBe(true);
+    });
+    it("does not match other tomls / jsons", () => {
+        expect(isManifestFile("tsconfig.json")).toBe(false);
+        expect(isManifestFile("rustfmt.toml")).toBe(false);
+        expect(isManifestFile("clippy.toml")).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------
+// Allow paths — gate should NOT block
+// ---------------------------------------------------------------------
+describe("evaluateVersioningGate — allow paths", () => {
+    it("allows when nothing is staged", async () => {
+        await seedInitial();
+        const r = await evaluateVersioningGate({ cwd: repoDir });
+        expect(r.block).toBe(false);
+        expect(r.stderr).toBe("");
+    });
+    it("allows docs-only commit (no src/ staged)", async () => {
+        await seedInitial();
+        await writeFile("README.md", "# updated\n");
+        await writeFile("CHANGELOG.md", "## changes\n");
+        stage("README.md");
+        stage("CHANGELOG.md");
+        const r = await evaluateVersioningGate({ cwd: repoDir });
+        expect(r.block).toBe(false);
+    });
+    it("allows CI-only commit", async () => {
+        await seedInitial();
+        await writeFile(".github/workflows/ci.yml", "name: CI\n");
+        stage(".github/workflows/ci.yml");
+        const r = await evaluateVersioningGate({ cwd: repoDir });
+        expect(r.block).toBe(false);
+    });
+    it("allows src + Cargo.toml version bump in same commit", async () => {
+        await seedInitial();
+        await writeFile("Cargo.toml", 'version = "0.1.0"\n');
+        await writeFile("src/lib.rs", "// initial\n");
+        stage("Cargo.toml");
+        stage("src/lib.rs");
+        commit("initial src + manifest");
+        // Now bump:
+        await writeFile("Cargo.toml", 'version = "0.1.1"\n');
+        await writeFile("src/lib.rs", "// patched\n");
+        stage("Cargo.toml");
+        stage("src/lib.rs");
+        const r = await evaluateVersioningGate({ cwd: repoDir });
+        expect(r.block).toBe(false);
+    });
+    // Audit HIGH fix (v0.6.3): minified package.json was originally a
+    // false-positive block because the regex anchored `^"version"` and
+    // minified JSON has `"version"` mid-line. Drop the anchor.
+    it("allows src + MINIFIED package.json version bump (audit HIGH regression)", async () => {
+        await seedInitial();
+        await writeFile("package.json", '{"name":"x","version":"0.1.0"}\n');
+        await writeFile("src/index.ts", "// initial\n");
+        stage("package.json");
+        stage("src/index.ts");
+        commit("initial");
+        await writeFile("package.json", '{"name":"x","version":"0.1.1"}\n');
+        await writeFile("src/index.ts", "// patched\n");
+        stage("package.json");
+        stage("src/index.ts");
+        const r = await evaluateVersioningGate({ cwd: repoDir });
+        expect(r.block).toBe(false);
+    });
+    it("allows src + package.json version bump in same commit (realistic multi-line JSON)", async () => {
+        await seedInitial();
+        // Real package.json is pretty-printed multi-line so the diff
+        // surfaces a `"version": "..."` change on its own line.
+        const pkgV1 = JSON.stringify({ name: "x", version: "0.1.0" }, null, 2) + "\n";
+        const pkgV2 = JSON.stringify({ name: "x", version: "0.1.1" }, null, 2) + "\n";
+        await writeFile("package.json", pkgV1);
+        await writeFile("src/index.ts", "// initial\n");
+        stage("package.json");
+        stage("src/index.ts");
+        commit("initial");
+        await writeFile("package.json", pkgV2);
+        await writeFile("src/index.ts", "// patched\n");
+        stage("package.json");
+        stage("src/index.ts");
+        const r = await evaluateVersioningGate({ cwd: repoDir });
+        expect(r.block).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------
+// Block paths — gate SHOULD block
+// ---------------------------------------------------------------------
+describe("evaluateVersioningGate — block paths", () => {
+    it("blocks src/ change with no manifest staged", async () => {
+        await seedInitial();
+        await writeFile("Cargo.toml", 'version = "0.1.0"\n');
+        await writeFile("src/lib.rs", "// initial\n");
+        stage("Cargo.toml");
+        stage("src/lib.rs");
+        commit("initial src + manifest");
+        // Now ONLY src changes, no manifest bump:
+        await writeFile("src/lib.rs", "// edited\n");
+        stage("src/lib.rs");
+        const r = await evaluateVersioningGate({ cwd: repoDir });
+        expect(r.block).toBe(true);
+        expect(r.stderr).toContain("commit blocked");
+        expect(r.stderr).toContain("src/lib.rs");
+        expect(r.stderr).toContain("No Cargo.toml or package.json staged");
+    });
+    it("blocks src/ change with manifest staged but no version-line diff", async () => {
+        await seedInitial();
+        await writeFile("Cargo.toml", 'version = "0.1.0"\n[dependencies]\nfoo = "1"\n');
+        await writeFile("src/lib.rs", "// initial\n");
+        stage("Cargo.toml");
+        stage("src/lib.rs");
+        commit("initial");
+        // Touch manifest (add dep) but DON'T bump version, also touch src:
+        await writeFile("Cargo.toml", 'version = "0.1.0"\n[dependencies]\nfoo = "1"\nbar = "2"\n');
+        await writeFile("src/lib.rs", "// edited\n");
+        stage("Cargo.toml");
+        stage("src/lib.rs");
+        const r = await evaluateVersioningGate({ cwd: repoDir });
+        expect(r.block).toBe(true);
+        expect(r.stderr).toContain("no version-line diff");
+        expect(r.stderr).toContain("Cargo.toml");
+    });
+});
+// ---------------------------------------------------------------------
+// Multi-manifest / workspace
+// ---------------------------------------------------------------------
+describe("evaluateVersioningGate — workspace / multi-manifest", () => {
+    it("allows when ANY staged manifest has a version bump", async () => {
+        await seedInitial();
+        await writeFile("crates/a/Cargo.toml", 'version = "0.1.0"\n');
+        await writeFile("crates/b/Cargo.toml", 'version = "0.1.0"\n');
+        await writeFile("crates/a/src/lib.rs", "// a\n");
+        await writeFile("crates/b/src/lib.rs", "// b\n");
+        stage("crates/a/Cargo.toml");
+        stage("crates/b/Cargo.toml");
+        stage("crates/a/src/lib.rs");
+        stage("crates/b/src/lib.rs");
+        commit("initial");
+        // Bump ONLY crate a; edit src in BOTH:
+        await writeFile("crates/a/Cargo.toml", 'version = "0.1.1"\n');
+        await writeFile("crates/a/src/lib.rs", "// a patched\n");
+        await writeFile("crates/b/src/lib.rs", "// b edited\n");
+        stage("crates/a/Cargo.toml");
+        stage("crates/a/src/lib.rs");
+        stage("crates/b/src/lib.rs");
+        const r = await evaluateVersioningGate({ cwd: repoDir });
+        // Liberal policy: ANY manifest bump is enough. Workspace-wide
+        // discipline is a v0.6.4+ refinement if needed.
+        expect(r.block).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------
+// Emergency override
+// ---------------------------------------------------------------------
+describe("evaluateVersioningGate — emergency override", () => {
+    it("ALLOWS with bypass warning when OPENSQUID_SKIP_VERSION_GATE=1", async () => {
+        process.env.OPENSQUID_SKIP_VERSION_GATE = "1";
+        expect(checkOverrideEnv()).toBe(true);
+        await seedInitial();
+        await writeFile("Cargo.toml", 'version = "0.1.0"\n');
+        await writeFile("src/lib.rs", "// initial\n");
+        stage("Cargo.toml");
+        stage("src/lib.rs");
+        commit("initial");
+        await writeFile("src/lib.rs", "// edited\n");
+        stage("src/lib.rs");
+        const r = await evaluateVersioningGate({ cwd: repoDir });
+        expect(r.block).toBe(false);
+        expect(r.stderr).toContain("BYPASSED");
+    });
+    it("respects the env var only when EXACTLY '1'", async () => {
+        process.env.OPENSQUID_SKIP_VERSION_GATE = "true";
+        expect(checkOverrideEnv()).toBe(false);
+        process.env.OPENSQUID_SKIP_VERSION_GATE = "1";
+        expect(checkOverrideEnv()).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------
+// 0.7.23 / D5 — multi-patch catch-up jump detection
+// ---------------------------------------------------------------------
+describe("parseVersionJumpFromDiff", () => {
+    it("parses a Cargo.toml patch bump", () => {
+        const diff = `--- a/Cargo.toml
++++ b/Cargo.toml
+@@ -1 +1 @@
+-version = "0.7.10"
++version = "0.7.11"
+`;
+        expect(parseVersionJumpFromDiff(diff)).toEqual({ from: "0.7.10", to: "0.7.11" });
+    });
+    it("parses a package.json patch bump", () => {
+        const diff = `--- a/package.json
++++ b/package.json
+@@ -2 +2 @@
+-  "version": "0.7.10",
++  "version": "0.7.11",
+`;
+        expect(parseVersionJumpFromDiff(diff)).toEqual({ from: "0.7.10", to: "0.7.11" });
+    });
+    it("parses a multi-patch jump (D5 incident shape)", () => {
+        const diff = `--- a/package.json
++++ b/package.json
+-  "version": "0.7.10",
++  "version": "0.7.14",
+`;
+        expect(parseVersionJumpFromDiff(diff)).toEqual({ from: "0.7.10", to: "0.7.14" });
+    });
+    it("returns null when no version line is touched", () => {
+        const diff = `--- a/package.json
++++ b/package.json
++  "description": "updated text",
+-  "description": "old text",
+`;
+        expect(parseVersionJumpFromDiff(diff)).toBeNull();
+    });
+});
+describe("isMultiPatchJump", () => {
+    it("flags 0.7.10 → 0.7.14 (D5 catch-up)", () => {
+        expect(isMultiPatchJump({ from: "0.7.10", to: "0.7.14" })).toBe(true);
+    });
+    it("flags 0.7.10 → 0.7.12 (2-step jump)", () => {
+        expect(isMultiPatchJump({ from: "0.7.10", to: "0.7.12" })).toBe(true);
+    });
+    it("does NOT flag a normal 0.7.10 → 0.7.11 patch bump", () => {
+        expect(isMultiPatchJump({ from: "0.7.10", to: "0.7.11" })).toBe(false);
+    });
+    it("does NOT flag a minor bump (0.7.x → 0.8.0)", () => {
+        // Minor/major bumps are user-authorized; not the agent's drift to warn about.
+        expect(isMultiPatchJump({ from: "0.7.20", to: "0.8.0" })).toBe(false);
+    });
+    it("does NOT flag a first-time version (from empty)", () => {
+        expect(isMultiPatchJump({ from: "", to: "0.1.0" })).toBe(false);
+    });
+    it("does NOT flag non-SemVer strings", () => {
+        expect(isMultiPatchJump({ from: "wip", to: "wip-2" })).toBe(false);
+    });
+});
+describe("evaluateVersioningGate — multi-patch warning end-to-end (D5)", () => {
+    it("ALLOWS but WARNS when commit bumps version by >1 patch", async () => {
+        await seedInitial();
+        await writeFile("Cargo.toml", 'version = "0.7.10"\n');
+        await writeFile("src/lib.rs", "// initial\n");
+        stage("Cargo.toml");
+        stage("src/lib.rs");
+        commit("initial");
+        // Now jump 0.7.10 → 0.7.14 in one commit alongside a src change
+        await writeFile("Cargo.toml", 'version = "0.7.14"\n');
+        await writeFile("src/lib.rs", "// changed\n");
+        stage("Cargo.toml");
+        stage("src/lib.rs");
+        const r = await evaluateVersioningGate({ cwd: repoDir });
+        expect(r.block).toBe(false);
+        expect(r.stderr).toContain("catch-up bump detected");
+        expect(r.stderr).toContain("0.7.10 → 0.7.14");
+        expect(r.stderr).toContain("Drift D5");
+    });
+    it("does NOT warn on a clean +1 patch bump", async () => {
+        await seedInitial();
+        await writeFile("Cargo.toml", 'version = "0.7.10"\n');
+        await writeFile("src/lib.rs", "// initial\n");
+        stage("Cargo.toml");
+        stage("src/lib.rs");
+        commit("initial");
+        await writeFile("Cargo.toml", 'version = "0.7.11"\n');
+        await writeFile("src/lib.rs", "// changed\n");
+        stage("Cargo.toml");
+        stage("src/lib.rs");
+        const r = await evaluateVersioningGate({ cwd: repoDir });
+        expect(r.block).toBe(false);
+        expect(r.stderr).toBe("");
+    });
+});
+// ---------------------------------------------------------------------
+// Fail-open invariant
+// ---------------------------------------------------------------------
+describe("evaluateVersioningGate — fail-open invariant", () => {
+    it("ALLOWS with stderr warning when git is not available (non-repo cwd)", async () => {
+        const notARepo = path.join(os.tmpdir(), `not-a-repo-${crypto.randomUUID()}`);
+        await fs.mkdir(notARepo, { recursive: true });
+        try {
+            const r = await evaluateVersioningGate({ cwd: notARepo });
+            expect(r.block).toBe(false);
+            expect(r.stderr).toContain("git diff failed");
+        }
+        finally {
+            await fs.rm(notARepo, { recursive: true, force: true });
+        }
+    });
+});