tickmarkr 1.30.0

package/dist/gates/run-gates.js

@@ -0,0 +1,105 @@
+import { channelKey } from "../adapters/types.js";
+import { TIER_RANK } from "../config/config.js";
+import { getAdapter } from "../adapters/registry.js";
+import { GATE_NAMES } from "../graph/schema.js";
+import { acceptanceGate } from "./acceptance.js";
+import { compareToBaseline } from "./baseline.js";
+import { evidenceGate } from "./evidence.js";
+import { marginalCostRank } from "../route/router.js";
+import { reviewGate } from "./review.js";
+import { scopeGate } from "./scope.js";
+export async function runGates(task, ctx) {
+    const results = [];
+    let commits = [];
+    const shapeGates = ctx.cfg.gates.byShape?.[task.shape];
+    const enabled = (g) => task.gates.includes(g) && (g !== "acceptance" && g !== "review" || shapeGates?.[g] !== false);
+    const failed = () => results.some((r) => !r.pass);
+    const sequence = GATE_NAMES.filter((g) => enabled(g));
+    const total = sequence.length;
+    const indexOf = (gate) => sequence.indexOf(gate) + 1;
+    const record = async (result) => {
+        results.push(result);
+        await ctx.onGate?.({ phase: "end", gate: result.gate, result });
+    };
+    const emitStart = async (gate) => {
+        await ctx.onGate?.({ phase: "start", gate, index: indexOf(gate), total });
+    };
+    // 1. build/test/lint vs shared baseline — deterministic and cheap, first
+    const toolGates = ["build", "test", "lint"].filter(enabled);
+    if (toolGates.length) {
+        // ponytail: compareToBaseline batches build/test/lint — their starts are emitted at iteration,
+        // not at true execution start. They are collectively sub-second (measured), so the debounce
+        // suppresses them anyway; split compareToBaseline only if a tool gate ever gets slow.
+        const toolResults = await compareToBaseline(ctx.worktree, ctx.commands, ctx.baseline, toolGates);
+        for (const r of toolResults) {
+            await emitStart(r.gate);
+            await record(r);
+        }
+        if (failed())
+            return { results, commits };
+    }
+    // 2. evidence — did the worker actually commit anything?
+    if (enabled("evidence")) {
+        await emitStart("evidence");
+        const e = await evidenceGate(ctx.worktree, ctx.baseRef);
+        commits = e.commits;
+        await record({ gate: e.gate, pass: e.pass, details: e.details });
+        if (!e.pass)
+            return { results, commits };
+    }
+    // 3. scope
+    if (enabled("scope")) {
+        await emitStart("scope");
+        await record(await scopeGate(ctx.worktree, ctx.baseRef, task.files, ctx.result, ctx.cfg.scope?.allowDeviations ?? []));
+        if (failed())
+            return { results, commits };
+    }
+    // 4. acceptance judge (first LLM spend — everything cheaper already passed)
+    if (enabled("acceptance")) {
+        await emitStart("acceptance");
+        const judgeAdapter = getAdapter(ctx.cfg.judge.adapter, ctx.adapters);
+        const jvia = ctx.via
+            ? { driver: ctx.via.driver, keep: ctx.via.keep, onSlot: ctx.via.onSlot, name: ctx.via.nameFor("judge", judgeAdapter.id), label: ctx.via.labelFor("judge") }
+            : undefined;
+        // v1.19 (T2): testCmd threads the detected test runner to the gate so named-test oracles run
+        // deterministically (filtered via -t) before any LLM judge dispatch.
+        let a = await acceptanceGate(task, ctx.worktree, ctx.baseRef, { adapter: judgeAdapter, model: ctx.cfg.judge.model }, jvia, { testCmd: ctx.commands.test });
+        // GATE-09: an unparseable judge verdict retries the JUDGE exactly once on a failover channel — never
+        // the worker (run-20260711-185020 P43-03 L70-72 billed a judge flake as a worker attempt). The flaked
+        // first verdict NEVER enters results (no false gate-result journal event, no operator notify, no stale
+        // failed() short-circuit — research Pitfall 5). Detection is meta-only (D-03), never string-matching
+        // details. The v1.1 badReviewers precedent's TIMING can't transfer: its failover lands on the NEXT
+        // worker attempt — exactly what this fix forbids; only its meta-carries-channel pattern is mirrored.
+        // Straight-line single `if` — NO loop/counter/knob: exactly-once by construction (a knob is a
+        // fail-closed weakening vector); a second garbage verdict fails the gate closed exactly as today.
+        if (a.meta?.unparseable === true && typeof a.meta.judge === "string") {
+            const flakedKey = a.meta.judge;
+            const candidate = ctx.channels
+                .filter((c) => channelKey(c) !== flakedKey)
+                // pickReviewer's sort (review.ts:37): TIER_RANK desc, marginalCostRank asc — proven ordering; both
+                // symbols already imported by a sibling gate file. No vendor-diversity axis (the judge isn't review).
+                .sort((x, y) => TIER_RANK[y.tier] - TIER_RANK[x.tier] || marginalCostRank(x) - marginalCostRank(y))[0];
+            // ponytail: same-channel fallback when the fleet has no alternative (D-03). One judge call against a
+            // deterministic garbage source is wasted, bounded; fail-closed unchanged on a second garbage verdict.
+            const retry = candidate ?? { adapter: ctx.cfg.judge.adapter, model: ctx.cfg.judge.model };
+            const retryAdapter = getAdapter(retry.adapter, ctx.adapters);
+            const retryJvia = ctx.via
+                // unconditional -r1 suffix: under keepPanes:forever a same-channel retry cannot collide with the
+                // still-open first pane (herdr agent_name_taken regression, research Pitfall 4)
+                ? { driver: ctx.via.driver, keep: ctx.via.keep, onSlot: ctx.via.onSlot, name: ctx.via.nameFor("judge", retryAdapter.id) + "-r1", label: ctx.via.labelFor("judge") }
+                : undefined;
+            // the retry IS a second acceptanceGate call: one code path, one parser, zero new parse leniency.
+            a = await acceptanceGate(task, ctx.worktree, ctx.baseRef, { adapter: retryAdapter, model: retry.model }, retryJvia, { testCmd: ctx.commands.test });
+            a = { ...a, meta: { ...a.meta, judgeRetry: { flaked: flakedKey, retried: channelKey({ adapter: retry.adapter, model: retry.model }) } } };
+        }
+        await record(a);
+        if (failed())
+            return { results, commits };
+    }
+    // 5. cross-vendor review
+    if (enabled("review")) {
+        await emitStart("review");
+        await record(await reviewGate(task, ctx.worktree, ctx.baseRef, ctx.author, ctx.channels, ctx.adapters, ctx.cfg, ctx.via, ctx.excludeReviewers));
+    }
+    return { results, commits };
+}

package/dist/gates/scope.d.ts

@@ -0,0 +1,8 @@
+import type { WorkerResult } from "../adapters/types.js";
+import type { GateResult } from "./types.js";
+/** Pure offender split — corpus-replay oracle exercises this exact decision logic. */
+export declare function dispositionOffenders(offenders: string[], allowDeviations: string[]): {
+    hard: string[];
+    allowed: string[];
+};
+export declare function scopeGate(worktree: string, baseRef: string, files: string[], result: WorkerResult, allowDeviations?: string[]): Promise<GateResult>;

package/dist/gates/scope.js

@@ -0,0 +1,32 @@
+import picomatch from "picomatch";
+import { shOk } from "../run/git.js";
+/** Pure offender split — corpus-replay oracle exercises this exact decision logic. */
+export function dispositionOffenders(offenders, allowDeviations) {
+    const allowedMatch = allowDeviations.length ? picomatch(allowDeviations, { dot: true }) : () => false;
+    const allowed = [];
+    const hard = [];
+    for (const f of offenders) {
+        if (allowedMatch(f))
+            allowed.push(f);
+        else
+            hard.push(f);
+    }
+    return { hard, allowed };
+}
+export async function scopeGate(worktree, baseRef, files, result, allowDeviations = []) {
+    if (!files.length)
+        return { gate: "scope", pass: true, details: "no file scope declared — unrestricted" };
+    const changed = (await shOk(`git diff --name-only '${baseRef}..HEAD'`, worktree)).trim().split("\n").filter(Boolean);
+    const inScope = picomatch(files, { dot: true }); // byte-identical options to assertWriteScope in src/compile/common.ts
+    const offenders = changed.filter((f) => !inScope(f));
+    if (!offenders.length)
+        return { gate: "scope", pass: true, details: `all ${changed.length} changed files in scope` };
+    // HARD-08: a worker's declared deviation is an audit note, NEVER a pass — the gate decides against
+    // operator config only (invariant: gates never trust worker claims).
+    const { hard, allowed } = dispositionOffenders(offenders, allowDeviations);
+    const note = result.deviations.length ? `\nworker-declared deviations (audit note, not authority): ${result.deviations.join("; ")}` : "";
+    if (!hard.length) {
+        return { gate: "scope", pass: true, details: `out-of-scope but operator-allowlisted:\n${allowed.join("\n")}${note}` };
+    }
+    return { gate: "scope", pass: false, details: `out-of-scope edits not covered by scope.allowDeviations:\n${hard.join("\n")}${note}` };
+}

package/dist/gates/types.d.ts

@@ -0,0 +1,6 @@
+export interface GateResult {
+    gate: string;
+    pass: boolean;
+    details: string;
+    meta?: Record<string, unknown>;
+}

package/dist/gates/types.js

@@ -0,0 +1 @@
+export {};

package/dist/graph/graph.d.ts

@@ -0,0 +1,20 @@
+import { type RunGraph, type Task, type TaskStatus } from "./schema.js";
+export declare function stateDirName(repoRoot: string): string;
+export declare function graphPath(repoRoot: string): string;
+export declare function drovrDir(repoRoot: string): string;
+export declare function loadGraph(repoRoot: string): RunGraph;
+export declare function saveGraph(repoRoot: string, g: RunGraph): void;
+export declare function getTask(g: RunGraph, id: string): Task;
+export declare function setStatus(g: RunGraph, id: string, status: TaskStatus): RunGraph;
+export declare function addEvidence(g: RunGraph, id: string, patch: {
+    commits?: string[];
+    artifacts?: string[];
+    gateResults?: unknown[];
+}): RunGraph;
+export declare function readyTasks(g: RunGraph): Task[];
+export declare function isComplete(g: RunGraph): boolean;
+export declare function isStalled(g: RunGraph): boolean;
+export declare function closureReaches(g: RunGraph, taskId: string, pred: (t: Task) => boolean): boolean;
+export declare function blockedTasks(g: RunGraph): Task[];
+export declare function pendingTasks(g: RunGraph): Task[];
+export declare function attributeBlocked(g: RunGraph): Map<string, number>;

package/dist/graph/graph.js

@@ -0,0 +1,148 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { validateGraph } from "./schema.js";
+const stateDirs = new Map();
+export function stateDirName(repoRoot) {
+    const cached = stateDirs.get(repoRoot);
+    if (cached)
+        return cached;
+    const name = existsSync(join(repoRoot, ".drovr")) ? ".drovr" : existsSync(join(repoRoot, ".drover")) ? ".drover" : ".drovr";
+    stateDirs.set(repoRoot, name);
+    return name;
+}
+export function graphPath(repoRoot) {
+    return join(repoRoot, stateDirName(repoRoot), "graph.json");
+}
+export function drovrDir(repoRoot) {
+    const dir = join(repoRoot, stateDirName(repoRoot));
+    mkdirSync(dir, { recursive: true });
+    const gi = join(dir, ".gitignore");
+    if (!existsSync(gi))
+        writeFileSync(gi, "*\n");
+    return dir;
+}
+export function loadGraph(repoRoot) {
+    const p = graphPath(repoRoot);
+    if (!existsSync(p))
+        throw new Error(`no graph at ${p} — run \`drovr compile <src>\` first`);
+    return validateGraph(JSON.parse(readFileSync(p, "utf8")));
+}
+export function saveGraph(repoRoot, g) {
+    drovrDir(repoRoot);
+    const p = graphPath(repoRoot);
+    // Temp file MUST be a sibling of graph.json: rename(2) is atomic only within one filesystem
+    // (never os.tmpdir()). pid-suffix so a racing writer can't clobber our in-flight temp (HARD-04).
+    const tmp = `${p}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(g, null, 2) + "\n");
+        renameSync(tmp, p); // atomic same-volume (APFS included) — a reader never sees a torn document
+    }
+    catch (e) {
+        rmSync(tmp, { force: true }); // no .tmp litter behind a failed write
+        throw e;
+    }
+}
+export function getTask(g, id) {
+    const t = g.tasks.find((t) => t.id === id);
+    if (!t)
+        throw new Error(`unknown task ${id}`);
+    return t;
+}
+export function setStatus(g, id, status) {
+    getTask(g, id);
+    return { ...g, tasks: g.tasks.map((t) => (t.id === id ? { ...t, status } : t)) };
+}
+export function addEvidence(g, id, patch) {
+    getTask(g, id);
+    return {
+        ...g,
+        tasks: g.tasks.map((t) => t.id === id
+            ? {
+                ...t,
+                evidence: {
+                    commits: [...t.evidence.commits, ...(patch.commits ?? [])],
+                    artifacts: [...t.evidence.artifacts, ...(patch.artifacts ?? [])],
+                    gateResults: [...t.evidence.gateResults, ...(patch.gateResults ?? [])],
+                },
+            }
+            : t),
+    };
+}
+export function readyTasks(g) {
+    const done = new Set(g.tasks.filter((t) => t.status === "done").map((t) => t.id));
+    return g.tasks.filter((t) => t.status === "pending" && t.deps.every((d) => done.has(d)));
+}
+export function isComplete(g) {
+    return g.tasks.every((t) => t.status === "done");
+}
+export function isStalled(g) {
+    const running = g.tasks.some((t) => t.status === "running" || t.status === "gated");
+    return !isComplete(g) && !running && readyTasks(g).length === 0;
+}
+// parked = a terminal-for-now state that strands every downstream task (D-02/D-06)
+const isParked = (t) => t.status === "human" || t.status === "failed";
+// closureReaches: true iff the transitive dep-closure of `taskId` contains a task matching `pred`.
+// Walks FORWARD along Task.deps with an iterative stack + visited-set; cycles are impossible
+// (validateGraph rejects them at load), so a visited-set is for efficiency, not safety. Pure —
+// depends on RunGraph alone, never daemon/run state (D-06).
+export function closureReaches(g, taskId, pred) {
+    const byId = new Map(g.tasks.map((t) => [t.id, t]));
+    const visited = new Set();
+    const stack = [...(byId.get(taskId)?.deps ?? [])];
+    while (stack.length) {
+        const id = stack.pop();
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        const t = byId.get(id);
+        if (!t)
+            continue; // unknown deps are rejected at validate; defensive only
+        if (pred(t))
+            return true;
+        for (const d of t.deps)
+            if (!visited.has(d))
+                stack.push(d);
+    }
+    return false;
+}
+// blockedTasks: pending tasks whose dep-closure reaches a parked (human|failed) task —
+// "not-yet-run AND structurally unreachable" — the truthful bucket the operator must see (VIS-01).
+export function blockedTasks(g) {
+    return g.tasks.filter((t) => t.status === "pending" && closureReaches(g, t.id, isParked));
+}
+// pendingTasks: pending tasks whose closure does NOT reach a parked task — still runnable
+// in principle (deps pending/running). Distinct from blocked so the buckets never lie mid-quiesce.
+export function pendingTasks(g) {
+    return g.tasks.filter((t) => t.status === "pending" && !closureReaches(g, t.id, isParked));
+}
+// attributeBlocked: for every blockedTasks(g) member, BFS forward over deps (level order, not
+// closureReaches' DFS) to find its NEAREST parked (human|failed) ancestor and count it there.
+// A task under two parked roots attributes to the nearer one only — never double-counted (D-04).
+export function attributeBlocked(g) {
+    const byId = new Map(g.tasks.map((t) => [t.id, t]));
+    const counts = new Map();
+    for (const t of blockedTasks(g)) {
+        const visited = new Set();
+        const queue = [...t.deps];
+        let root;
+        while (queue.length) {
+            const id = queue.shift();
+            if (visited.has(id))
+                continue;
+            visited.add(id);
+            const dep = byId.get(id);
+            if (!dep)
+                continue;
+            if (isParked(dep)) {
+                root = dep.id;
+                break;
+            }
+            for (const d of dep.deps)
+                if (!visited.has(d))
+                    queue.push(d);
+        }
+        if (root)
+            counts.set(root, (counts.get(root) ?? 0) + 1);
+    }
+    return counts;
+}

package/dist/graph/schema.d.ts

@@ -0,0 +1,185 @@
+import { z } from "zod";
+export declare const SHAPES: readonly ["plan", "spec", "implement", "tests", "docs", "migration", "ui", "refactor", "chore"];
+export declare const STATUSES: readonly ["pending", "running", "gated", "failed", "done", "human"];
+export declare const GATE_NAMES: readonly ["build", "test", "lint", "evidence", "scope", "acceptance", "review"];
+export declare const TIERS: readonly ["cheap", "mid", "frontier"];
+export declare const ORACLES: readonly ["command", "test", "judge"];
+export type Shape = (typeof SHAPES)[number];
+export type TaskStatus = (typeof STATUSES)[number];
+export type GateName = (typeof GATE_NAMES)[number];
+export type Oracle = (typeof ORACLES)[number];
+export declare const AcceptanceItemSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    oracle: z.ZodLiteral<"command">;
+    command: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    oracle: z.ZodLiteral<"test">;
+    test: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    oracle: z.ZodLiteral<"judge">;
+    text: z.ZodString;
+}, z.core.$strip>]>;
+export type AcceptanceItem = z.infer<typeof AcceptanceItemSchema>;
+export declare function renderAcceptanceItem(item: AcceptanceItem): string;
+export declare const TaskSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    goal: z.ZodString;
+    shape: z.ZodEnum<{
+        plan: "plan";
+        spec: "spec";
+        implement: "implement";
+        tests: "tests";
+        docs: "docs";
+        migration: "migration";
+        ui: "ui";
+        refactor: "refactor";
+        chore: "chore";
+    }>;
+    complexity: z.ZodNumber;
+    deps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    files: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    context: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    acceptance: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        oracle: z.ZodLiteral<"command">;
+        command: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        oracle: z.ZodLiteral<"test">;
+        test: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        oracle: z.ZodLiteral<"judge">;
+        text: z.ZodString;
+    }, z.core.$strip>]>>;
+    scopeHints: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        paths: z.ZodArray<z.ZodString>;
+        confidence: z.ZodOptional<z.ZodNumber>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    gates: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        build: "build";
+        test: "test";
+        lint: "lint";
+        evidence: "evidence";
+        scope: "scope";
+        acceptance: "acceptance";
+        review: "review";
+    }>>>;
+    routingHints: z.ZodOptional<z.ZodObject<{
+        pin: z.ZodOptional<z.ZodObject<{
+            via: z.ZodString;
+            model: z.ZodString;
+        }, z.core.$strip>>;
+        floor: z.ZodOptional<z.ZodEnum<{
+            cheap: "cheap";
+            mid: "mid";
+            frontier: "frontier";
+        }>>;
+        source: z.ZodOptional<z.ZodString>;
+        escalate: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    humanGate: z.ZodDefault<z.ZodBoolean>;
+    status: z.ZodDefault<z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        gated: "gated";
+        failed: "failed";
+        done: "done";
+        human: "human";
+    }>>;
+    evidence: z.ZodDefault<z.ZodObject<{
+        commits: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        artifacts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        gateResults: z.ZodDefault<z.ZodArray<z.ZodUnknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const RunGraphSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    spec: z.ZodObject<{
+        source: z.ZodEnum<{
+            speckit: "speckit";
+            gsd: "gsd";
+            prd: "prd";
+            native: "native";
+            taskmaster: "taskmaster";
+        }>;
+        paths: z.ZodArray<z.ZodString>;
+        hash: z.ZodString;
+    }, z.core.$strip>;
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        goal: z.ZodString;
+        shape: z.ZodEnum<{
+            plan: "plan";
+            spec: "spec";
+            implement: "implement";
+            tests: "tests";
+            docs: "docs";
+            migration: "migration";
+            ui: "ui";
+            refactor: "refactor";
+            chore: "chore";
+        }>;
+        complexity: z.ZodNumber;
+        deps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        files: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        context: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        acceptance: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            oracle: z.ZodLiteral<"command">;
+            command: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            oracle: z.ZodLiteral<"test">;
+            test: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            oracle: z.ZodLiteral<"judge">;
+            text: z.ZodString;
+        }, z.core.$strip>]>>;
+        scopeHints: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            paths: z.ZodArray<z.ZodString>;
+            confidence: z.ZodOptional<z.ZodNumber>;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        gates: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            build: "build";
+            test: "test";
+            lint: "lint";
+            evidence: "evidence";
+            scope: "scope";
+            acceptance: "acceptance";
+            review: "review";
+        }>>>;
+        routingHints: z.ZodOptional<z.ZodObject<{
+            pin: z.ZodOptional<z.ZodObject<{
+                via: z.ZodString;
+                model: z.ZodString;
+            }, z.core.$strip>>;
+            floor: z.ZodOptional<z.ZodEnum<{
+                cheap: "cheap";
+                mid: "mid";
+                frontier: "frontier";
+            }>>;
+            source: z.ZodOptional<z.ZodString>;
+            escalate: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        humanGate: z.ZodDefault<z.ZodBoolean>;
+        status: z.ZodDefault<z.ZodEnum<{
+            pending: "pending";
+            running: "running";
+            gated: "gated";
+            failed: "failed";
+            done: "done";
+            human: "human";
+        }>>;
+        evidence: z.ZodDefault<z.ZodObject<{
+            commits: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            artifacts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            gateResults: z.ZodDefault<z.ZodArray<z.ZodUnknown>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Task = z.infer<typeof TaskSchema>;
+export type RunGraph = z.infer<typeof RunGraphSchema>;
+export declare class GraphValidationError extends Error {
+    issues: string[];
+    constructor(issues: string[]);
+}
+export declare function validateGraph(data: unknown): RunGraph;

package/dist/graph/schema.js

@@ -0,0 +1,141 @@
+import { z } from "zod";
+export const SHAPES = ["plan", "spec", "implement", "tests", "docs", "migration", "ui", "refactor", "chore"];
+export const STATUSES = ["pending", "running", "gated", "failed", "done", "human"];
+export const GATE_NAMES = ["build", "test", "lint", "evidence", "scope", "acceptance", "review"];
+export const TIERS = ["cheap", "mid", "frontier"];
+// v1.19 acceptance oracles: command (exit code), test (named test), judge (LLM, free-text rubric).
+// A plain string is the read-old/write-new compat form — semantically a judge oracle (spec §2).
+export const ORACLES = ["command", "test", "judge"];
+// Typed acceptance oracle: command carries the thing to run, test the test name, judge free text.
+// Anything else (a typed object naming an unknown oracle) fails validation loudly here.
+export const AcceptanceItemSchema = z.union([
+    z.string().min(1),
+    z.object({ oracle: z.literal("command"), command: z.string().min(1) }),
+    z.object({ oracle: z.literal("test"), test: z.string().min(1) }),
+    z.object({ oracle: z.literal("judge"), text: z.string().min(1) }),
+]);
+// Shared text rendering of one acceptance item — every consumer (worker prompt, acceptance gate,
+// review gate) renders typed items as text through THIS helper. Rendering only; oracle execution is T2.
+export function renderAcceptanceItem(item) {
+    if (typeof item === "string")
+        return item;
+    if (item.oracle === "command")
+        return `$ ${item.command}`;
+    if (item.oracle === "test")
+        return `test: ${item.test}`;
+    return item.text; // judge — bare text, byte-identical to a plain-string judge criterion
+}
+export const TaskSchema = z.object({
+    // ids land in git branch names and herdr pane names — branch-safe characters only, bounded
+    // length (refs hit filesystem limits), and never "--" (the task-branch separator, locked
+    // decision 10) or a trailing dash. T1-style from prd/speckit; P07-01-style from gsd (v1.3).
+    id: z
+        .string()
+        .max(64)
+        .regex(/^[A-Za-z][A-Za-z0-9_-]*$/, "task ids look like T1 or P07-01 (letter start; letters/digits/-/_)")
+        .refine((id) => !id.includes("--") && !id.endsWith("-"), 'task ids may not contain "--" or end with "-"'),
+    title: z.string().min(1),
+    goal: z.string().min(1),
+    shape: z.enum(SHAPES),
+    complexity: z.number().int().min(1).max(10),
+    deps: z.array(z.string()).default([]),
+    files: z.array(z.string()).default([]),
+    context: z.array(z.string()).default([]),
+    acceptance: z.array(AcceptanceItemSchema).min(1, "acceptance[] is required and must be non-empty"),
+    // v1.19: purely advisory plan-time blast radius — NO gate reads this (the run-time scope gate stays
+    // authoritative fail-closed). Optional + best-effort: paths required, confidence/reason may be absent.
+    scopeHints: z
+        .array(z.object({
+        paths: z.array(z.string()),
+        confidence: z.number().min(0).max(1).optional(),
+        reason: z.string().optional(),
+    }))
+        .optional(),
+    gates: z.array(z.enum(GATE_NAMES)).default(["build", "test", "lint", "evidence", "scope", "acceptance", "review"]),
+    routingHints: z
+        .object({
+        pin: z.object({ via: z.string(), model: z.string() }).optional(),
+        floor: z.enum(TIERS).optional(),
+        source: z.string().optional(),
+        escalate: z.boolean().optional(),
+    })
+        .optional(),
+    humanGate: z.boolean().default(false),
+    status: z.enum(STATUSES).default("pending"),
+    evidence: z
+        .object({
+        commits: z.array(z.string()).default([]),
+        artifacts: z.array(z.string()).default([]),
+        gateResults: z.array(z.unknown()).default([]),
+    })
+        .default({ commits: [], artifacts: [], gateResults: [] }),
+});
+export const RunGraphSchema = z
+    .object({
+    version: z.literal(1),
+    spec: z.object({
+        source: z.enum(["speckit", "gsd", "prd", "native", "taskmaster"]),
+        paths: z.array(z.string()),
+        hash: z.string(),
+    }),
+    tasks: z.array(TaskSchema).min(1),
+})
+    .superRefine((g, ctx) => {
+    const ids = new Set();
+    for (const t of g.tasks) {
+        if (ids.has(t.id))
+            ctx.addIssue({ code: "custom", message: `duplicate task id ${t.id}` });
+        ids.add(t.id);
+    }
+    for (const t of g.tasks)
+        for (const d of t.deps)
+            if (!ids.has(d))
+                ctx.addIssue({ code: "custom", message: `${t.id} depends on unknown task ${d}` });
+    const cycle = findCycle(g.tasks);
+    if (cycle)
+        ctx.addIssue({ code: "custom", message: `dependency cycle: ${cycle.join(" -> ")}` });
+});
+export class GraphValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`invalid RunGraph:\n  - ${issues.join("\n  - ")}`);
+        this.issues = issues;
+        this.name = "GraphValidationError";
+    }
+}
+export function validateGraph(data) {
+    const r = RunGraphSchema.safeParse(data);
+    if (!r.success) {
+        throw new GraphValidationError(r.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`));
+    }
+    return r.data;
+}
+function findCycle(tasks) {
+    const deps = new Map(tasks.map((t) => [t.id, t.deps]));
+    const state = new Map();
+    const stack = [];
+    const visit = (id) => {
+        state.set(id, 1);
+        stack.push(id);
+        for (const d of deps.get(id) ?? []) {
+            if (state.get(d) === 1)
+                return [...stack.slice(stack.indexOf(d)), d];
+            if (!state.has(d) && deps.has(d)) {
+                const c = visit(d);
+                if (c)
+                    return c;
+            }
+        }
+        state.set(id, 2);
+        stack.pop();
+        return null;
+    };
+    for (const t of tasks) {
+        if (!state.has(t.id)) {
+            const c = visit(t.id);
+            if (c)
+                return c;
+        }
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.1.0";

package/dist/index.js

@@ -0,0 +1 @@
+export const VERSION = "0.1.0";

package/dist/plan/prompt.d.ts

@@ -0,0 +1,4 @@
+export declare function scopePrompt(intent: string, repair?: {
+    draft: string;
+    error: string;
+}): string;