opensquid 0.5.395

package/dist/hooks/workflow-gate.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Workflow gate — engine-backed commit-blocking check (v0.6.1).
+ *
+ * Wired into the PreToolUse hook when the planned tool call is
+ * `git commit` (without `--amend`). Checks that the active task's
+ * phase ledger has the required workflow phases logged; blocks the
+ * commit with an actionable stderr message if not.
+ *
+ * The required-phase policy is fixed for now (per user direction):
+ * `audit` + `post_research` must be logged. These are the phases
+ * empirically skipped under "ship fast" pressure. The other phases
+ * (pre_research, learn, code, test, fix) are either obvious from the
+ * commit itself or naturally happen — gating them too creates
+ * paperwork friction without catching real drift.
+ *
+ * Fail-open invariant: any error reaching the engine, parsing the
+ * transcript, or detecting the active task → return non-blocking
+ * with a stderr warning. The gate is best-effort drift protection,
+ * not a hard safety wall (mirrors the honesty-ledger precedent at
+ * pre-tool-use.ts).
+ */
+/**
+ * Resolve the set of phases that must be logged before `git commit`
+ * is allowed.
+ *
+ * 0.7.16 (drift-as-codex chunk 3a): the required-phase list now comes
+ * from `bundled-default/codex.yaml`'s `default_workflow_id` workflow,
+ * filtered to phases with `required: true`. Previously this was a
+ * hard-coded `REQUIRED_PHASES` array; the codex is now the single
+ * source of truth, which is what drift-as-codex was for.
+ *
+ * Fail-open: if the codex can't be loaded (missing file, parse error,
+ * missing workflow id), the gate disables itself with a stderr
+ * warning rather than blocking every commit. The codex is bundled
+ * in the npm package so this should be unreachable in normal use.
+ */
+export declare function getRequiredPhasesFromCodex(): readonly string[];
+export interface WorkflowGateInput {
+    /** Path to the session's JSONL transcript. Optional — gate falls
+     * back to allow-commit when absent (can't detect active task). */
+    transcriptPath?: string;
+}
+export interface WorkflowGateResult {
+    /** True when the commit should be blocked. */
+    block: boolean;
+    /** Stderr message (always present when stderr should be written;
+     * non-blocking warnings also use this). */
+    stderr: string;
+}
+/**
+ * Evaluate whether the planned `git commit` should be blocked.
+ * Pure function over its inputs + an engine RPC; safe to call from
+ * the hook handler.
+ */
+export declare function evaluateWorkflowGate(input: WorkflowGateInput): Promise<WorkflowGateResult>;
+/**
+ * Emergency-override env var. Lets the user bypass the gate when they
+ * know what they're doing. Logged loudly to stderr so the bypass is
+ * always visible in scrollback / CI logs.
+ *
+ * Exported for the test suite.
+ */
+export declare function checkOverrideEnv(): boolean;
+//# sourceMappingURL=workflow-gate.d.ts.map

package/dist/hooks/workflow-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-gate.d.ts","sourceRoot":"","sources":["../../src.legacy/hooks/workflow-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,IAAI,SAAS,MAAM,EAAE,CAW9D;AAED,MAAM,WAAW,iBAAiB;IAChC;sEACkE;IAClE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,KAAK,EAAE,OAAO,CAAC;IACf;+CAC2C;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA4EhG;AAiBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C"}

package/dist/hooks/workflow-gate.js

@@ -0,0 +1,152 @@
+/**
+ * Workflow gate — engine-backed commit-blocking check (v0.6.1).
+ *
+ * Wired into the PreToolUse hook when the planned tool call is
+ * `git commit` (without `--amend`). Checks that the active task's
+ * phase ledger has the required workflow phases logged; blocks the
+ * commit with an actionable stderr message if not.
+ *
+ * The required-phase policy is fixed for now (per user direction):
+ * `audit` + `post_research` must be logged. These are the phases
+ * empirically skipped under "ship fast" pressure. The other phases
+ * (pre_research, learn, code, test, fix) are either obvious from the
+ * commit itself or naturally happen — gating them too creates
+ * paperwork friction without catching real drift.
+ *
+ * Fail-open invariant: any error reaching the engine, parsing the
+ * transcript, or detecting the active task → return non-blocking
+ * with a stderr warning. The gate is best-effort drift protection,
+ * not a hard safety wall (mirrors the honesty-ledger precedent at
+ * pre-tool-use.ts).
+ */
+import { loadBundledDefaultCodex } from "../codex/loader.js";
+import { OpenSquidEngine } from "../engine-client.js";
+import { readActiveTaskId } from "./transcript.js";
+/**
+ * Resolve the set of phases that must be logged before `git commit`
+ * is allowed.
+ *
+ * 0.7.16 (drift-as-codex chunk 3a): the required-phase list now comes
+ * from `bundled-default/codex.yaml`'s `default_workflow_id` workflow,
+ * filtered to phases with `required: true`. Previously this was a
+ * hard-coded `REQUIRED_PHASES` array; the codex is now the single
+ * source of truth, which is what drift-as-codex was for.
+ *
+ * Fail-open: if the codex can't be loaded (missing file, parse error,
+ * missing workflow id), the gate disables itself with a stderr
+ * warning rather than blocking every commit. The codex is bundled
+ * in the npm package so this should be unreachable in normal use.
+ */
+export function getRequiredPhasesFromCodex() {
+    const codex = loadBundledDefaultCodex();
+    const workflowId = codex.default_workflow_id;
+    if (!workflowId) {
+        throw new Error("bundled-default codex has no default_workflow_id");
+    }
+    const workflow = (codex.workflows ?? []).find((w) => w.id === workflowId);
+    if (!workflow) {
+        throw new Error(`bundled-default codex has no workflow with id=${workflowId}`);
+    }
+    return workflow.phases.filter((p) => p.required).map((p) => p.name);
+}
+/**
+ * Evaluate whether the planned `git commit` should be blocked.
+ * Pure function over its inputs + an engine RPC; safe to call from
+ * the hook handler.
+ */
+export async function evaluateWorkflowGate(input) {
+    // Emergency override — explicit env var bypass with loud warning.
+    if (checkOverrideEnv()) {
+        return {
+            block: false,
+            stderr: "🦑 [opensquid workflow-gate] BYPASSED via OPENSQUID_SKIP_WORKFLOW_GATE=1\n",
+        };
+    }
+    if (!input.transcriptPath) {
+        // Can't detect active task. Allow with a debug-level warn so the
+        // gate's absence is observable.
+        return {
+            block: false,
+            stderr: "[opensquid workflow-gate] no transcript_path — gate skipped\n",
+        };
+    }
+    let taskId = null;
+    try {
+        taskId = await readActiveTaskId(input.transcriptPath);
+    }
+    catch (err) {
+        return {
+            block: false,
+            stderr: `[opensquid workflow-gate] transcript read failed (proceeding): ${err instanceof Error ? err.message : err}\n`,
+        };
+    }
+    if (!taskId) {
+        // No active task — nothing to gate. Common case: ad-hoc commits
+        // outside any TaskCreate flow. Allow silently.
+        return { block: false, stderr: "" };
+    }
+    let requiredPhases;
+    try {
+        requiredPhases = getRequiredPhasesFromCodex();
+    }
+    catch (err) {
+        // Codex unloadable (missing bundled YAML, parse error, etc.).
+        // Fail-open consistent with the gate's other failure modes.
+        return {
+            block: false,
+            stderr: `[opensquid workflow-gate] codex unloadable (proceeding): ${err instanceof Error ? err.message : err}\n`,
+        };
+    }
+    const engine = new OpenSquidEngine();
+    let ledger = null;
+    try {
+        ledger = await engine.getTaskLedger({
+            task_id: taskId,
+        });
+    }
+    catch (err) {
+        // Engine unreachable, binary missing, RPC error. Fail-open.
+        return {
+            block: false,
+            stderr: `[opensquid workflow-gate] engine unreachable (proceeding): ${err instanceof Error ? err.message : err}\n`,
+        };
+    }
+    finally {
+        // The OpenSquidEngine wrapper spawns a subprocess; shut it down
+        // so the hook process can exit cleanly.
+        try {
+            engine.shutdown();
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    const logged = new Set(ledger.phases_logged);
+    const missing = requiredPhases.filter((p) => !logged.has(p));
+    if (missing.length === 0) {
+        return { block: false, stderr: "" };
+    }
+    return {
+        block: true,
+        stderr: buildBlockMessage(taskId, missing, ledger.phases_logged),
+    };
+}
+function buildBlockMessage(taskId, missing, loggedPhases) {
+    const loggedList = loggedPhases.length === 0 ? "(none)" : loggedPhases.join(", ");
+    return (`🦑 [opensquid workflow-gate] commit blocked for task ${taskId}\n` +
+        `  missing phases: ${missing.join(", ")}\n` +
+        `  logged phases:  ${loggedList}\n` +
+        `  Log the missing phases via the \`log_phase\` MCP tool, then retry the commit.\n` +
+        `  Override (genuine emergency): set OPENSQUID_SKIP_WORKFLOW_GATE=1 for this command.\n`);
+}
+/**
+ * Emergency-override env var. Lets the user bypass the gate when they
+ * know what they're doing. Logged loudly to stderr so the bypass is
+ * always visible in scrollback / CI logs.
+ *
+ * Exported for the test suite.
+ */
+export function checkOverrideEnv() {
+    return process.env.OPENSQUID_SKIP_WORKFLOW_GATE === "1";
+}
+//# sourceMappingURL=workflow-gate.js.map

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

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

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

@@ -0,0 +1,197 @@
+/**
+ * Workflow-gate tests — covers the pure evaluator (no engine subprocess
+ * spawned). We mock the OpenSquidEngine.getTaskLedger to assert the
+ * gate behavior without standing up a real engine binary. The hook
+ * test wires the gate into the actual PreToolUse flow.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+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 * as engineClient from "../engine-client.js";
+import { checkOverrideEnv, evaluateWorkflowGate, getRequiredPhasesFromCodex, } from "./workflow-gate.js";
+// ---------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------
+let tmpDir;
+let transcriptPath;
+beforeEach(async () => {
+    tmpDir = path.join(os.tmpdir(), `opensquid-gate-${crypto.randomUUID()}`);
+    await fs.mkdir(tmpDir, { recursive: true });
+    transcriptPath = path.join(tmpDir, "transcript.jsonl");
+});
+afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+    delete process.env.OPENSQUID_SKIP_WORKFLOW_GATE;
+    vi.restoreAllMocks();
+});
+async function writeTranscriptWithActiveTask(taskId) {
+    // Single assistant tool_use event with a TodoWrite block. Matches
+    // the shape readActiveTaskId scans for.
+    const event = {
+        type: "assistant",
+        message: {
+            role: "assistant",
+            content: [
+                {
+                    type: "tool_use",
+                    name: "TodoWrite",
+                    input: {
+                        todos: [
+                            { id: "999", status: "completed", content: "done thing" },
+                            { id: taskId, status: "in_progress", content: "active thing" },
+                        ],
+                    },
+                },
+            ],
+        },
+    };
+    await fs.writeFile(transcriptPath, JSON.stringify(event) + "\n", "utf8");
+}
+/** Mock OpenSquidEngine.getTaskLedger to return a specific phase set. */
+function mockLedger(phasesLogged) {
+    vi.spyOn(engineClient.OpenSquidEngine.prototype, "getTaskLedger").mockResolvedValue({
+        task_id: "127",
+        phases_logged: phasesLogged,
+        entries: phasesLogged.map((p) => ({
+            phase: p,
+            logged_at: "2026-05-16T08:00:00.000Z",
+            note: null,
+        })),
+    });
+    // shutdown() is called in the finally block of evaluateWorkflowGate.
+    vi.spyOn(engineClient.OpenSquidEngine.prototype, "shutdown").mockImplementation(() => { });
+}
+/** Mock the engine call to throw — simulates engine unreachable. */
+function mockLedgerError(message) {
+    vi.spyOn(engineClient.OpenSquidEngine.prototype, "getTaskLedger").mockRejectedValue(new Error(message));
+    vi.spyOn(engineClient.OpenSquidEngine.prototype, "shutdown").mockImplementation(() => { });
+}
+// ---------------------------------------------------------------------
+// Fail-open input scenarios — no block, no engine call
+// ---------------------------------------------------------------------
+describe("evaluateWorkflowGate — fail-open inputs", () => {
+    it("returns allow with warning when transcriptPath is missing", async () => {
+        const result = await evaluateWorkflowGate({});
+        expect(result.block).toBe(false);
+        expect(result.stderr).toContain("no transcript_path");
+    });
+    it("returns allow when transcript has no in_progress task", async () => {
+        await fs.writeFile(transcriptPath, "", "utf8");
+        const result = await evaluateWorkflowGate({ transcriptPath });
+        expect(result.block).toBe(false);
+        expect(result.stderr).toBe("");
+    });
+    it("returns allow with warning when transcript path doesn't exist", async () => {
+        const result = await evaluateWorkflowGate({
+            transcriptPath: path.join(tmpDir, "nonexistent.jsonl"),
+        });
+        expect(result.block).toBe(false);
+        // readActiveTaskId swallows the read error → returns null → allow silently.
+        expect(result.stderr).toBe("");
+    });
+});
+// ---------------------------------------------------------------------
+// Active task detected → engine RPC drives decision
+// ---------------------------------------------------------------------
+describe("evaluateWorkflowGate — with active task", () => {
+    // 0.7.6 (#150): REQUIRED_PHASES expanded from ["audit",
+    // "post_research"] to all 6 required (fix stays soft). Tests
+    // updated accordingly. The 2-phase variant used to allow #132 to
+    // ship with most of its workflow unlogged.
+    it("BLOCKS when most required phases are missing", async () => {
+        await writeTranscriptWithActiveTask("127");
+        mockLedger(["code", "test"]);
+        const result = await evaluateWorkflowGate({ transcriptPath });
+        expect(result.block).toBe(true);
+        expect(result.stderr).toContain("commit blocked");
+        expect(result.stderr).toContain("pre_research");
+        expect(result.stderr).toContain("audit");
+        expect(result.stderr).toContain("post_research");
+        expect(result.stderr).toContain("127");
+    });
+    it("BLOCKS when only audit is missing (6-of-6 expansion)", async () => {
+        await writeTranscriptWithActiveTask("127");
+        mockLedger(["pre_research", "learn", "code", "test", "post_research"]);
+        const result = await evaluateWorkflowGate({ transcriptPath });
+        expect(result.block).toBe(true);
+        expect(result.stderr).toContain("missing phases: audit");
+    });
+    it("BLOCKS when only post_research is missing", async () => {
+        await writeTranscriptWithActiveTask("127");
+        mockLedger(["pre_research", "learn", "code", "test", "audit"]);
+        const result = await evaluateWorkflowGate({ transcriptPath });
+        expect(result.block).toBe(true);
+        expect(result.stderr).toContain("missing phases: post_research");
+    });
+    it("BLOCKS when only pre_research is missing (catches #132's shape)", async () => {
+        // #132 shipped today with only audit + post_research logged.
+        // The pre-#150 gate let it through. New gate catches it.
+        await writeTranscriptWithActiveTask("132");
+        mockLedger(["learn", "code", "test", "audit", "post_research"]);
+        const result = await evaluateWorkflowGate({ transcriptPath });
+        expect(result.block).toBe(true);
+        expect(result.stderr).toContain("missing phases: pre_research");
+    });
+    it("ALLOWS when all 6 required phases are logged (fix stays optional)", async () => {
+        await writeTranscriptWithActiveTask("127");
+        mockLedger(["pre_research", "learn", "code", "test", "audit", "post_research"]);
+        const result = await evaluateWorkflowGate({ transcriptPath });
+        expect(result.block).toBe(false);
+        expect(result.stderr).toBe("");
+    });
+    it("ALLOWS when more than the required phases are logged (extra is fine)", async () => {
+        await writeTranscriptWithActiveTask("127");
+        mockLedger(["pre_research", "learn", "code", "test", "audit", "post_research", "fix"]);
+        const result = await evaluateWorkflowGate({ transcriptPath });
+        expect(result.block).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------
+// Fail-open on engine error
+// ---------------------------------------------------------------------
+describe("evaluateWorkflowGate — fail-open invariant", () => {
+    it("ALLOWS with stderr warning when engine RPC throws", async () => {
+        await writeTranscriptWithActiveTask("127");
+        mockLedgerError("ECONNREFUSED: engine not running");
+        const result = await evaluateWorkflowGate({ transcriptPath });
+        expect(result.block).toBe(false);
+        expect(result.stderr).toContain("engine unreachable");
+        expect(result.stderr).toContain("ECONNREFUSED");
+    });
+});
+// ---------------------------------------------------------------------
+// Emergency override
+// ---------------------------------------------------------------------
+// ---------------------------------------------------------------------
+// Codex-driven required-phases (drift-as-codex chunk 3a, 0.7.16)
+// ---------------------------------------------------------------------
+describe("getRequiredPhasesFromCodex", () => {
+    it("returns the 6 required phases from the bundled-default codex's standard-7-phase workflow", () => {
+        const phases = getRequiredPhasesFromCodex();
+        expect(phases).toEqual(["pre_research", "learn", "code", "test", "audit", "post_research"]);
+    });
+    it("excludes the `fix` phase (required: false in the codex)", () => {
+        const phases = getRequiredPhasesFromCodex();
+        expect(phases).not.toContain("fix");
+    });
+});
+describe("evaluateWorkflowGate — emergency override", () => {
+    it("ALLOWS with bypass warning when OPENSQUID_SKIP_WORKFLOW_GATE=1", async () => {
+        process.env.OPENSQUID_SKIP_WORKFLOW_GATE = "1";
+        expect(checkOverrideEnv()).toBe(true);
+        // Should bypass even if all the other signals say block.
+        await writeTranscriptWithActiveTask("127");
+        mockLedger(["code"]); // would otherwise block
+        const result = await evaluateWorkflowGate({ transcriptPath });
+        expect(result.block).toBe(false);
+        expect(result.stderr).toContain("BYPASSED");
+    });
+    it("respects the env var only when EXACTLY '1' (not 'true', not 'yes')", async () => {
+        process.env.OPENSQUID_SKIP_WORKFLOW_GATE = "true";
+        expect(checkOverrideEnv()).toBe(false);
+        process.env.OPENSQUID_SKIP_WORKFLOW_GATE = "1";
+        expect(checkOverrideEnv()).toBe(true);
+    });
+});

package/dist/hooks-cli.d.ts

@@ -0,0 +1,25 @@
+export declare class HooksCliError extends Error {
+    readonly hint?: string | undefined;
+    constructor(message: string, hint?: string | undefined);
+}
+interface ClaudeCommandHook {
+    type: "command";
+    command: string;
+    /** Custom non-standard marker so we can find our own hook later. */
+    _id?: string;
+}
+interface ClaudePromptHook {
+    type: "prompt";
+    prompt: string;
+    model?: string;
+    /** Optional timeout in seconds — Claude Code default is 30s for prompt hooks. */
+    timeout?: number;
+    _id?: string;
+}
+type ClaudeHook = ClaudeCommandHook | ClaudePromptHook;
+/** True when a hook entry is recognizably opensquid's. */
+export declare function isOurHook(h: ClaudeHook): boolean;
+export type HooksCliCmd = "install" | "uninstall" | "doctor";
+export declare function runHooksCli(cmd: HooksCliCmd, _argv: string[]): Promise<void>;
+export {};
+//# sourceMappingURL=hooks-cli.d.ts.map

package/dist/hooks-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks-cli.d.ts","sourceRoot":"","sources":["../src.legacy/hooks-cli.ts"],"names":[],"mappings":"AAsBA,qBAAa,aAAc,SAAQ,KAAK;aAGpB,IAAI,CAAC,EAAE,MAAM;gBAD7B,OAAO,EAAE,MAAM,EACC,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC;AA2DD,UAAU,iBAAiB;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,UAAU,gBAAgB;IACxB,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,KAAK,UAAU,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;AAsDvD,0DAA0D;AAC1D,wBAAgB,SAAS,CAAC,CAAC,EAAE,UAAU,GAAG,OAAO,CAoBhD;AAkJD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE7D,wBAAsB,WAAW,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAYlF"}