novahiz 0.1.0

package/src/commands/inspect.ts

@@ -0,0 +1,296 @@
+import { join } from "node:path";
+import { asString, dbPathFor, numberFlag, print, safeJsonArray, type Parsed } from "./context.ts";
+import { loadSpec, novahizHome } from "../spec.ts";
+import { getMeta, openDb, setMeta } from "../db.ts";
+import { loadCatalog, loadInstalledSkills, persistCatalog, scanSkills, writeCatalog, writeSkillIndex } from "../catalog.ts";
+import { rankSkills } from "../relevance.ts";
+import { buildMcpEntries, enabledProviders, installCommands } from "../providers.ts";
+import { bootstrapFor, checkDependencies, missingPrerequisites } from "../deps.ts";
+import { classify } from "../classify.ts";
+import { runCommand, runScript } from "../exec.ts";
+import { activeTask, buildWorkPackets, getTask } from "../ledger.ts";
+
+export function commandCheck(): void {
+  const root = novahizHome();
+  const spec = loadSpec(root);
+  const index = loadInstalledSkills(spec);
+  const db = openDb(dbPathFor(root, spec));
+  const lastSync = getMeta(db, "last_sync");
+  db.close();
+  print({
+    home: root,
+    categories: spec.categories.length,
+    rules: spec.rules.length,
+    skillRoots: spec.config.skillRoots.length,
+    installedSkills: index.skills.size,
+    indexAvailable: index.available,
+    lastSync,
+    gate: spec.config.gate,
+    classify: spec.config.classify
+  });
+}
+
+export function commandSync(): void {
+  const root = novahizHome();
+  const spec = loadSpec(root);
+  const scanErrors: string[] = [];
+  const skills = scanSkills(spec, scanErrors);
+  const indexFile = writeSkillIndex(spec, skills);
+  const catalogFile = writeCatalog(spec, skills);
+  const db = openDb(dbPathFor(root, spec));
+  persistCatalog(db, spec, skills);
+  const lastSync = new Date().toISOString();
+  setMeta(db, "last_sync", lastSync);
+  db.close();
+  print({ root, scanned: skills.length, index: indexFile, catalog: catalogFile, lastSync, scanErrors });
+}
+
+export function commandClassify(parsed: Parsed): void {
+  const root = novahizHome();
+  const spec = loadSpec(root);
+  const text = (parsed.positionals.slice(1).join(" ") || asString(parsed.flags.text)).trim();
+  if (text.length === 0) {
+    throw new Error("classify needs a prompt: pass it as an argument or with --text");
+  }
+  const result = classify(spec, text, {
+    minScore: numberFlag(parsed, "min-score", { min: 0 }),
+    maxCategories: numberFlag(parsed, "max-categories", { min: 1, integer: true })
+  });
+  print({ prompt: text, ...result });
+}
+
+
+export function commandSkills(parsed: Parsed): void {
+  const root = novahizHome();
+  const spec = loadSpec(root);
+  const db = openDb(dbPathFor(root, spec));
+  const rows = db.prepare("SELECT id, name, power, stars, tags, categories FROM skills ORDER BY power DESC, id ASC").all() as {
+    id: string;
+    name: string;
+    power: number;
+    stars: number | null;
+    tags: string;
+    categories: string;
+  }[];
+  db.close();
+  const category = asString(parsed.flags.category);
+  const filtered = category.length > 0 ? rows.filter((row) => safeJsonArray(row.categories).includes(category)) : rows;
+  print(
+    filtered.map((row) => ({
+      id: row.id,
+      name: row.name,
+      power: row.power,
+      stars: row.stars,
+      tags: safeJsonArray(row.tags),
+      categories: safeJsonArray(row.categories)
+    }))
+  );
+}
+
+export function commandCategories(): void {
+  print(loadSpec().categories);
+}
+
+export function commandRules(): void {
+  print(loadSpec().rules);
+}
+
+export function commandSessionLoad(parsed: Parsed): void {
+  const root = novahizHome();
+  const spec = loadSpec(root);
+  const session = asString(parsed.flags.session);
+  const skill = asString(parsed.flags.skill);
+  if (session.length === 0 || skill.length === 0) {
+    print({ error: "session-load requires --session and --skill" });
+    process.exitCode = 1;
+    return;
+  }
+  const db = openDb(dbPathFor(root, spec));
+  db.prepare("INSERT OR IGNORE INTO skill_invocations (session_id, skill, invoked_at) VALUES (?, ?, ?)").run(
+    session,
+    skill,
+    new Date().toISOString()
+  );
+  db.close();
+  print({ session, loaded: skill });
+}
+
+export function commandSessionState(parsed: Parsed): void {
+  const root = novahizHome();
+  const spec = loadSpec(root);
+  const session = asString(parsed.flags.session);
+  const db = openDb(dbPathFor(root, spec));
+  const loaded = (db.prepare("SELECT skill FROM skill_invocations WHERE session_id = ?").all(session) as { skill: string }[]).map(
+    (row) => row.skill
+  );
+  const state = db.prepare("SELECT categories, required_skills FROM sessions WHERE id = ?").get(session) as
+    | { categories: string; required_skills: string }
+    | undefined;
+  db.close();
+  print({ session, loaded, categories: state ? safeJsonArray(state.categories) : [], requiredSkills: state ? safeJsonArray(state.required_skills) : [] });
+}
+
+
+export function commandCatalog(parsed: Parsed): void {
+  const spec = loadSpec();
+  const query = parsed.positionals.slice(1).join(" ") || asString(parsed.flags.query);
+  const limitRaw = numberFlag(parsed, "limit", { min: 1, integer: true });
+  const limit = limitRaw !== undefined && limitRaw > 0 ? limitRaw : 10;
+  const catalog = loadCatalog(spec);
+  const results = rankSkills(catalog, query, limit);
+  const hint = catalog.length === 0 ? "catalog is empty; run `novahiz sync` to build it" : undefined;
+  print({ query, total: catalog.length, results, ...(hint ? { hint } : {}) });
+}
+
+export function commandRoadmap(parsed: Parsed): void {
+  const spec = loadSpec();
+  const categoryId = asString(parsed.flags.category);
+  const query = parsed.positionals.slice(1).join(" ") || asString(parsed.flags.query);
+  let category = categoryId ? spec.categories.find((entry) => entry.id === categoryId) : undefined;
+  if (!category && query.length > 0) {
+    const result = classify(spec, query);
+    category = spec.categories.find((entry) => entry.id === result.primary);
+  }
+  if (!category) {
+    print({ error: "roadmap requires --category <id> or a query" });
+    process.exitCode = 1;
+    return;
+  }
+  print({ category: category.id, roadmap: category.roadmap ?? null });
+}
+
+export function commandStep(parsed: Parsed): void {
+  const root = novahizHome();
+  const spec = loadSpec(root);
+  const session = asString(parsed.flags.session);
+  const done = asString(parsed.flags.done);
+  if (session.length === 0) {
+    print({ error: "step requires --session <id>" });
+    process.exitCode = 1;
+    return;
+  }
+  const db = openDb(dbPathFor(root, spec));
+  if (done.length > 0) {
+    db.prepare(
+      "INSERT INTO roadmap_progress (session_id, step_id, status, updated_at) VALUES (?, ?, 'done', ?) ON CONFLICT(session_id, step_id) DO UPDATE SET status = 'done', updated_at = excluded.updated_at"
+    ).run(session, done, new Date().toISOString());
+  }
+  const steps = db.prepare("SELECT step_id, status, updated_at FROM roadmap_progress WHERE session_id = ? ORDER BY updated_at").all(session);
+  db.close();
+  print({ session, steps });
+}
+
+export function commandProviders(parsed: Parsed): void {
+  const spec = loadSpec();
+  if (parsed.flags["mcp-json"]) {
+    print(buildMcpEntries(spec));
+    return;
+  }
+  if (parsed.flags.install) {
+    const results: Record<string, unknown>[] = [];
+    for (const entry of installCommands(spec)) {
+      const [command, ...args] = entry.command;
+      const result = runCommand(command, args);
+      process.stdout.write(`${result.ok ? "ok  " : "fail"} ${entry.id} (${entry.kind}) ${entry.command.join(" ")}\n`);
+      if (!result.ok && result.stderr) process.stderr.write(result.stderr);
+      results.push({ id: entry.id, kind: entry.kind, source: entry.source, command: entry.command.join(" "), ok: result.ok, error: result.error ?? null });
+    }
+    print(results);
+    return;
+  }
+  const category = asString(parsed.flags.category);
+  const query = parsed.positionals.slice(1).join(" ") || asString(parsed.flags.query);
+  let list = spec.providers;
+  if (category.length > 0) {
+    list = list.filter((provider) => (provider.categories ?? []).includes(category));
+  } else if (query.length > 0) {
+    const ids = new Set(classify(spec, query).providers);
+    list = list.filter((provider) => ids.has(provider.id));
+  }
+  const enabled = new Set(enabledProviders(spec).map((provider) => provider.id));
+  print(
+    list.map((provider) => ({
+      id: provider.id,
+      label: provider.label,
+      kind: provider.kind,
+      transport: provider.transport ?? null,
+      purpose: provider.purpose ?? "",
+      categories: provider.categories ?? [],
+      source: provider.source ?? "",
+      enabled: enabled.has(provider.id)
+    }))
+  );
+}
+
+export function commandDeps(parsed: Parsed): void {
+  const spec = loadSpec();
+  const status = checkDependencies(spec);
+  if (!parsed.flags.install) {
+    print({ node: process.version, platform: process.platform, dependencies: status });
+    return;
+  }
+
+  const run = (command: string[], label: string): boolean => {
+    const [bin, ...args] = command;
+    const result = runCommand(bin, args);
+    process.stdout.write(`${result.ok ? "ok  " : "fail"} ${label}\n`);
+    if (!result.ok && result.stderr) process.stderr.write(result.stderr);
+    if (result.error) process.stderr.write(`${result.error}\n`);
+    return result.ok;
+  };
+
+  const runBootstrap = (argv: string[], label: string): boolean => {
+    const result = runScript(argv);
+    process.stdout.write(`${result.ok ? "ok  " : "fail"} ${label}\n`);
+    if (!result.ok && result.stderr) process.stderr.write(result.stderr);
+    if (result.error) process.stderr.write(`${result.error}\n`);
+    return result.ok;
+  };
+
+  const results: Record<string, unknown>[] = [];
+  for (const entry of missingPrerequisites(spec)) {
+    const bootstrap = bootstrapFor(entry.provider);
+    if (!bootstrap || bootstrap.length === 0) {
+      results.push({ provider: entry.provider.id, step: "bootstrap", ok: false, note: `missing ${entry.missing.join(", ")}` });
+      continue;
+    }
+    results.push({ provider: entry.provider.id, step: "bootstrap", command: bootstrap.join(" "), ok: runBootstrap(bootstrap, `bootstrap ${entry.provider.id}`) });
+  }
+  for (const entry of installCommands(spec)) {
+    results.push({ provider: entry.id, step: "install", command: entry.command.join(" "), ok: run(entry.command, `install ${entry.id}`) });
+  }
+  print(results);
+}
+
+
+export function commandDispatch(parsed: Parsed): void {
+  const root = novahizHome();
+  const spec = loadSpec(root);
+  const session = asString(parsed.flags.session);
+  const db = openDb(dbPathFor(root, spec));
+  try {
+    const taskId = asString(parsed.flags.task) || activeTask(db, session || undefined)?.id;
+    if (!taskId) {
+      print({ error: "dispatch requires --task or an active task" });
+      process.exitCode = 1;
+      return;
+    }
+    const packets = buildWorkPackets(db, taskId);
+    const ownership = new Map<string, string[]>();
+    for (const packet of packets) {
+      for (const file of packet.files) {
+        ownership.set(file, [...(ownership.get(file) ?? []), packet.todo]);
+      }
+    }
+    const conflicts = [...ownership.entries()]
+      .filter(([, owners]) => owners.length > 1)
+      .map(([file, owners]) => ({ file, todos: owners }));
+    print({ task: getTask(db, taskId), packets, conflicts });
+  } catch (error) {
+    print({ error: String((error as Error)?.message ?? error) });
+    process.exitCode = 1;
+  } finally {
+    db.close();
+  }
+}
+

package/src/commands/report.ts

@@ -0,0 +1,85 @@
+import { join } from "node:path";
+import { asString, dbPathFor, emit, parse, type Parsed } from "./context.ts";
+import { loadSpec, novahizHome } from "../spec.ts";
+import { openDb } from "../db.ts";
+import * as ui from "../render.ts";
+
+export function commandReport(parsed: Parsed): void {
+  const root = novahizHome();
+  const spec = loadSpec(root);
+  const db = openDb(dbPathFor(root, spec));
+  const total = (db.prepare("SELECT COUNT(*) AS n FROM enforcement_log").get() as { n: number }).n;
+  const decisions = db.prepare("SELECT decision, COUNT(*) AS n FROM enforcement_log GROUP BY decision").all();
+  const byTool = db.prepare("SELECT tool, COUNT(*) AS n FROM enforcement_log GROUP BY tool ORDER BY n DESC").all();
+  const byClass = db.prepare("SELECT file_class, COUNT(*) AS n FROM enforcement_log GROUP BY file_class ORDER BY n DESC").all();
+  const missingRows = db.prepare("SELECT missing FROM enforcement_log").all() as { missing: string }[];
+  const invocations = (db.prepare("SELECT COUNT(*) AS n FROM skill_invocations").get() as { n: number }).n;
+  const topSkills = db.prepare("SELECT skill, COUNT(*) AS n FROM skill_invocations GROUP BY skill ORDER BY n DESC LIMIT 10").all();
+  const roadmapDone = (db.prepare("SELECT COUNT(*) AS n FROM roadmap_progress").get() as { n: number }).n;
+  const roadmapBySession = db.prepare("SELECT session_id, COUNT(*) AS n FROM roadmap_progress GROUP BY session_id ORDER BY n DESC LIMIT 10").all();
+  db.close();
+
+  const counts: Record<string, number> = {};
+  for (const row of missingRows) {
+    let list: string[] = [];
+    try {
+      list = JSON.parse(row.missing) as string[];
+    } catch {
+      list = [];
+    }
+    for (const skill of list) counts[skill] = (counts[skill] ?? 0) + 1;
+  }
+  const topMissing = Object.entries(counts)
+    .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))
+    .slice(0, 10)
+    .map(([skill, n]) => ({ skill, n }));
+
+  const report = { total, invocations, roadmapDone, providers: spec.providers.map((provider) => provider.id), decisions, byTool, byClass, topMissing, topSkills, roadmapBySession };
+
+  if (asString(parsed.flags.format) === "markdown") {
+    const lines = [
+      "# Novahiz report",
+      "",
+      `Enforcement entries: ${total}`,
+      `Skill invocations: ${invocations}`,
+      `Roadmap steps done: ${roadmapDone}`,
+      "",
+      "## Decisions",
+      ...decisions.map((row) => `- ${(row as { decision: string }).decision}: ${(row as { n: number }).n}`),
+      "",
+      "## Top missing skills",
+      ...topMissing.map((entry) => `- ${entry.skill}: ${entry.n}`),
+      "",
+      "## Top loaded skills",
+      ...topSkills.map((row) => `- ${(row as { skill: string }).skill}: ${(row as { n: number }).n}`),
+      ""
+    ];
+    process.stdout.write(`${lines.join("\n")}\n`);
+    return;
+  }
+
+  emit(parsed, report, () =>
+    [
+      ui.heading("Novahiz report"),
+      ui.kv([
+        ["Journal d'enforcement", String(total)],
+        ["Invocations de skills", String(invocations)],
+        ["Etapes de roadmap faites", String(roadmapDone)],
+        ["Providers", String(spec.providers.length)]
+      ]),
+      "",
+      ui.heading("Decisions"),
+      ui.table(["decision", "n"], decisions.map((row) => [(row as { decision: string }).decision, String((row as { n: number }).n)])),
+      "",
+      ui.heading("Outils"),
+      ui.table(["outil", "n"], byTool.map((row) => [String((row as { tool: string }).tool), String((row as { n: number }).n)])),
+      "",
+      ui.heading("Skills les plus attendues"),
+      ui.table(["skill", "n"], topMissing.map((entry) => [entry.skill, String(entry.n)])),
+      "",
+      ui.heading("Skills les plus chargees"),
+      ui.table(["skill", "n"], topSkills.map((row) => [(row as { skill: string }).skill, String((row as { n: number }).n)]))
+    ].join("\n")
+  );
+}
+

package/src/commands/task.ts

@@ -0,0 +1,310 @@
+import { join } from "node:path";
+import { asString, dbPathFor, numberFlag, parse, print, readStdin, splitList, type Parsed } from "./context.ts";
+import { loadSpec, novahizHome } from "../spec.ts";
+import { openDb } from "../db.ts";
+import { activeTask, addTodos, amendTodo, blockTodo, completeTodo, createTask, dropTodo, getTask, getTodo, insertTodo, ledgerSummary, recordTodoDone, reorderTodos, resume, reviewDue, reviewTask, revisionSignals, startTodo, type ReviewDiff, type TodoAmendment, type TodoInput, type TodoKind } from "../ledger.ts";
+
+export function normalizeTodoInput(item: unknown): TodoInput {
+  const record = (item ?? {}) as Record<string, unknown>;
+  const owners = Array.isArray(record.owner)
+    ? record.owner.map(String)
+    : typeof record.owner === "string"
+      ? record.owner.split(",").map((part) => part.trim()).filter(Boolean)
+      : [];
+  const dependsRaw = record.dependsOn ?? record.depends_on;
+  const dependsOn = Array.isArray(dependsRaw) ? dependsRaw.map(String) : [];
+  const maxIterations = Number(record.maxIterations ?? record.max_iterations);
+  return {
+    label: String(record.label ?? record.title ?? "").trim(),
+    kind: (record.kind ? String(record.kind) : "edit") as TodoKind,
+    acceptance: record.acceptance ? String(record.acceptance) : undefined,
+    owner: owners.length > 0 ? owners.join(",") : undefined,
+    dependsOn,
+    maxIterations: Number.isFinite(maxIterations) && maxIterations > 0 ? maxIterations : undefined
+  };
+}
+
+export function commandTask(parsed: Parsed): void {
+  const root = novahizHome();
+  const spec = loadSpec(root);
+  const action = parsed.positionals[1] ?? "status";
+  const session = asString(parsed.flags.session);
+  const db = openDb(dbPathFor(root, spec));
+  try {
+    if (action === "new") return taskNew(parsed, db, session, spec);
+
+    if (action === "plan") return taskPlan(parsed, db, session, spec);
+
+    if (action === "todo") return taskTodo(parsed, db, session, spec);
+
+    const id = asString(parsed.flags.id) || parsed.positionals[2] || "";
+    if (action === "start") return taskStart(parsed, db, session, spec);
+    if (action === "done") return taskDone(parsed, db, session, spec);
+    if (action === "block") return taskBlock(parsed, db, session, spec);
+
+    if (action === "signals") return taskSignals(parsed, db, session, spec);
+
+    if (action === "review") return taskReview(parsed, db, session, spec);
+
+    if (action === "amend") return taskAmend(parsed, db, session, spec);
+
+    if (action === "insert") return taskInsert(parsed, db, session, spec);
+
+    if (action === "drop") return taskDrop(parsed, db, session, spec);
+
+    if (action === "reorder") return taskReorder(parsed, db, session, spec);
+
+    if (action === "read") return taskRead(parsed, db, session, spec);
+
+    print({ error: `unknown task action: ${action}`, actions: ["new", "plan", "todo", "start", "done", "block", "review", "amend", "insert", "drop", "reorder", "signals", "status", "resume", "current"] });
+    process.exitCode = 1;
+  } catch (error) {
+    print({ error: String((error as Error)?.message ?? error) });
+    process.exitCode = 1;
+  } finally {
+    db.close();
+  }
+
+}
+
+function taskRead(parsed: Parsed, db: ReturnType<typeof openDb>, session: string, spec: ReturnType<typeof loadSpec>): void {
+  const id = asString(parsed.flags.id) || parsed.positionals[2] || "";
+  const state = resume(db, session || undefined);
+  const summary = ledgerSummary(state);
+  let review = null as ReturnType<typeof reviewDue> | null;
+  const signals = state.task ? revisionSignals(db, state.task.id) : [];
+  if (state.task && spec.config.ledger?.enabled !== false) {
+    review = reviewDue(db, state.task.id, spec.config.ledger.review);
+    summary.push(
+      `  review: ${review.due ? "DUE" : "ok"} (edits ${review.edits}/${review.policy.edits}, todos ${review.todos}/${review.policy.todos})`
+    );
+    if (review.due) summary.push(`  -> reconcile with: novahiz task review --task ${state.task.id} --reason "<what changed>"`);
+    for (const signal of signals) summary.push(`  signal ${signal.type}: ${signal.detail}`);
+  }
+  print({ ...state, summary, review, signals });
+  return;
+    }
+
+function taskReorder(parsed: Parsed, db: ReturnType<typeof openDb>, session: string, spec: ReturnType<typeof loadSpec>): void {
+  const id = asString(parsed.flags.id) || parsed.positionals[2] || "";
+  const taskId = asString(parsed.flags.task) || activeTask(db, session || undefined)?.id;
+  if (!taskId) {
+    print({ error: "task reorder requires --task or an active task" });
+    process.exitCode = 1;
+    return;
+  }
+  const requested = splitList(parsed.flags.order);
+  const order = requested.length > 0 ? requested : parsed.positionals.slice(2);
+  print({ task: getTask(db, taskId), todos: reorderTodos(db, taskId, order) });
+  return;
+    }
+
+function taskDrop(parsed: Parsed, db: ReturnType<typeof openDb>, session: string, spec: ReturnType<typeof loadSpec>): void {
+  const id = asString(parsed.flags.id) || parsed.positionals[2] || "";
+  if (!id) {
+    print({ error: "task drop requires --id" });
+    process.exitCode = 1;
+    return;
+  }
+  print({ todo: dropTodo(db, id, asString(parsed.flags.reason)) });
+  return;
+    }
+
+function taskInsert(parsed: Parsed, db: ReturnType<typeof openDb>, session: string, spec: ReturnType<typeof loadSpec>): void {
+  const id = asString(parsed.flags.id) || parsed.positionals[2] || "";
+  const taskId = asString(parsed.flags.task) || activeTask(db, session || undefined)?.id;
+  if (!taskId) {
+    print({ error: "task insert requires --task or an active task" });
+    process.exitCode = 1;
+    return;
+  }
+  const label = (asString(parsed.flags.label) || parsed.positionals.slice(2).join(" ")).trim();
+  if (!label) {
+    print({ error: "task insert requires --label" });
+    process.exitCode = 1;
+    return;
+  }
+  const item = normalizeTodoInput({
+    label,
+    kind: asString(parsed.flags.kind) || "edit",
+    acceptance: asString(parsed.flags.acceptance) || undefined,
+    owner: splitList(parsed.flags.owner),
+    maxIterations: numberFlag(parsed, "max-iterations", { min: 1, integer: true }) || undefined
+  });
+  const positionRaw = asString(parsed.flags.position);
+  const position = positionRaw === "" ? "end" : /^\d+$/.test(positionRaw) ? Number(positionRaw) : (positionRaw as "start" | "end");
+  print({ todo: insertTodo(db, taskId, item, position), task: getTask(db, taskId) });
+  return;
+    }
+
+function taskAmend(parsed: Parsed, db: ReturnType<typeof openDb>, session: string, spec: ReturnType<typeof loadSpec>): void {
+  const id = asString(parsed.flags.id) || parsed.positionals[2] || "";
+  if (!id) {
+    print({ error: "task amend requires --id" });
+    process.exitCode = 1;
+    return;
+  }
+  const patch: TodoAmendment = {};
+  const label = asString(parsed.flags.label);
+  if (label) patch.label = label;
+  const kind = asString(parsed.flags.kind);
+  if (kind) patch.kind = kind as TodoKind;
+  if (parsed.flags.acceptance !== undefined) patch.acceptance = asString(parsed.flags.acceptance);
+  const owners = splitList(parsed.flags.owner);
+  if (owners.length > 0) patch.owner = owners.join(",");
+  const maxIterations = numberFlag(parsed, "max-iterations", { min: 1, integer: true });
+  if (maxIterations !== undefined && maxIterations > 0) patch.maxIterations = maxIterations;
+  print({ todo: amendTodo(db, id, patch) });
+  return;
+    }
+
+function taskReview(parsed: Parsed, db: ReturnType<typeof openDb>, session: string, spec: ReturnType<typeof loadSpec>): void {
+  const id = asString(parsed.flags.id) || parsed.positionals[2] || "";
+  const taskId = asString(parsed.flags.task) || activeTask(db, session || undefined)?.id;
+  if (!taskId) {
+    print({ error: "task review requires --task or an active task" });
+    process.exitCode = 1;
+    return;
+  }
+  const raw = (asString(parsed.flags.json) || readStdin()).trim();
+  let diff: ReviewDiff = {};
+  if (raw.length > 0) {
+    try {
+      diff = JSON.parse(raw) as ReviewDiff;
+    } catch {
+      print({ error: "invalid JSON review diff" });
+      process.exitCode = 1;
+      return;
+    }
+  }
+  const outcome = reviewTask(db, { taskId, ...diff });
+  print({ ...outcome, reason: asString(parsed.flags.reason) });
+  return;
+    }
+
+function taskSignals(parsed: Parsed, db: ReturnType<typeof openDb>, session: string, spec: ReturnType<typeof loadSpec>): void {
+  const id = asString(parsed.flags.id) || parsed.positionals[2] || "";
+  const taskId = asString(parsed.flags.task) || activeTask(db, session || undefined)?.id;
+  if (!taskId) {
+    print({ error: "task signals requires --task or an active task" });
+    process.exitCode = 1;
+    return;
+  }
+  print({ task: getTask(db, taskId), signals: revisionSignals(db, taskId) });
+  return;
+    }
+
+function taskBlock(parsed: Parsed, db: ReturnType<typeof openDb>, session: string, spec: ReturnType<typeof loadSpec>): void {
+  const id = asString(parsed.flags.id) || parsed.positionals[2] || "";
+  if (!id) {
+    print({ error: "task block requires --id" });
+    process.exitCode = 1;
+    return;
+  }
+  print({ todo: blockTodo(db, id, asString(parsed.flags.reason)) });
+  return;
+    }
+
+function taskDone(parsed: Parsed, db: ReturnType<typeof openDb>, session: string, spec: ReturnType<typeof loadSpec>): void {
+  const id = asString(parsed.flags.id) || parsed.positionals[2] || "";
+  if (!id) {
+    print({ error: "task done requires --id" });
+    process.exitCode = 1;
+    return;
+  }
+  const todo = completeTodo(db, id, asString(parsed.flags.proof));
+  if (spec.config.ledger?.enabled !== false) recordTodoDone(db, todo.task_id);
+  print({ todo });
+  return;
+    }
+
+function taskStart(parsed: Parsed, db: ReturnType<typeof openDb>, session: string, spec: ReturnType<typeof loadSpec>): void {
+  const id = asString(parsed.flags.id) || parsed.positionals[2] || "";
+  if (!id) {
+    print({ error: "task start requires --id" });
+    process.exitCode = 1;
+    return;
+  }
+  const target = getTodo(db, id);
+  if (target && spec.config.ledger?.enabled !== false) {
+    const due = reviewDue(db, target.task_id, spec.config.ledger.review);
+    if (due.due) {
+      print({ error: due.reason, task: target.task_id });
+      process.exitCode = 1;
+      return;
+    }
+  }
+  print({ todo: startTodo(db, id) });
+  return;
+    }
+
+function taskTodo(parsed: Parsed, db: ReturnType<typeof openDb>, session: string, spec: ReturnType<typeof loadSpec>): void {
+  const id = asString(parsed.flags.id) || parsed.positionals[2] || "";
+  const taskId = asString(parsed.flags.task) || activeTask(db, session || undefined)?.id;
+  if (!taskId) {
+    print({ error: "task todo requires --task or an active task" });
+    process.exitCode = 1;
+    return;
+  }
+  const label = (asString(parsed.flags.label) || parsed.positionals.slice(2).join(" ")).trim();
+  if (label.length === 0) {
+    print({ error: "task todo requires --label" });
+    process.exitCode = 1;
+    return;
+  }
+  const maxIterations = numberFlag(parsed, "max-iterations", { min: 1, integer: true });
+  const owners = splitList(parsed.flags.owner);
+  const todos = addTodos(db, taskId, [
+    {
+      label,
+      kind: (asString(parsed.flags.kind) || "edit") as TodoKind,
+      acceptance: asString(parsed.flags.acceptance) || undefined,
+      owner: owners.length > 0 ? owners.join(",") : undefined,
+      maxIterations: maxIterations !== undefined && maxIterations > 0 ? maxIterations : undefined
+    }
+  ]);
+  print({ task: getTask(db, taskId), todos });
+  return;
+    }
+
+function taskPlan(parsed: Parsed, db: ReturnType<typeof openDb>, session: string, spec: ReturnType<typeof loadSpec>): void {
+  const id = asString(parsed.flags.id) || parsed.positionals[2] || "";
+  const taskId = asString(parsed.flags.task) || activeTask(db, session || undefined)?.id;
+  if (!taskId) {
+    print({ error: "task plan requires --task or an active task" });
+    process.exitCode = 1;
+    return;
+  }
+  const raw = (asString(parsed.flags.json) || readStdin()).trim();
+  let parsedItems: unknown;
+  try {
+    parsedItems = JSON.parse(raw.length > 0 ? raw : "[]");
+  } catch {
+    print({ error: "invalid JSON plan" });
+    process.exitCode = 1;
+    return;
+  }
+  if (!Array.isArray(parsedItems)) {
+    print({ error: "plan must be a JSON array of todos" });
+    process.exitCode = 1;
+    return;
+  }
+  const todos = addTodos(db, taskId, parsedItems.map(normalizeTodoInput));
+  print({ task: getTask(db, taskId), todos });
+  return;
+    }
+
+function taskNew(parsed: Parsed, db: ReturnType<typeof openDb>, session: string, spec: ReturnType<typeof loadSpec>): void {
+  const title = (asString(parsed.flags.title) || parsed.positionals.slice(2).join(" ")).trim();
+  if (title.length === 0) {
+    print({ error: "task new requires --title" });
+    process.exitCode = 1;
+    return;
+  }
+  const id = asString(parsed.flags.id) || undefined;
+  const task = createTask(db, { title, id, sessionId: session || undefined });
+  print({ task, todos: [] });
+  return;
+    }
+
+