novahiz 0.3.2 → 0.3.3

package/dist/graft.js

@@ -0,0 +1,257 @@
+/**
+ * Graft integration for Novahiz — version-controls the SQLite ledger.
+ *
+ * Provides: init, commit, log, diff, status, restore, isAvailable, isInitialized.
+ * Auto-commit is handled by calling `commitGraft()` from ledger operations.
+ */
+import { execFileSync } from "node:child_process";
+import { copyFileSync, existsSync } from "node:fs";
+import { isAbsolute, resolve, sep } from "node:path";
+import { NovahizHome } from "./spec.js";
+// ── Graft binary resolution ──────────────────────────────────────────────────
+// Graft is expected on PATH. If not found, we degrade gracefully (no-op).
+let _graftBinary = null; // null = not resolved yet, "" = resolved but absent
+function graftBinary() {
+    if (_graftBinary !== null)
+        return _graftBinary || null;
+    const override = process.env.NOVAHIZ_GRAFT_BIN;
+    if (override) {
+        const abs = resolve(override);
+        if (existsSync(abs)) {
+            _graftBinary = abs;
+            return abs;
+        }
+    }
+    const isWin = process.platform === "win32";
+    const names = isWin ? ["graft.cmd", "graft.exe", "graft"] : ["graft"];
+    const delimiter = isWin ? ";" : ":";
+    for (const raw of (process.env.PATH ?? "").split(delimiter)) {
+        const dir = raw.trim();
+        if (dir === "" || !isAbsolute(dir))
+            continue;
+        for (const name of names) {
+            const candidate = resolve(dir, name);
+            if (existsSync(candidate)) {
+                _graftBinary = candidate;
+                return candidate;
+            }
+        }
+    }
+    _graftBinary = "";
+    return null;
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function graftDir() {
+    return resolve(NovahizHome(), ".graft");
+}
+function ledgerPath() {
+    const envDb = process.env.NOVAHIZ_DB;
+    if (envDb)
+        return resolve(envDb);
+    // Default: novahiz.sqlite in the Novahiz home directory
+    return resolve(NovahizHome(), "novahiz.sqlite");
+}
+function runGraft(args, opts) {
+    const bin = graftBinary();
+    if (!bin)
+        throw new Error("graft not found on PATH (install @eidos.space/graft or set NOVAHIZ_GRAFT_BIN)");
+    const db = ledgerPath();
+    const fullArgs = ["--db", db, ...args];
+    try {
+        return execFileSync(bin, fullArgs, {
+            stdio: "pipe",
+            timeout: opts?.timeout ?? 30_000,
+            cwd: NovahizHome(),
+            encoding: "utf-8",
+        }).trim();
+    }
+    catch (err) {
+        const stderr = err instanceof Error && "stderr" in err ? String(err.stderr ?? "") : "";
+        const stdout = err instanceof Error && "stdout" in err ? String(err.stdout ?? "") : "";
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`graft ${args[0]} failed: ${stderr || stdout || message}`);
+    }
+}
+// ── Public API ───────────────────────────────────────────────────────────────
+/** Check if graft CLI is available on PATH. */
+export function isGraftAvailable() {
+    const bin = graftBinary();
+    if (!bin)
+        return false;
+    try {
+        execFileSync(bin, ["--version"], { stdio: "pipe", timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Check if .graft directory exists in the Novahiz home. */
+export function isGraftInitialized() {
+    return existsSync(graftDir());
+}
+/** Initialize a .graft repository in the Novahiz home directory. */
+export function initGraft() {
+    if (!isGraftAvailable()) {
+        return { success: false, message: "graft CLI not found on PATH" };
+    }
+    if (isGraftInitialized()) {
+        return { success: true, message: "graft already initialized" };
+    }
+    try {
+        // graft init creates .graft/ in cwd
+        const bin = graftBinary();
+        if (!bin)
+            return { success: false, message: "graft CLI not found on PATH" };
+        execFileSync(bin, ["init"], {
+            stdio: "pipe",
+            timeout: 10_000,
+            cwd: NovahizHome(),
+        });
+        // Configure user identity
+        try {
+            runGraft(["config", "set", "user.name", "Novahiz"]);
+            runGraft(["config", "set", "user.email", "Novahiz@local"]);
+        }
+        catch {
+            // non-critical
+        }
+        return { success: true, message: "graft initialized" };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { success: false, message: `init failed: ${message}` };
+    }
+}
+/**
+ * Stage and commit the ledger database.
+ * No-op if graft is not initialized or unavailable.
+ * Returns commit info or null if nothing to commit.
+ */
+export function commitGraft(message) {
+    if (!isGraftAvailable() || !isGraftInitialized())
+        return null;
+    const db = ledgerPath();
+    // Stage the database file (--force needed because .gitignore excludes *.sqlite)
+    try {
+        runGraft(["add", "--force", db]);
+    }
+    catch {
+        // may be no changes — graft add exits non-zero if nothing changed
+        return null;
+    }
+    // Commit
+    try {
+        const out = runGraft(["commit", "-m", message]);
+        // parse "[abc123] message"
+        const match = out.match(/^\[([a-f0-9]+)\]\s*(.*)/m);
+        if (match) {
+            return { hash: match[1], message: match[2] };
+        }
+        return { hash: "unknown", message };
+    }
+    catch {
+        return null;
+    }
+}
+/** Get commit log as an array of objects. */
+export function getGraftLog(limit = 20) {
+    if (!isGraftAvailable() || !isGraftInitialized())
+        return [];
+    try {
+        const out = runGraft(["log", "--json", `--limit=${limit}`]);
+        const data = JSON.parse(out);
+        // graft JSON output has `commits` array
+        const commits = data.commits ?? [];
+        return commits.map((entry) => ({
+            hash: (entry.id ?? "unknown").slice(0, 8),
+            date: entry.timestamp_ms ? new Date(entry.timestamp_ms).toISOString() : "",
+            message: entry.message ?? "",
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/** Get diff between current ledger and last committed version. */
+export function getGraftDiff() {
+    if (!isGraftAvailable() || !isGraftInitialized())
+        return "(graft not initialized)";
+    try {
+        return runGraft(["diff"]);
+    }
+    catch {
+        return "(no diff available)";
+    }
+}
+/** Get graft status output. */
+export function getGraftStatus() {
+    if (!isGraftAvailable() || !isGraftInitialized())
+        return "graft not initialized";
+    try {
+        return runGraft(["status"]);
+    }
+    catch {
+        return "status unavailable";
+    }
+}
+/** Restore the ledger to a specific revision. */
+export function restoreGraft(revision, opts) {
+    if (!isGraftAvailable() || !isGraftInitialized()) {
+        return { success: false, message: "graft not initialized" };
+    }
+    if (!opts?.force) {
+        return {
+            success: false,
+            message: "refuses to overwrite the ledger without --force; re-run as `novahiz graft restore <hash> --force` (a backup is written first)",
+        };
+    }
+    try {
+        const db = ledgerPath();
+        if (existsSync(db))
+            copyFileSync(db, `${db}.backup-${Date.now()}`);
+        runGraft(["checkout", revision]);
+        return { success: true, message: `restored to ${revision} (backup kept next to the ledger)` };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { success: false, message: `restore failed: ${message}` };
+    }
+}
+/** Export a snapshot of the ledger as a physical .sqlite file. */
+export function exportGraft(revision, outputPath, opts) {
+    if (!isGraftAvailable() || !isGraftInitialized()) {
+        return { success: false, message: "graft not initialized" };
+    }
+    const target = resolve(outputPath);
+    const allowed = [resolve(NovahizHome()), resolve(process.cwd())];
+    if (!allowed.some((r) => target === r || target.startsWith(r + sep))) {
+        return { success: false, message: `export path outside the workspace refused: ${outputPath}` };
+    }
+    if (existsSync(target) && !opts?.force) {
+        return { success: false, message: `export path already exists: ${target} (pass --force to overwrite)` };
+    }
+    try {
+        runGraft(["export", revision, "--output", target]);
+        return { success: true, message: `exported to ${target}` };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { success: false, message: `export failed: ${message}` };
+    }
+}
+// ── Auto-commit wrapper ──────────────────────────────────────────────────────
+/**
+ * Wraps a ledger operation with auto-commit.
+ * Call this after any significant write to the database.
+ * The commit message is generated from the operation type.
+ */
+export function autoCommit(operation, detail) {
+    const msg = detail ? `novahiz: ${operation} — ${detail}` : `novahiz: ${operation}`;
+    try {
+        commitGraft(msg);
+    }
+    catch {
+        // H12: auto-commit failures must never break the caller
+    }
+}

package/dist/ledger.js

@@ -0,0 +1,431 @@
+import { globToRegExp, isSafeRegexPattern } from "./gate.js";
+import { autoCommit } from "./graft.js";
+export const DEFAULT_MAX_ITERATIONS = 12;
+const DEFAULT_REVIEW_EDITS = 3;
+const DEFAULT_REVIEW_TODOS = 2;
+const SESSION_TTL_MS = 4 * 60 * 60 * 1000;
+function nowIso() {
+    return new Date().toISOString();
+}
+// H4: SESSION_TTL_MS was defined but never enforced — sessions accumulated
+// forever. pruneSessions deletes expired sessions and their orphaned rows.
+// Called from openDb on every startup (best effort, never throws).
+export function pruneSessions(db) {
+    const cutoff = new Date(Date.now() - SESSION_TTL_MS).toISOString();
+    db.exec("SAVEPOINT prune_sp");
+    try {
+        db.prepare("DELETE FROM skill_invocations WHERE session_id IN (SELECT id FROM sessions WHERE updated_at < ?)").run(cutoff);
+        db.prepare("DELETE FROM roadmap_progress WHERE session_id IN (SELECT id FROM sessions WHERE updated_at < ?)").run(cutoff);
+        db.prepare("DELETE FROM enforcement_log WHERE session_id IN (SELECT id FROM sessions WHERE updated_at < ?)").run(cutoff);
+        db.prepare("DELETE FROM sessions WHERE updated_at < ?").run(cutoff);
+        db.exec("RELEASE SAVEPOINT prune_sp");
+    }
+    catch (error) {
+        db.exec("ROLLBACK TO SAVEPOINT prune_sp");
+        throw error;
+    }
+}
+function genId(prefix) {
+    return `${prefix}_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+}
+function parseDeps(raw) {
+    try {
+        const parsed = JSON.parse(raw || "[]");
+        return Array.isArray(parsed) ? parsed.map(String) : [];
+    }
+    catch (error) {
+        console.warn(`[Novahiz] parseDeps: corrupted JSON ignored: ${error}`);
+        return [];
+    }
+}
+export function createTask(db, options) {
+    const taskId = options.id && options.id.trim().length > 0 ? options.id.trim() : genId("task");
+    const ts = nowIso();
+    // H5: ensure referenced session exists (auto-create if needed for FK compliance)
+    if (options.sessionId) {
+        db.prepare("INSERT OR IGNORE INTO sessions (id, categories, required_skills, updated_at) VALUES (?, '[]', '[]', ?)").run(options.sessionId, ts);
+    }
+    db.prepare("INSERT INTO tasks (id, title, status, session_id, created_at, updated_at) VALUES (?, ?, 'active', ?, ?, ?)").run(taskId, options.title, options.sessionId ?? null, ts, ts);
+    autoCommit("task-created", options.title);
+    return getTask(db, taskId);
+}
+export function getTask(db, id) {
+    const row = db.prepare("SELECT * FROM tasks WHERE id = ?").get(id);
+    return row ?? null;
+}
+// C6: Helper that throws a descriptive error instead of casting null as TaskRow.
+// Prevents silent null-dereference when a task ID doesn't exist.
+function requireTask(db, id) {
+    const task = getTask(db, id);
+    if (!task)
+        throw new Error(`task not found: ${id}`);
+    return task;
+}
+export function activeTask(db, sessionId) {
+    const row = sessionId
+        ? db.prepare("SELECT * FROM tasks WHERE status = 'active' AND session_id = ? ORDER BY created_at DESC LIMIT 1").get(sessionId)
+        : db.prepare("SELECT * FROM tasks WHERE status = 'active' ORDER BY created_at DESC LIMIT 1").get();
+    return row ?? null;
+}
+export function getTodo(db, id) {
+    const row = db.prepare("SELECT * FROM todos WHERE id = ?").get(id);
+    return row ?? null;
+}
+export function listTodos(db, taskId) {
+    return db.prepare("SELECT * FROM todos WHERE task_id = ? ORDER BY seq").all(taskId);
+}
+export function addTodos(db, taskId, items) {
+    const task = getTask(db, taskId);
+    if (!task)
+        throw new Error(`unknown task: ${taskId}`);
+    const insert = db.prepare("INSERT INTO todos (id, task_id, seq, label, kind, status, acceptance, proof, owner, depends_on, iterations, max_iterations, updated_at) VALUES (?, ?, COALESCE((SELECT MAX(seq) FROM todos WHERE task_id = ?), 0) + 1, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+    const ids = [];
+    db.exec("SAVEPOINT add_todos_sp");
+    try {
+        for (const item of items) {
+            const todoId = genId("todo");
+            insert.run(todoId, taskId, taskId, item.label, item.kind ?? "edit", item.status ?? "pending", item.acceptance ?? null, null, item.owner ?? null, JSON.stringify(item.dependsOn ?? []), 0, item.maxIterations ?? DEFAULT_MAX_ITERATIONS, nowIso());
+            ids.push(todoId);
+        }
+        reopenTask(db, taskId);
+        db.exec("RELEASE SAVEPOINT add_todos_sp");
+    }
+    catch (error) {
+        db.exec("ROLLBACK TO SAVEPOINT add_todos_sp");
+        throw error;
+    }
+    autoCommit("todos-added", `${items.length} item(s) to ${taskId}`);
+    return ids.map((id) => getTodo(db, id));
+}
+export function startTodo(db, id) {
+    const todo = getTodo(db, id);
+    if (!todo)
+        throw new Error(`unknown todo: ${id}`);
+    if (todo.status === "done")
+        throw new Error(`todo already done: ${id}`);
+    const unfinished = parseDeps(todo.depends_on).filter((dep) => {
+        const dependency = getTodo(db, dep);
+        return !dependency || (dependency.status !== "done" && dependency.status !== "dropped");
+    });
+    if (unfinished.length > 0) {
+        throw new Error(`todo ${id} is blocked by unfinished dependencies: ${unfinished.join(", ")}`);
+    }
+    const ts = nowIso();
+    const result = db.prepare("UPDATE todos SET iterations = iterations + 1, status = 'in_progress', updated_at = ? WHERE id = ? AND (max_iterations IS NULL OR iterations < max_iterations) RETURNING iterations, max_iterations").get(ts, id);
+    if (!result) {
+        throw new Error(`todo ${id} exceeded its iteration budget (${todo.max_iterations ?? DEFAULT_MAX_ITERATIONS})`);
+    }
+    return getTodo(db, id);
+}
+export function completeTodo(db, id, proof = "") {
+    const todo = getTodo(db, id);
+    if (!todo)
+        throw new Error(`unknown todo: ${id}`);
+    const trimmed = String(proof ?? "").trim();
+    if (todo.kind === "verify" && trimmed.length === 0) {
+        throw new Error(`todo ${id} is a verify step and needs proof (the command you ran and its result)`);
+    }
+    db.prepare("UPDATE todos SET status = 'done', proof = ?, updated_at = ? WHERE id = ?").run(trimmed.length > 0 ? trimmed : null, nowIso(), id);
+    maybeCompleteTask(db, todo.task_id);
+    autoCommit("todo-completed", id);
+    return getTodo(db, id);
+}
+export function blockTodo(db, id, reason = "") {
+    const todo = getTodo(db, id);
+    if (!todo)
+        throw new Error(`unknown todo: ${id}`);
+    // The todos table has no reason column, so the block reason travels in proof.
+    db.prepare("UPDATE todos SET status = 'blocked', proof = ?, updated_at = ? WHERE id = ?").run(String(reason ?? "").trim() || null, nowIso(), id);
+    return getTodo(db, id);
+}
+function maybeCompleteTask(db, taskId) {
+    const open = db.prepare("SELECT COUNT(*) AS count FROM todos WHERE task_id = ? AND status NOT IN ('done', 'dropped')").get(taskId);
+    if (open.count === 0) {
+        db.prepare("UPDATE tasks SET status = 'done', updated_at = ? WHERE id = ?").run(nowIso(), taskId);
+    }
+}
+function reopenTask(db, taskId) {
+    db.prepare("UPDATE tasks SET status = CASE WHEN status = 'done' THEN 'active' ELSE status END, updated_at = ? WHERE id = ?").run(nowIso(), taskId);
+}
+export function resume(db, sessionId) {
+    const task = activeTask(db, sessionId);
+    if (!task)
+        return { task: null, todos: [], current: null };
+    const todos = listTodos(db, task.id);
+    const current = todos.find((todo) => todo.status === "in_progress") ??
+        todos.find((todo) => todo.status === "pending") ??
+        null;
+    return { task, todos, current };
+}
+export function ownedBy(todo, filePath) {
+    const owner = (todo.owner ?? "").trim();
+    if (owner.length === 0)
+        return true;
+    const normalized = filePath.replace(/\\/g, "/");
+    return owner
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean)
+        // P2-C (LOW): owner globs come from todo labels; reject nested-quantifier
+        // shapes before compiling so a crafted owner cannot ReDoS every edit check.
+        .some((pattern) => isSafeRegexPattern(pattern) && globToRegExp(pattern).test(normalized));
+}
+export function traceCheck(db, options) {
+    if (!options.required)
+        return { required: false, ok: true, todo: null, reason: "" };
+    const state = resume(db, options.sessionId);
+    const inProgress = state.todos.filter((todo) => todo.status === "in_progress");
+    const match = inProgress.find((todo) => ownedBy(todo, options.filePath));
+    if (match)
+        return { required: true, ok: true, todo: match, reason: "" };
+    const reason = inProgress.length === 0
+        ? "no todo is in progress. Start one with `novahiz task start --id <todo>` before editing."
+        : `no in-progress todo owns ${options.filePath}. Active todos own: ${inProgress.map((todo) => todo.owner || "(any file)").join("; ")}`;
+    return { required: true, ok: false, todo: null, reason };
+}
+export function buildWorkPackets(db, taskId) {
+    const task = getTask(db, taskId);
+    if (!task)
+        throw new Error(`unknown task: ${taskId}`);
+    return listTodos(db, taskId)
+        .filter((todo) => todo.status === "pending" || todo.status === "in_progress")
+        .map((todo) => ({
+        todo: todo.id,
+        label: todo.label,
+        objective: todo.acceptance ?? todo.label,
+        kind: todo.kind,
+        files: (todo.owner ?? "")
+            .split(",")
+            .map((part) => part.trim())
+            .filter(Boolean),
+        acceptance: todo.acceptance,
+        budget: todo.max_iterations,
+        dependsOn: parseDeps(todo.depends_on)
+    }));
+}
+export function amendTodo(db, id, patch) {
+    const todo = getTodo(db, id);
+    if (!todo)
+        throw new Error(`unknown todo: ${id}`);
+    if (todo.status === "done" || todo.status === "dropped")
+        throw new Error(`cannot amend a ${todo.status} todo: ${id}`);
+    const label = patch.label ?? todo.label;
+    const kind = patch.kind ?? todo.kind;
+    const acceptance = patch.acceptance === undefined ? todo.acceptance : patch.acceptance;
+    const owner = patch.owner === undefined ? todo.owner : patch.owner;
+    const dependsOn = patch.dependsOn === undefined ? todo.depends_on : JSON.stringify(patch.dependsOn);
+    const maxIterations = patch.maxIterations === undefined ? todo.max_iterations : patch.maxIterations;
+    if (maxIterations !== null && maxIterations !== undefined && (!Number.isInteger(maxIterations) || maxIterations <= 0)) {
+        throw new Error(`maxIterations must be a positive integer, got: ${maxIterations}`);
+    }
+    db.prepare("UPDATE todos SET label = ?, kind = ?, acceptance = ?, owner = ?, depends_on = ?, max_iterations = ?, updated_at = ? WHERE id = ?").run(label, kind, acceptance, owner, dependsOn, maxIterations, nowIso(), id);
+    return getTodo(db, id);
+}
+export function reorderTodos(db, taskId, orderedIds) {
+    const todos = listTodos(db, taskId);
+    const existing = new Set(todos.map((todo) => todo.id));
+    if (orderedIds.length !== todos.length || new Set(orderedIds).size !== orderedIds.length || orderedIds.some((id) => !existing.has(id))) {
+        throw new Error(`reorder must list each todo of task ${taskId} exactly once`);
+    }
+    const update = db.prepare("UPDATE todos SET seq = ?, updated_at = ? WHERE id = ?");
+    const ts = nowIso();
+    orderedIds.forEach((id, index) => update.run(index + 1, ts, id));
+    db.prepare("UPDATE tasks SET updated_at = ? WHERE id = ?").run(ts, taskId);
+    return listTodos(db, taskId);
+}
+export function insertTodo(db, taskId, item, position) {
+    // M-Ledger: wrap insert + reorder in a savepoint so a reorder failure doesn't
+    // leave a half-inserted todo visible.
+    db.exec("SAVEPOINT insert_sp");
+    try {
+        const created = addTodos(db, taskId, [item])[0];
+        if (position === undefined || position === "end") {
+            db.exec("RELEASE SAVEPOINT insert_sp");
+            return created;
+        }
+        const others = listTodos(db, taskId).filter((todo) => todo.id !== created.id);
+        let orderedIds;
+        if (position === "start") {
+            orderedIds = [created.id, ...others.map((todo) => todo.id)];
+        }
+        else {
+            orderedIds = [
+                ...others.filter((todo) => todo.seq <= position).map((todo) => todo.id),
+                created.id,
+                ...others.filter((todo) => todo.seq > position).map((todo) => todo.id)
+            ];
+        }
+        reorderTodos(db, taskId, orderedIds);
+        db.exec("RELEASE SAVEPOINT insert_sp");
+        return getTodo(db, created.id);
+    }
+    catch (error) {
+        db.exec("ROLLBACK TO SAVEPOINT insert_sp");
+        db.exec("RELEASE SAVEPOINT insert_sp");
+        throw error;
+    }
+}
+export function dropTodo(db, id, reason = "") {
+    const todo = getTodo(db, id);
+    if (!todo)
+        throw new Error(`unknown todo: ${id}`);
+    db.prepare("UPDATE todos SET status = 'dropped', proof = ?, updated_at = ? WHERE id = ?").run(String(reason ?? "").trim() || null, nowIso(), id);
+    maybeCompleteTask(db, todo.task_id);
+    autoCommit("todo-dropped", id);
+    return getTodo(db, id);
+}
+export function dropTask(db, id, reason = "") {
+    const task = requireTask(db, id);
+    const trimmed = String(reason ?? "").trim();
+    // Active tasks may only be abandoned with an explicit reason (cleanup /
+    // superseded work). Finished tasks can be dropped without one.
+    if (task.status === "active" && trimmed.length === 0) {
+        throw new Error(`refusing to abandon active task ${id} without a reason; pass --reason (or finish the task first)`);
+    }
+    try {
+        db.exec("SAVEPOINT drop_task_sp");
+        db.prepare("UPDATE todos SET status = 'dropped', proof = ?, updated_at = ? WHERE task_id = ? AND status NOT IN ('done', 'dropped')").run(trimmed || null, nowIso(), id);
+        db.prepare("UPDATE tasks SET status = 'abandoned', updated_at = ? WHERE id = ?").run(nowIso(), id);
+        db.exec("RELEASE SAVEPOINT drop_task_sp");
+    }
+    catch (error) {
+        db.exec("ROLLBACK TO SAVEPOINT drop_task_sp");
+        throw error;
+    }
+    autoCommit("task-abandoned", trimmed ? `${id}: ${trimmed}` : id);
+    return requireTask(db, id);
+}
+export function recordEdit(db, taskId) {
+    const result = db.prepare("UPDATE tasks SET edits_since_review = edits_since_review + 1, updated_at = ? WHERE id = ? RETURNING edits_since_review").get(nowIso(), taskId);
+    if (!result)
+        throw new Error(`task not found: ${taskId}`);
+    return result.edits_since_review;
+}
+export function recordTodoDone(db, taskId) {
+    db.prepare("UPDATE tasks SET todos_since_review = todos_since_review + 1, updated_at = ? WHERE id = ?").run(nowIso(), taskId);
+    return requireTask(db, taskId).todos_since_review;
+}
+export function reviewDue(db, taskId, policy = { edits: DEFAULT_REVIEW_EDITS, todos: DEFAULT_REVIEW_TODOS }) {
+    const task = getTask(db, taskId);
+    if (!task)
+        throw new Error(`unknown task: ${taskId}`);
+    const due = task.edits_since_review >= policy.edits || task.todos_since_review >= policy.todos;
+    const reason = due
+        ? `plan review due (${task.edits_since_review} edits, ${task.todos_since_review} todos since last review; cadence ${policy.edits} edits / ${policy.todos} todos). Reconcile with \`novahiz task review\`.`
+        : "";
+    return { due, edits: task.edits_since_review, todos: task.todos_since_review, policy, reason };
+}
+/**
+ * Which gate targets a due plan review should block.
+ * Only paths owned by an open todo with a non-empty owner pattern are blocked.
+ * Empty owners and tasks with no owned open todos never expand the block set,
+ * so a due review no longer freezes the whole gate.
+ */
+export function reviewBlockReason(db, taskId, filePath, policy) {
+    const due = reviewDue(db, taskId, policy);
+    if (!due.due)
+        return null;
+    const openOwned = listTodos(db, taskId).filter((todo) => (todo.status === "pending" || todo.status === "in_progress") && (todo.owner ?? "").trim().length > 0);
+    if (openOwned.length === 0)
+        return null;
+    return openOwned.some((todo) => ownedBy(todo, filePath)) ? due.reason : null;
+}
+export function revisionSignals(db, taskId) {
+    const todos = listTodos(db, taskId);
+    const signals = [];
+    const inProgress = todos.filter((todo) => todo.status === "in_progress");
+    if (inProgress.length > 1) {
+        signals.push({ type: "parallel", todo: null, detail: `${inProgress.length} todos are in progress at once; keep a single active step.` });
+    }
+    for (const todo of todos) {
+        if (todo.status === "blocked") {
+            signals.push({ type: "blocked", todo: todo.id, detail: `${todo.label} is blocked: ${todo.proof ?? "no reason given"}` });
+        }
+        if (todo.status === "in_progress" || todo.status === "pending") {
+            const max = todo.max_iterations ?? DEFAULT_MAX_ITERATIONS;
+            if (todo.iterations >= max) {
+                signals.push({ type: "budget", todo: todo.id, detail: `${todo.label} hit its iteration budget (${todo.iterations}/${max}); split, drop, or re-scope it.` });
+            }
+            if (todo.kind === "edit" && !todo.acceptance) {
+                signals.push({ type: "missing_acceptance", todo: todo.id, detail: `${todo.label} has no acceptance criterion.` });
+            }
+            if (!todo.owner) {
+                signals.push({ type: "unowned", todo: todo.id, detail: `${todo.label} owns no file; a parallel agent could collide.` });
+            }
+        }
+    }
+    const settled = new Set(todos.filter((todo) => todo.status === "done" || todo.status === "dropped").map((todo) => todo.id));
+    for (const todo of todos) {
+        if (todo.status !== "pending")
+            continue;
+        const deps = parseDeps(todo.depends_on);
+        if (deps.length > 0 && deps.every((dep) => settled.has(dep))) {
+            signals.push({ type: "ready", todo: todo.id, detail: `${todo.label} has no unfinished dependencies.` });
+        }
+    }
+    return signals;
+}
+export function reviewTask(db, options) {
+    const task = getTask(db, options.taskId);
+    if (!task)
+        throw new Error(`unknown task: ${options.taskId}`);
+    const additions = options.additions ?? [];
+    const amendments = options.amendments ?? [];
+    const removals = options.removals ?? [];
+    db.exec("BEGIN");
+    try {
+        for (const item of removals) {
+            const id = typeof item === "string" ? item : item.id;
+            const reason = typeof item === "string" ? "" : item.reason ?? "";
+            const target = getTodo(db, id);
+            if (!target || target.task_id !== options.taskId) {
+                throw new Error(`review removal targets a todo outside this task: ${id}`);
+            }
+            dropTodo(db, id, reason);
+        }
+        for (const change of amendments) {
+            const { id, ...patch } = change;
+            const target = getTodo(db, id);
+            if (!target || target.task_id !== options.taskId) {
+                throw new Error(`review amendment targets a todo outside this task: ${id}`);
+            }
+            amendTodo(db, id, patch);
+        }
+        for (const item of additions)
+            insertTodo(db, options.taskId, item, "end");
+        if (options.order)
+            reorderTodos(db, options.taskId, options.order);
+        const revision = task.revision + 1;
+        const ts = nowIso();
+        db.prepare("UPDATE tasks SET revision = ?, reviewed_at = ?, edits_since_review = 0, todos_since_review = 0, updated_at = ? WHERE id = ?").run(revision, ts, ts, options.taskId);
+        db.exec("COMMIT");
+        const result = {
+            task: requireTask(db, options.taskId),
+            revision,
+            applied: { additions: additions.length, amendments: amendments.length, removals: removals.length, reordered: Boolean(options.order) },
+            signals: revisionSignals(db, options.taskId)
+        };
+        autoCommit("task-reviewed", `revision ${revision}`);
+        return result;
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}
+export function ledgerSummary(state) {
+    if (!state.task)
+        return [];
+    const done = state.todos.filter((todo) => todo.status === "done").length;
+    const lines = [`Ledger ${state.task.id}: ${state.task.title} (${done}/${state.todos.length} done)`];
+    for (const todo of state.todos) {
+        const flag = todo.status === "in_progress" ? ">" : todo.status === "done" ? "x" : todo.status === "blocked" ? "!" : todo.status === "dropped" ? "-" : " ";
+        const proof = todo.proof ? ` | proof: ${todo.proof}` : "";
+        lines.push(`  [${flag}] ${todo.seq}. ${todo.label}${proof}`);
+    }
+    if (state.current) {
+        const max = state.current.max_iterations ?? DEFAULT_MAX_ITERATIONS;
+        lines.push(`  next: ${state.current.label} (budget ${state.current.iterations}/${max})`);
+    }
+    return lines;
+}