@alecsibilia/luca 13.0.0-alpha.1

package/dist/shared/luca.DjDTeDCi.mjs

@@ -0,0 +1,1904 @@
+import { z } from 'zod';
+import { P as ProjectPreferencesSchema, b as ConfidenceCategorySchema, d as ConfidenceLevelSchema, e as lucaRootPaths, S as ShadowScanFindingSchema, f as RoadmapPhaseSchema, g as PipelineStep, i as isLegalTransition, h as PIPELINE_TRANSITIONS, j as PIPELINE_STEP_TO_COARSE_PHASE, k as PipelineStepValues, m as TodoIdSchema, s as slugFromTitle, n as TodoSchema, t as todoConceptFor, o as TodoStatus, p as TODO_CONCEPT_PREFIX, V as VerificationRefSchema, l as lucaStateSchema } from './luca.CRmaAfXR.mjs';
+import { l as loadCurrentState, r as resolveActiveSlug } from './luca.CrXzXueR.mjs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdir, writeFile, rename, rm, readFile, appendFile, unlink } from 'node:fs/promises';
+import { join, dirname, resolve, relative, sep } from 'node:path';
+import 'node:crypto';
+import 'node:module';
+import 'node:url';
+import { spawnSync } from 'node:child_process';
+import { c as appendConfidenceEntry, d as appendLedger } from './luca.HZxBTBgD.mjs';
+import { p as phasePathFor } from './luca.TSMg1t7I.mjs';
+import { l as loadCurrentConfig } from './luca.CQ3g1xrD.mjs';
+import { S as STEP_ARTIFACTS, W as WRITE_COMMAND_PHASES } from './luca.B3Mimc0P.mjs';
+
+const PREFERENCE_SECTIONS = [
+  "schemaVersion",
+  "branching",
+  "commits",
+  "pr",
+  "release",
+  "tracker"
+];
+function formatIssues(error) {
+  return error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+}
+function extractPreferences(config) {
+  const raw = config.preferences != null ? config.preferences : {};
+  const result = ProjectPreferencesSchema.safeParse(raw);
+  if (!result.success) {
+    return { ok: false, error: formatIssues(result.error) };
+  }
+  return { ok: true, preferences: result.data };
+}
+function mergePreferences(config, partial) {
+  const currentPrefs = config.preferences && typeof config.preferences === "object" ? config.preferences : {};
+  const mergedPrefs = { ...currentPrefs };
+  const mergedSections = [];
+  for (const section of PREFERENCE_SECTIONS) {
+    if (section in partial) {
+      mergedPrefs[section] = partial[section];
+      mergedSections.push(section);
+    }
+  }
+  const ignoredKeys = Object.keys(partial).filter(
+    (k) => !PREFERENCE_SECTIONS.includes(k)
+  );
+  const result = ProjectPreferencesSchema.safeParse(mergedPrefs);
+  if (!result.success) {
+    return { ok: false, error: formatIssues(result.error) };
+  }
+  return {
+    ok: true,
+    nextConfig: { ...config, preferences: result.data },
+    mergedSections,
+    ignoredKeys
+  };
+}
+
+const DEFAULT_LINE_TOLERANCE = 2;
+const DEFAULT_PROMOTABLE = /* @__PURE__ */ new Set([
+  "nit",
+  "info",
+  "optional",
+  "should-fix",
+  "should",
+  "style",
+  "improvement",
+  "minor",
+  "low"
+]);
+function median(nums) {
+  if (nums.length === 0) return 0;
+  const sorted = [...nums].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  if (sorted.length % 2 === 0) {
+    const a = sorted[mid - 1] ?? 0;
+    const b = sorted[mid] ?? 0;
+    return Math.floor((a + b) / 2);
+  }
+  return sorted[mid] ?? 0;
+}
+function distinctPerspectives(findings) {
+  const set = /* @__PURE__ */ new Set();
+  for (const f of findings) set.add(f.perspective);
+  return [...set].sort();
+}
+function groupFindings(findings, lineTolerance) {
+  const byPath = /* @__PURE__ */ new Map();
+  const orphaned = [];
+  for (const f of findings) {
+    if (!f.path || f.line == null) {
+      orphaned.push(f);
+      continue;
+    }
+    const arr = byPath.get(f.path) ?? [];
+    arr.push(f);
+    byPath.set(f.path, arr);
+  }
+  const groups = [];
+  for (const [path, items] of byPath) {
+    items.sort((a, b) => (a.line ?? 0) - (b.line ?? 0));
+    const buckets = [];
+    for (const f of items) {
+      const line = f.line ?? 0;
+      const target = buckets.find((b) => {
+        const maxLine = Math.max(...b.map((x) => x.line ?? 0));
+        return Math.abs(maxLine - line) <= lineTolerance;
+      });
+      if (target) {
+        target.push(f);
+      } else {
+        buckets.push([f]);
+      }
+    }
+    for (const b of buckets) {
+      const lines = b.map((x) => x.line ?? 0);
+      groups.push({
+        key: `${path}:${Math.min(...lines)}-${Math.max(...lines)}`,
+        path,
+        anchorLine: median(lines),
+        minLine: Math.min(...lines),
+        maxLine: Math.max(...lines),
+        perspectives: distinctPerspectives(b),
+        findings: b
+      });
+    }
+  }
+  for (const f of orphaned) {
+    groups.push({
+      key: `orphan:${f.perspective}:${f.id}`,
+      path: f.path ?? "<no-path>",
+      anchorLine: f.line ?? 0,
+      minLine: f.line ?? 0,
+      maxLine: f.line ?? 0,
+      perspectives: [f.perspective],
+      findings: [f]
+    });
+  }
+  return groups;
+}
+function detectConvergence(findings, opts = {}) {
+  const tolerance = opts.lineTolerance ?? DEFAULT_LINE_TOLERANCE;
+  const promotable = opts.promotableSeverities ? new Set(opts.promotableSeverities.map((s) => s.toLowerCase())) : DEFAULT_PROMOTABLE;
+  const groups = groupFindings(findings, tolerance);
+  const convergentGroups = groups.filter((g) => g.perspectives.length >= 2);
+  const promotions = [];
+  const promoted = findings.map((f) => ({ ...f }));
+  const indexById = /* @__PURE__ */ new Map();
+  promoted.forEach((f, i) => indexById.set(f.id, i));
+  for (const g of convergentGroups) {
+    for (const f of g.findings) {
+      const sev = f.severity.toLowerCase();
+      const idx = indexById.get(f.id);
+      if (promotable.has(sev)) {
+        promotions.push({
+          findingId: f.id,
+          perspective: f.perspective,
+          fromSeverity: f.severity,
+          toSeverity: "must-fix",
+          reason: `Converged with ${g.perspectives.length} perspectives at ${g.path}:${g.minLine}-${g.maxLine}: ${g.perspectives.join(", ")}.`,
+          groupKey: g.key
+        });
+        if (idx !== void 0) {
+          promoted[idx] = { ...f, severity: "must-fix" };
+        }
+      } else if (sev === "must-fix" || sev === "must" || sev === "high" || sev === "critical") {
+        promotions.push({
+          findingId: f.id,
+          perspective: f.perspective,
+          fromSeverity: f.severity,
+          toSeverity: f.severity,
+          reason: `Already must-fix; converged with ${g.perspectives.length} perspectives at ${g.path}:${g.minLine}-${g.maxLine}: ${g.perspectives.join(", ")}.`,
+          groupKey: g.key
+        });
+      }
+    }
+  }
+  return {
+    groups,
+    convergentGroups,
+    promotions,
+    promotedFindings: promoted
+  };
+}
+
+const DEFAULT_SEVERITY_RANK = [
+  "praise",
+  "nit",
+  "info",
+  "optional",
+  "style",
+  "improvement",
+  "should-fix",
+  "should",
+  "must-fix",
+  "must",
+  "high",
+  "critical"
+];
+function findingIdentity(f) {
+  const summaryPrefix = (f.summary ?? "").replace(/\s+/g, " ").trim().slice(0, 80);
+  const anchor = f.line == null ? "?" : String(f.line);
+  return [f.perspective, f.path ?? "<no-path>", anchor, summaryPrefix].join(
+    "::"
+  );
+}
+function severityIndex(severity, ranking) {
+  const idx = ranking.indexOf(severity.toLowerCase());
+  return idx === -1 ? 0 : idx;
+}
+function pathIsTouched(findingPath, touched) {
+  if (!findingPath) return false;
+  return touched.has(findingPath);
+}
+function checkRegression(inputs, opts = {}) {
+  const ranking = opts.severityRank ?? DEFAULT_SEVERITY_RANK;
+  const touched = new Set(inputs.touchedPaths);
+  const beforeIndex = /* @__PURE__ */ new Map();
+  for (const f of inputs.before) {
+    const key = findingIdentity(f);
+    const existing = beforeIndex.get(key);
+    if (!existing || severityIndex(f.severity, ranking) > severityIndex(existing.severity, ranking)) {
+      beforeIndex.set(key, f);
+    }
+  }
+  const afterIndex = /* @__PURE__ */ new Map();
+  for (const f of inputs.after) {
+    const key = findingIdentity(f);
+    const existing = afterIndex.get(key);
+    if (!existing || severityIndex(f.severity, ranking) > severityIndex(existing.severity, ranking)) {
+      afterIndex.set(key, f);
+    }
+  }
+  const regressions = [];
+  const unchanged = [];
+  const newButUntouched = [];
+  const resolved = [];
+  for (const [key, f] of beforeIndex) {
+    if (!afterIndex.has(key)) {
+      resolved.push(f);
+    }
+  }
+  for (const [key, f] of afterIndex) {
+    const prev = beforeIndex.get(key);
+    if (!prev) {
+      if (pathIsTouched(f.path, touched)) {
+        regressions.push({
+          finding: f,
+          reason: "new-on-touched-path",
+          evidence: `New finding from '${f.perspective}' at ${f.path ?? "<no-path>"}:${f.line ?? "?"} on a path modified by this iteration.`
+        });
+      } else {
+        newButUntouched.push(f);
+      }
+      continue;
+    }
+    const prevSev = severityIndex(prev.severity, ranking);
+    const curSev = severityIndex(f.severity, ranking);
+    if (curSev > prevSev) {
+      regressions.push({
+        finding: f,
+        reason: "severity-escalated",
+        evidence: `Severity escalated from '${prev.severity}' to '${f.severity}' on the same finding.`
+      });
+    } else {
+      unchanged.push(f);
+    }
+  }
+  return { regressions, resolved, unchanged, newButUntouched };
+}
+function diffPaths(repoRoot, fromSha, toSha) {
+  const r = spawnSync(
+    "git",
+    ["diff", "--name-only", `${fromSha}..${toSha}`],
+    {
+      cwd: repoRoot,
+      encoding: "utf8",
+      timeout: 5e3
+    }
+  );
+  if (r.status !== 0) return [];
+  return (r.stdout ?? "").split("\n").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+function extractHunkAnchorLines(diffHunk) {
+  const lines = diffHunk.split("\n");
+  const anchors = [];
+  for (const line of lines) {
+    if (line.startsWith("@@")) continue;
+    if (line.startsWith("-")) continue;
+    if (line.startsWith(" ") || line.startsWith("+")) {
+      anchors.push(line.slice(1));
+    } else if (line.length === 0) {
+      anchors.push("");
+    }
+  }
+  while (anchors.length > 0 && anchors[anchors.length - 1] === "") {
+    anchors.pop();
+  }
+  return anchors;
+}
+function readFileLines(repoRoot, relPath) {
+  const full = join(repoRoot, relPath);
+  if (!existsSync(full)) return null;
+  try {
+    return readFileSync(full, "utf8").split("\n");
+  } catch {
+    return null;
+  }
+}
+function git(repoRoot, args, timeoutMs = 5e3) {
+  try {
+    const r = spawnSync("git", args, {
+      cwd: repoRoot,
+      encoding: "utf8",
+      timeout: timeoutMs
+    });
+    if (r.status !== 0) return { ok: false, stdout: "" };
+    return { ok: true, stdout: r.stdout ?? "" };
+  } catch {
+    return { ok: false, stdout: "" };
+  }
+}
+function isCommitReachable(repoRoot, sha) {
+  if (!sha) return false;
+  return git(repoRoot, ["cat-file", "-e", `${sha}^{commit}`]).ok;
+}
+function pathChangedBetween(repoRoot, fromSha, toSha, path) {
+  const r = git(repoRoot, [
+    "diff",
+    "--name-only",
+    `${fromSha}..${toSha}`,
+    "--",
+    path
+  ]);
+  if (!r.ok) return false;
+  return r.stdout.split("\n").some((l) => l.trim() === path);
+}
+function getHeadSha(repoRoot) {
+  const r = git(repoRoot, ["rev-parse", "HEAD"]);
+  if (!r.ok) return void 0;
+  return r.stdout.trim() || void 0;
+}
+function findAnchorInFile(fileLines, anchors, expectedLine) {
+  const meaningfulAnchors = anchors.filter((a) => a.trim().length > 0);
+  if (meaningfulAnchors.length === 0) return void 0;
+  const expected = expectedLine ?? 1;
+  const windowSize = 50;
+  const windowStart = Math.max(0, expected - 1 - windowSize);
+  const windowEnd = Math.min(fileLines.length, expected - 1 + windowSize);
+  function scoreAt(startIdx) {
+    let matched = 0;
+    let mismatches = 0;
+    let cursor = startIdx;
+    for (const anchor of meaningfulAnchors) {
+      let found = -1;
+      for (let probe = 0; probe < 4 && cursor + probe < fileLines.length; probe++) {
+        if (fileLines[cursor + probe] === anchor) {
+          found = probe;
+          break;
+        }
+      }
+      if (found === -1) {
+        mismatches++;
+        if (mismatches > 2) return void 0;
+        cursor++;
+        continue;
+      }
+      matched++;
+      cursor += found + 1;
+    }
+    const ratio = matched / meaningfulAnchors.length;
+    if (ratio < 0.6) return void 0;
+    return { line: startIdx + 1, matchedRatio: ratio };
+  }
+  let best;
+  for (let i = windowStart; i < windowEnd; i++) {
+    const c = scoreAt(i);
+    if (!c) continue;
+    if (!best || c.matchedRatio > best.matchedRatio || Math.abs(c.line - expected) < Math.abs(best.line - expected)) {
+      best = c;
+    }
+  }
+  if (best) return best;
+  for (let i = 0; i < fileLines.length; i++) {
+    if (i >= windowStart && i < windowEnd) continue;
+    const c = scoreAt(i);
+    if (!c) continue;
+    if (!best || c.matchedRatio > best.matchedRatio) {
+      best = c;
+    }
+  }
+  return best;
+}
+function verdictFor(comment, opts) {
+  const { repoRoot } = opts;
+  const maxDrift = opts.maxDriftLines ?? 5;
+  if (comment.diff_hunk === "") {
+    return {
+      commentId: comment.id,
+      stale: false,
+      reason: "empty-diff-hunk",
+      evidence: "empty diff_hunk \u2014 cannot classify"
+    };
+  }
+  const fileLines = readFileLines(repoRoot, comment.path);
+  if (!fileLines) {
+    return {
+      commentId: comment.id,
+      stale: true,
+      reason: "file-missing",
+      evidence: `Cited path '${comment.path}' no longer exists in the working tree.`
+    };
+  }
+  const anchors = extractHunkAnchorLines(comment.diff_hunk);
+  const expectedLine = comment.line ?? comment.original_line;
+  const match = findAnchorInFile(fileLines, anchors, expectedLine);
+  if (!match) {
+    return {
+      commentId: comment.id,
+      stale: true,
+      reason: "content-mismatch",
+      evidence: `Diff hunk anchors not found in current '${comment.path}'. The cited code has likely been rewritten or removed.`
+    };
+  }
+  if (expectedLine != null) {
+    const drift = Math.abs(match.line - expectedLine);
+    if (drift > maxDrift) {
+      return {
+        commentId: comment.id,
+        stale: true,
+        reason: "line-out-of-range",
+        evidence: `Cited line ${expectedLine} differs from current anchor location ${match.line} by ${drift} lines (> ${maxDrift}).`,
+        currentLine: match.line
+      };
+    }
+  }
+  const headSha = opts.headSha ?? getHeadSha(repoRoot);
+  if (headSha && comment.commit_id && comment.commit_id !== headSha && isCommitReachable(repoRoot, comment.commit_id) && pathChangedBetween(repoRoot, comment.commit_id, headSha, comment.path)) {
+    if (match.matchedRatio < 0.85) {
+      return {
+        commentId: comment.id,
+        stale: true,
+        reason: "commit-outdated-and-path-modified",
+        evidence: `Path '${comment.path}' was modified between commit ${comment.commit_id.slice(0, 7)} and HEAD ${headSha.slice(0, 7)} and only ${(match.matchedRatio * 100).toFixed(0)}% of anchors match. Likely stale.`,
+        currentLine: match.line
+      };
+    }
+  }
+  return {
+    commentId: comment.id,
+    stale: false,
+    evidence: `Anchored at line ${match.line} (${(match.matchedRatio * 100).toFixed(0)}% match).`,
+    currentLine: match.line
+  };
+}
+function filterStaleComments(comments, opts) {
+  const headSha = opts.headSha ?? getHeadSha(opts.repoRoot);
+  const verdictOpts = {
+    repoRoot: opts.repoRoot,
+    headSha,
+    maxDriftLines: opts.maxDriftLines
+  };
+  const actionable = [];
+  const stale = [];
+  const replies = [];
+  const unknown = [];
+  const verdicts = {};
+  for (const c of comments) {
+    if (c.in_reply_to_id != null) {
+      replies.push(c);
+      continue;
+    }
+    const v = verdictFor(c, verdictOpts);
+    verdicts[c.id] = v;
+    if (v.stale) {
+      stale.push({ comment: c, verdict: v });
+    } else if (v.reason === "empty-diff-hunk") {
+      unknown.push(c);
+    } else {
+      actionable.push(c);
+    }
+  }
+  return { actionable, stale, replies, unknown, verdicts };
+}
+
+async function resolveRepoVault(opts) {
+  const config = await loadCurrentConfig({ cwd: opts.cwd });
+  const muninn = config.muninn;
+  if (muninn && typeof muninn === "object" && !Array.isArray(muninn)) {
+    const v = muninn.vault;
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  const topLevelVault = config.vault;
+  if (typeof topLevelVault === "string" && topLevelVault.length > 0) {
+    return topLevelVault;
+  }
+  const envVault = process.env.LUCA_MUNINN_VAULT;
+  if (envVault && envVault.length > 0) return envVault;
+  return "default";
+}
+
+async function writeAtomicFile(absPath, content) {
+  await mkdir(dirname(absPath), { recursive: true });
+  const tmp = `${absPath}.tmp`;
+  try {
+    await writeFile(tmp, content);
+    await rename(tmp, absPath);
+  } catch (err) {
+    await rm(tmp, { force: true });
+    throw err;
+  }
+}
+
+function buildMuninnInstruction(input) {
+  const argsJson = JSON.stringify(input.args);
+  const instructionForAgent = `Call ${input.tool}. ${input.description} Parse the args via JSON.parse on the argsJson field; do NOT interpolate any free-form values directly into the call.`;
+  return {
+    tool: input.tool,
+    argsJson,
+    instructionForAgent
+  };
+}
+
+async function validateVerificationRef(opts) {
+  const state = await loadCurrentState({ cwd: opts.cwd });
+  const slug = resolveActiveSlug(state);
+  if (!slug.ok) {
+    return {
+      code: "NO_ACTIVE_PHASE",
+      message: slug.error
+    };
+  }
+  const verifyPath = join(opts.cwd, phasePathFor(slug.slug, "verify"));
+  if (!existsSync(verifyPath)) {
+    return {
+      code: "VERIFY_FILE_MISSING",
+      message: `verify.json not found for phase ${slug.slug}. Run luca-verifier first and persist via luca_phase_write_verify.`
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(verifyPath, "utf-8"));
+  } catch (err) {
+    return {
+      code: "VERIFY_FILE_INVALID",
+      message: `verify.json could not be parsed: ${err.message}`
+    };
+  }
+  const result = parsed;
+  const criteria = Array.isArray(result.criteria) ? result.criteria : [];
+  const found = criteria.find((c) => c.criterionId === opts.ref.criterionId);
+  if (!found) {
+    return {
+      code: "CRITERION_NOT_FOUND",
+      message: `criterion "${opts.ref.criterionId}" not present in ${slug.slug}/verify.json. Existing ids: ${criteria.map((c) => c.criterionId).filter(Boolean).join(", ") || "(none)"}.`
+    };
+  }
+  if (!found.met) {
+    return {
+      code: "CRITERION_UNMET",
+      message: `criterion "${opts.ref.criterionId}" is recorded as met=false. Cannot mark a todo done against an unmet criterion.`
+    };
+  }
+  if (!found.evidence || !found.evidence.trim()) {
+    return {
+      code: "CRITERION_NO_EVIDENCE",
+      message: `criterion "${opts.ref.criterionId}" has empty evidence. Re-run verification with concrete evidence (file:line or test name) before marking the todo done.`
+    };
+  }
+  if (result.status !== "PASS") {
+    return {
+      code: "VERIFY_NOT_PASS",
+      message: `verify.json status is "${result.status}", not "PASS". Cannot mark a todo done against a failing/stalled verification run.`
+    };
+  }
+  return null;
+}
+
+const inputSchema$h = z.object({
+  default_branch: z.string().min(1).default("main").describe(
+    "Branch name that must NOT equal the current branch (typically the repository default branch)."
+  )
+});
+async function readCurrentBranch(cwd) {
+  const proc = Bun.spawn(["git", "rev-parse", "--abbrev-ref", "HEAD"], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe"
+  });
+  const code = await proc.exited;
+  if (code !== 0) return null;
+  const out = await new Response(proc.stdout).text();
+  return out.trim() || null;
+}
+const lucaBranchGuardTool = {
+  name: "luca_branch_guard",
+  description: "Assert that the current git branch is NOT the repository default branch. Returns isError when on the default branch, otherwise ok=true. Use before committing to prevent accidental main writes.",
+  inputSchema: inputSchema$h,
+  async handler(args, ctx) {
+    const current = await readCurrentBranch(ctx.cwd);
+    if (current === null) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `luca_branch_guard: could not read git branch in ${ctx.cwd} (not a git repo?)`
+          }
+        ],
+        isError: true
+      };
+    }
+    const result = {
+      ok: current !== args.default_branch,
+      current,
+      default: args.default_branch,
+      message: current === args.default_branch ? `on default branch "${args.default_branch}" \u2014 refusing to proceed; switch to a feature branch first.` : `current branch "${current}" differs from default "${args.default_branch}".`
+    };
+    return {
+      content: [
+        { type: "text", text: JSON.stringify(result, null, 2) }
+      ],
+      isError: !result.ok
+    };
+  }
+};
+
+const commandSchema = z.object({
+  argv: z.array(z.string().min(1)).min(1).describe(
+    "Argv array passed directly to the spawn. First element is the executable, remaining elements are arguments. No shell interpolation."
+  ),
+  label: z.string().min(1).optional().describe(
+    "Optional human-friendly label for this command in the summary output. Defaults to the argv joined by spaces."
+  )
+});
+const inputSchema$g = z.object({
+  commands: z.array(commandSchema).min(1).describe(
+    "Ordered list of commands to run sequentially. Each command runs only if the previous one is still within budget; failures do NOT stop the sequence."
+  ),
+  timeout_ms: z.number().int().min(100).max(6e5).default(9e4).describe(
+    "Per-command timeout in milliseconds (range 100\u2013600000, default 90000). On timeout the process is killed (SIGTERM then SIGKILL) and reported as timedOut=true."
+  )
+});
+const MAX_OUTPUT_BYTES = 16 * 1024;
+function truncate(buf) {
+  if (buf.length <= MAX_OUTPUT_BYTES) return buf;
+  const head = buf.slice(0, MAX_OUTPUT_BYTES / 2);
+  const tail = buf.slice(-MAX_OUTPUT_BYTES / 2);
+  return `${head}
+\u2026[truncated ${buf.length - MAX_OUTPUT_BYTES} bytes]\u2026
+${tail}`;
+}
+async function runOne(argv, label, cwd, timeoutMs) {
+  const [cmd, ...rest] = argv;
+  if (!cmd) {
+    return {
+      label,
+      argv,
+      ok: false,
+      exitCode: null,
+      timedOut: false,
+      stdout: "",
+      stderr: "empty argv"
+    };
+  }
+  const proc = Bun.spawn([cmd, ...rest], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+    stdin: "ignore"
+  });
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    try {
+      proc.kill("SIGTERM");
+    } catch {
+    }
+    setTimeout(() => {
+      if (proc.exitCode === null) {
+        try {
+          proc.kill("SIGKILL");
+        } catch {
+        }
+      }
+    }, 250);
+  }, timeoutMs);
+  let exitCode = null;
+  let stdoutText = "";
+  let stderrText = "";
+  try {
+    const [code, stdout, stderr] = await Promise.all([
+      proc.exited,
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text()
+    ]);
+    exitCode = code;
+    stdoutText = truncate(stdout);
+    stderrText = truncate(stderr);
+  } finally {
+    clearTimeout(timer);
+  }
+  return {
+    label,
+    argv,
+    ok: !timedOut && exitCode === 0,
+    exitCode,
+    timedOut,
+    stdout: stdoutText,
+    stderr: stderrText
+  };
+}
+const lucaChecksRunTool = {
+  name: "luca_checks_run",
+  description: "Run verification commands (typecheck/tests/lint) sequentially with per-command timeout and SIGTERM/SIGKILL cleanup. Returns structured summary per command. Only callable in execute/checks phases.",
+  inputSchema: inputSchema$g,
+  allowedPhases: ["execute", "checks"],
+  async handler(args, ctx) {
+    const results = [];
+    for (const cmd of args.commands) {
+      const label = cmd.label ?? cmd.argv.join(" ");
+      const r = await runOne(cmd.argv, label, ctx.cwd, args.timeout_ms);
+      results.push(r);
+    }
+    const passed = results.every((r) => r.ok);
+    const payload = { passed, summary: results };
+    return {
+      content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+      isError: !passed
+    };
+  }
+};
+
+const inputSchema$f = z.object({
+  phase: z.string().min(1).describe("Phase name from the plan / roadmap."),
+  wave: z.number().describe("Wave number within the phase."),
+  task: z.string().min(1).describe("Task ID or description from the plan."),
+  confidence: ConfidenceLevelSchema.describe(
+    "How confident the executor was in its decision (high|medium|low)."
+  ),
+  category: ConfidenceCategorySchema.describe(
+    "What kind of ambiguity was encountered."
+  ),
+  decision: z.string().min(1).describe("What the executor actually decided to do."),
+  alternatives: z.array(z.string()).describe("Other options that were considered."),
+  reasoning: z.string().min(1).describe("Why this choice was made over the alternatives."),
+  risk: z.string().min(1).describe("What could go wrong if this was the wrong call."),
+  files: z.array(z.string()).describe("Which files were affected by this decision."),
+  reviewHint: z.string().optional().describe("Suggested focus area for a human reviewer.")
+});
+const lucaConfidenceLogTool = {
+  name: "luca_confidence_log",
+  description: "Append a confidence entry to the active phase's confidence.jsonl. One JSONL line per call. Payload matches the canonical ConfidenceEntrySchema (phase, wave, task, confidence, category, decision, alternatives, reasoning, risk, files, reviewHint?).",
+  inputSchema: inputSchema$f,
+  async handler(args, ctx) {
+    const state = await loadCurrentState({ cwd: ctx.cwd });
+    const slug = resolveActiveSlug(state);
+    if (!slug.ok) {
+      return {
+        content: [{ type: "text", text: slug.error }],
+        isError: true
+      };
+    }
+    const entry = appendConfidenceEntry({
+      cwd: ctx.cwd,
+      slug: slug.slug,
+      entry: {
+        phase: args.phase,
+        wave: args.wave,
+        task: args.task,
+        confidence: args.confidence,
+        category: args.category,
+        decision: args.decision,
+        alternatives: args.alternatives,
+        reasoning: args.reasoning,
+        risk: args.risk,
+        files: args.files,
+        ...args.reviewHint !== void 0 ? { reviewHint: args.reviewHint } : {}
+      }
+    });
+    return {
+      content: [
+        {
+          type: "text",
+          text: `appended confidence entry (${entry.confidence}, ${entry.category}) to phase '${slug.slug}' (task: ${entry.task})`
+        }
+      ]
+    };
+  }
+};
+
+const inputSchema$e = z.object({});
+const lucaPhaseCurrentTool = {
+  name: "luca_phase_current",
+  description: "Return information about the currently active phase: { active, NN, slug, dir }. When no phase is active (currentPhase=0), returns { active: false }.",
+  inputSchema: inputSchema$e,
+  async handler(_args, ctx) {
+    const state = await loadCurrentState({ cwd: ctx.cwd });
+    if (state.currentPhase === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ active: false }, null, 2)
+          }
+        ]
+      };
+    }
+    const resolved = resolveActiveSlug(state);
+    if (!resolved.ok) {
+      return {
+        content: [{ type: "text", text: resolved.error }],
+        isError: true
+      };
+    }
+    const dir = phasePathFor(resolved.slug);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              active: true,
+              NN: resolved.NN,
+              slug: resolved.slug,
+              dir
+            },
+            null,
+            2
+          )
+        }
+      ]
+    };
+  }
+};
+
+z.object({
+  reviewer: z.string().regex(/^[a-z][a-z0-9-]*[a-z0-9]?$/, {
+    message: 'reviewer must be kebab-case (e.g. "code-review", "security")'
+  }).describe(
+    'Reviewer name (kebab-case). Examples: "code-review", "security", "architect", "ux".'
+  ),
+  content: z.string().min(1).describe(
+    "Markdown audit content. Written to .luca/phases/<active-slug>/audits/<reviewer>.md."
+  )
+});
+
+z.object({
+  content: z.string().min(1).describe(
+    "Markdown content capturing user decisions from /phase-discuss. Written verbatim to .luca/phases/<active-slug>/context.md."
+  )
+});
+
+z.object({
+  content: z.string().min(1).describe(
+    "Markdown content capturing learnings from this phase. Written to .luca/phases/<active-slug>/learn.md."
+  )
+});
+
+z.object({
+  content: z.string().min(1).describe(
+    "Markdown plan-review output (APPROVED | NEEDS_REVISION | ESCALATE + findings). Written to .luca/phases/<active-slug>/plan-review.md."
+  )
+});
+
+z.object({
+  content: z.string().min(1).describe(
+    "Markdown content of the phase plan. Will be written verbatim to .luca/phases/<active-slug>/plan.md."
+  )
+});
+
+z.object({
+  content: z.string().min(1).describe(
+    "Markdown content of phase research notes. Written verbatim to .luca/phases/<active-slug>/research.md."
+  )
+});
+
+z.object({
+  content: z.string().min(1).describe(
+    "Markdown summary of the executed phase work. Written to .luca/phases/<active-slug>/execute/summary.md."
+  )
+});
+
+z.object({
+  result: z.record(z.string(), z.unknown()).describe(
+    "Structured verification result. Common fields: status (pass|fail), typecheck (bool), tests ({passed, failed}), lint (...). Written verbatim to .luca/phases/<active-slug>/verify.json."
+  )
+});
+
+z.object({
+  waveNumber: z.number().int().min(0).max(99).describe(
+    "Wave number (0\u201399). Zero-padded to two digits in the filename (e.g. wave 3 \u2192 03.md)."
+  ),
+  content: z.string().min(1).describe(
+    "Markdown content for this wave. Written to .luca/phases/<active-slug>/execute/waves/NN.md."
+  )
+});
+
+const findingSchema$1 = z.object({
+  id: z.string(),
+  perspective: z.string(),
+  path: z.string().optional(),
+  line: z.number().optional(),
+  severity: z.string(),
+  category: z.string().optional(),
+  summary: z.string()
+});
+const inputSchema$d = z.object({
+  findings: z.array(findingSchema$1).describe(
+    "Combined review findings across every perspective (PR comments, claim-verifier, reviewer subagents, CI annotations)."
+  ),
+  line_tolerance: z.number().int().min(0).optional().describe(
+    "Lines within +/- this distance count as the same location (default 2)."
+  )
+});
+const lucaPrReviewDetectConvergenceTool = {
+  name: "luca_pr_review_detect_convergence",
+  description: "Group review findings by location and auto-promote severity to must-fix when 2+ distinct perspectives flag the same line. Returns the convergence report plus promoted findings. Read-only.",
+  inputSchema: inputSchema$d,
+  async handler(args, _ctx) {
+    const report = detectConvergence(args.findings, {
+      lineTolerance: args.line_tolerance
+    });
+    const summary = {
+      counts: {
+        input: args.findings.length,
+        groups: report.groups.length,
+        convergentGroups: report.convergentGroups.length,
+        promotions: report.promotions.length
+      },
+      report
+    };
+    return {
+      content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
+    };
+  }
+};
+
+const commentSchema = z.object({
+  id: z.number(),
+  path: z.string(),
+  line: z.number().nullable(),
+  original_line: z.number().nullable(),
+  commit_id: z.string(),
+  original_commit_id: z.string(),
+  diff_hunk: z.string(),
+  body: z.string(),
+  in_reply_to_id: z.number().nullable().optional(),
+  user: z.object({
+    login: z.string().optional(),
+    type: z.string().optional()
+  }).optional()
+});
+const inputSchema$c = z.object({
+  comments: z.array(commentSchema).describe(
+    "PR review comments (gh api pulls/<n>/comments shape). Each is classified against the current working tree."
+  ),
+  head_sha: z.string().optional().describe(
+    "Override HEAD SHA used for stale detection. Defaults to current git HEAD."
+  ),
+  max_drift_lines: z.number().int().min(0).optional().describe(
+    "Max line drift before a relocated anchor is treated as stale (default 5)."
+  )
+});
+const lucaPrReviewFilterStaleTool = {
+  name: "luca_pr_review_filter_stale",
+  description: "Partition PR review comments into actionable / stale / replies / unknown buckets by re-anchoring each comment against the current working tree. Drops comments whose cited code was rewritten. Read-only.",
+  inputSchema: inputSchema$c,
+  async handler(args, ctx) {
+    const result = filterStaleComments(args.comments, {
+      repoRoot: ctx.cwd,
+      headSha: args.head_sha,
+      maxDriftLines: args.max_drift_lines
+    });
+    const summary = {
+      counts: {
+        input: args.comments.length,
+        actionable: result.actionable.length,
+        stale: result.stale.length,
+        replies: result.replies.length,
+        unknown: result.unknown.length
+      },
+      actionable: result.actionable,
+      stale: result.stale,
+      replies: result.replies,
+      unknown: result.unknown,
+      verdicts: result.verdicts
+    };
+    return {
+      content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
+    };
+  }
+};
+
+const findingSchema = z.object({
+  id: z.string(),
+  perspective: z.string(),
+  path: z.string().optional(),
+  line: z.number().optional(),
+  severity: z.string(),
+  category: z.string().optional(),
+  summary: z.string()
+});
+const inputSchema$b = z.object({
+  before: z.array(findingSchema).describe("Findings snapshot taken BEFORE the fix iteration."),
+  after: z.array(findingSchema).describe("Findings snapshot taken AFTER the fix iteration."),
+  touched_paths: z.array(z.string()).default([]).describe(
+    "Repo-relative paths modified by fix commits in this iteration. If empty and from_sha/to_sha are given, computed via git diff."
+  ),
+  from_sha: z.string().optional().describe("Iteration-start SHA (used to compute touched paths)."),
+  to_sha: z.string().optional().describe("Iteration-end SHA (used to compute touched paths).")
+});
+const lucaPrReviewRegressionCheckTool = {
+  name: "luca_pr_review_regression_check",
+  description: "Diff before/after review-finding snapshots to surface regressions introduced by a fix iteration (new findings on touched paths, severity escalations). Returns isError when regressions are found. Read-only.",
+  inputSchema: inputSchema$b,
+  async handler(args, ctx) {
+    let touchedPaths = args.touched_paths;
+    if (touchedPaths.length === 0 && args.from_sha && args.to_sha) {
+      touchedPaths = diffPaths(ctx.cwd, args.from_sha, args.to_sha);
+    }
+    const report = checkRegression({
+      before: args.before,
+      after: args.after,
+      touchedPaths
+    });
+    const summary = {
+      counts: {
+        before: args.before.length,
+        after: args.after.length,
+        touchedPaths: touchedPaths.length,
+        regressions: report.regressions.length,
+        resolved: report.resolved.length,
+        unchanged: report.unchanged.length,
+        newButUntouched: report.newButUntouched.length
+      },
+      touchedPaths,
+      report
+    };
+    const hasRegressions = report.regressions.length > 0;
+    return {
+      content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],
+      isError: hasRegressions
+    };
+  }
+};
+
+const inputSchema$a = z.object({});
+const lucaPreferencesReadTool = {
+  name: "luca_preferences_read",
+  description: "Read the project preferences object from .luca/config.json#preferences. Returns ProjectPreferencesSchema-validated JSON, with defaults applied to unset sections. Pure read \u2014 allowed in every pipelineStep.",
+  inputSchema: inputSchema$a,
+  async handler(_args, ctx) {
+    const config = await loadCurrentConfig({ cwd: ctx.cwd });
+    const result = extractPreferences(config);
+    if (!result.ok) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `luca_preferences_read: .luca/config.json#preferences failed validation: ${result.error}`
+          }
+        ],
+        isError: true
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result.preferences, null, 2)
+        }
+      ]
+    };
+  }
+};
+
+const inputSchema$9 = z.object({
+  preferences: z.record(z.string(), z.unknown()).describe(
+    "Partial preferences object. Top-level sections (branching, commits, pr, release, tracker, schemaVersion) overlay the existing ones; unspecified sections are left unchanged. The merged result is re-validated against ProjectPreferencesSchema before write."
+  )
+});
+const lucaPreferencesWriteTool = {
+  name: "luca_preferences_write",
+  description: "Write/update the preferences section of .luca/config.json. Section-level shallow merge; preserves other config keys. Validated through ProjectPreferencesSchema (rejects unsafe free-form input and ReDoS-shaped regex).",
+  inputSchema: inputSchema$9,
+  async handler(args, ctx) {
+    const config = await loadCurrentConfig({ cwd: ctx.cwd });
+    const result = mergePreferences(config, args.preferences);
+    if (!result.ok) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `luca_preferences_write: validation failed: ${result.error}`
+          }
+        ],
+        isError: true
+      };
+    }
+    const absPath = join(ctx.cwd, lucaRootPaths.config);
+    await writeAtomicFile(
+      absPath,
+      JSON.stringify(result.nextConfig, null, 2) + "\n"
+    );
+    const ignoredNote = result.ignoredKeys.length > 0 ? `; ignored ${result.ignoredKeys.length} unknown key(s): ${result.ignoredKeys.join(", ")}` : "";
+    return {
+      content: [
+        {
+          type: "text",
+          text: `wrote .luca/config.json (preferences section updated; ${result.mergedSections.length} section(s) merged${ignoredNote})`
+        }
+      ]
+    };
+  }
+};
+
+const inputSchema$8 = z.object({
+  finding: ShadowScanFindingSchema.describe(
+    "A single finding from a luca-shadow-scanner ShadowScanReport. recommended_action drives what gets applied."
+  ),
+  confirm: z.boolean().default(false).describe(
+    "Must be true to actually apply the remediation. Default false so a stray call cannot delete/move files."
+  )
+});
+function checkPath(cwd, relPath) {
+  const root = resolve(cwd);
+  const abs = resolve(root, relPath);
+  const rel = relative(root, abs);
+  if (rel === "" || rel.startsWith("..") || rel.startsWith(`..${sep}`)) {
+    return {
+      ok: false,
+      abs,
+      error: `path "${relPath}" escapes the project root`
+    };
+  }
+  if (rel === ".git" || rel.startsWith(`.git${sep}`)) {
+    return {
+      ok: false,
+      abs,
+      error: `refusing to operate inside .git/ ("${relPath}")`
+    };
+  }
+  return { ok: true, abs };
+}
+const lucaRepoCleanupApplyTool = {
+  name: "luca_repo_cleanup_apply",
+  description: "Apply one luca-shadow-scanner finding: delete a debris file, move a misplaced file, or add a path to .gitignore. Destructive \u2014 requires confirm=true. Path-safety enforced (no traversal, no .git/).",
+  inputSchema: inputSchema$8,
+  async handler(args, ctx) {
+    if (!args.confirm) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "luca_repo_cleanup_apply refused: confirm=true required (delete/move are destructive)."
+          }
+        ],
+        isError: true
+      };
+    }
+    const { finding } = args;
+    const src = checkPath(ctx.cwd, finding.file_path);
+    if (!src.ok) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `luca_repo_cleanup_apply: ${src.error}`
+          }
+        ],
+        isError: true
+      };
+    }
+    switch (finding.recommended_action) {
+      case "delete": {
+        if (!existsSync(src.abs)) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `skipped: ${finding.file_path} not found (nothing to delete).`
+              }
+            ]
+          };
+        }
+        await unlink(src.abs);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `applied delete: removed ${finding.file_path}`
+            }
+          ]
+        };
+      }
+      case "move": {
+        if (!finding.target_path) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "luca_repo_cleanup_apply: target_path is required for a move action."
+              }
+            ],
+            isError: true
+          };
+        }
+        const dst = checkPath(ctx.cwd, finding.target_path);
+        if (!dst.ok) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `luca_repo_cleanup_apply: ${dst.error}`
+              }
+            ],
+            isError: true
+          };
+        }
+        if (!existsSync(src.abs)) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `skipped: ${finding.file_path} not found (nothing to move).`
+              }
+            ]
+          };
+        }
+        await mkdir(dirname(dst.abs), { recursive: true });
+        await rename(src.abs, dst.abs);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `applied move: ${finding.file_path} \u2192 ${finding.target_path}`
+            }
+          ]
+        };
+      }
+      case "gitignore": {
+        const gitignorePath = join(resolve(ctx.cwd), ".gitignore");
+        const existing = existsSync(gitignorePath) ? await readFile(gitignorePath, "utf-8") : "";
+        const alreadyPresent = existing.split("\n").some((line) => {
+          const trimmed = line.trim();
+          return trimmed !== "" && !trimmed.startsWith("#") && trimmed === finding.file_path;
+        });
+        if (alreadyPresent) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `skipped: ${finding.file_path} already in .gitignore.`
+              }
+            ]
+          };
+        }
+        const newline = existing === "" || existing.endsWith("\n") ? "" : "\n";
+        await appendFile(
+          gitignorePath,
+          `${newline}${finding.file_path}
+`
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: `applied gitignore: added ${finding.file_path} to .gitignore`
+            }
+          ]
+        };
+      }
+    }
+  }
+};
+
+const inputSchema$7 = z.object({
+  phases: z.array(RoadmapPhaseSchema).min(1).describe(
+    "Ordered list of roadmap phases. Each entry: { name, deps?, status?, complexity? }. Defaults: deps=[], status=pending."
+  )
+});
+const lucaRoadmapCreateTool = {
+  name: "luca_roadmap_create",
+  description: "Replace the roadmap in .luca/state.json with a new ordered list of phases. Resets currentPhase to 0; updates totalPhases. Only callable in idle or triage pipelineSteps so an active roadmap cannot be clobbered mid-execution.",
+  inputSchema: inputSchema$7,
+  allowedPhases: ["idle", "triage"],
+  async handler(args, ctx) {
+    const state = await loadCurrentState({ cwd: ctx.cwd });
+    const phases = args.phases.map((p) => ({
+      ...p,
+      deps: p.deps ?? [],
+      status: p.status ?? "pending"
+    }));
+    const next = {
+      ...state,
+      roadmap: phases,
+      totalPhases: phases.length,
+      currentPhase: 0
+    };
+    const absPath = join(ctx.cwd, lucaRootPaths.state);
+    await writeAtomicFile(absPath, JSON.stringify(next, null, 2) + "\n");
+    return {
+      content: [
+        {
+          type: "text",
+          text: `wrote .luca/state.json (roadmap replaced with ${phases.length} phase(s); currentPhase reset to 0)`
+        }
+      ]
+    };
+  }
+};
+
+const inputSchema$6 = z.object({});
+const lucaRoadmapReadTool = {
+  name: "luca_roadmap_read",
+  description: "Read the roadmap array from .luca/state.json, plus currentPhase and totalPhases for context. Each entry is { name, deps, status, complexity? }. Pure read \u2014 callable in every pipelineStep.",
+  inputSchema: inputSchema$6,
+  async handler(_args, ctx) {
+    const state = await loadCurrentState({ cwd: ctx.cwd });
+    const payload = {
+      currentPhase: state.currentPhase,
+      totalPhases: state.roadmap.length,
+      roadmap: state.roadmap
+    };
+    return {
+      content: [
+        { type: "text", text: JSON.stringify(payload, null, 2) }
+      ]
+    };
+  }
+};
+
+function isPhaseHeading(line, phaseName) {
+  const m = /^(#{1,6})\s+(.*)$/.exec(line);
+  if (!m || !m[2]) return false;
+  const headingText = m[2].trim();
+  const target = phaseName.trim().toLowerCase();
+  if (!target) return false;
+  if (headingText.toLowerCase() === target) return true;
+  const prefixed = /^Phase\s+\d+(?:\.\d+)*\s*[:\-—]\s*(.+)$/i.exec(
+    headingText
+  );
+  if (prefixed && prefixed[1] && prefixed[1].trim().toLowerCase() === target)
+    return true;
+  if (headingText.toLowerCase() === `phase ${target}`) return true;
+  return false;
+}
+function headingDepth(line) {
+  const m = /^(#{1,6})\s+\S/.exec(line);
+  return m && m[1] ? m[1].length : 0;
+}
+function tickPhaseTasks(planFile, phaseName) {
+  const base = {
+    tickedCount: 0,
+    alreadyTickedCount: 0,
+    planFile,
+    phaseName,
+    tickedLines: []
+  };
+  if (!planFile) {
+    return {
+      ...base,
+      success: false,
+      reason: "planFile path is empty"
+    };
+  }
+  if (!phaseName) {
+    return {
+      ...base,
+      success: false,
+      reason: "phaseName is empty"
+    };
+  }
+  if (!existsSync(planFile)) {
+    return {
+      ...base,
+      success: false,
+      reason: `plan.md not found at ${planFile}`
+    };
+  }
+  let raw;
+  try {
+    raw = readFileSync(planFile, "utf8");
+  } catch (err) {
+    return {
+      ...base,
+      success: false,
+      reason: `failed to read ${planFile}: ${err.message}`
+    };
+  }
+  const hadTrailingNewline = raw.endsWith("\n");
+  const lines = raw.split("\n");
+  if (hadTrailingNewline) {
+    lines.pop();
+  }
+  let sectionStart = -1;
+  let sectionDepth = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const candidate = lines[i] ?? "";
+    if (isPhaseHeading(candidate, phaseName)) {
+      sectionStart = i + 1;
+      sectionDepth = headingDepth(candidate);
+      break;
+    }
+  }
+  if (sectionStart === -1) {
+    return {
+      ...base,
+      success: false,
+      reason: `no heading matching phase "${phaseName}" found in ${planFile}`
+    };
+  }
+  let sectionEnd = lines.length;
+  for (let i = sectionStart; i < lines.length; i++) {
+    const d = headingDepth(lines[i] ?? "");
+    if (d > 0 && d <= sectionDepth) {
+      sectionEnd = i;
+      break;
+    }
+  }
+  const uncheckedRe = /^(\s*[-*]\s+)\[ \](\s)/;
+  const checkedRe = /^(\s*[-*]\s+)\[[xX]\](\s)/;
+  const tickedLines = [];
+  let alreadyTicked = 0;
+  for (let i = sectionStart; i < sectionEnd; i++) {
+    const line = lines[i] ?? "";
+    if (uncheckedRe.test(line)) {
+      lines[i] = line.replace(uncheckedRe, "$1[x]$2");
+      tickedLines.push(i + 1);
+    } else if (checkedRe.test(line)) {
+      alreadyTicked++;
+    }
+  }
+  if (tickedLines.length === 0) {
+    return {
+      ...base,
+      success: true,
+      alreadyTickedCount: alreadyTicked,
+      reason: alreadyTicked > 0 ? `all ${alreadyTicked} checkbox(es) in phase "${phaseName}" already ticked` : `no '- [ ]' checkboxes found under phase "${phaseName}"`
+    };
+  }
+  const out = lines.join("\n") + (hadTrailingNewline ? "\n" : "");
+  try {
+    writeFileSync(planFile, out, "utf8");
+  } catch (err) {
+    return {
+      ...base,
+      success: false,
+      reason: `failed to write ${planFile}: ${err.message}`
+    };
+  }
+  return {
+    ...base,
+    success: true,
+    tickedCount: tickedLines.length,
+    alreadyTickedCount: alreadyTicked,
+    tickedLines
+  };
+}
+
+const inputSchema$5 = z.object({
+  toStep: PipelineStep.describe(
+    "Target pipelineStep. Must be a legal transition from the current step (see the pipeline-transitions table)."
+  )
+});
+function stepOrdinal(step) {
+  return PipelineStepValues.indexOf(step);
+}
+const EMPTY_STEP_CHECK = {
+  research: "research",
+  discuss: "context",
+  plan: "plan",
+  "plan-review": "plan-review",
+  execute: "execute/summary",
+  verify: "verify",
+  learn: "learn"
+};
+function expectedArtifactPath(cwd, slug, key) {
+  switch (key) {
+    case "research":
+    case "context":
+    case "plan":
+    case "plan-review":
+    case "verify":
+    case "learn":
+      return join(cwd, phasePathFor(slug, key));
+    case "execute/summary":
+      return join(cwd, phasePathFor(slug, "execute/summary"));
+    default:
+      return null;
+  }
+}
+const lucaStateAdvanceTool = {
+  name: "luca_state_advance",
+  description: "Atomically advance the workflow pipelineStep. Validates the transition against the pipeline-transitions table; legal forward + loop-back transitions allowed, illegal jumps rejected.",
+  inputSchema: inputSchema$5,
+  async handler(args, ctx) {
+    const state = await loadCurrentState({ cwd: ctx.cwd });
+    const from = state.pipelineStep;
+    const to = args.toStep;
+    if (!isLegalTransition(from, to)) {
+      const allowed = PIPELINE_TRANSITIONS[from].join(", ");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `illegal transition: '${from}' \u2192 '${to}'. Allowed next steps from '${from}': [${allowed}].`
+          }
+        ],
+        isError: true
+      };
+    }
+    const next = { ...state, pipelineStep: to };
+    const path = join(ctx.cwd, ".luca", "state.json");
+    await writeAtomicFile(path, JSON.stringify(next, null, 2) + "\n");
+    try {
+      const runId = typeof state.sessionId === "string" ? state.sessionId : "";
+      appendLedger({
+        cwd: ctx.cwd,
+        runId,
+        event: "mode-transition",
+        data: { from, to }
+      });
+      if (stepOrdinal(to) < stepOrdinal(from)) {
+        appendLedger({
+          cwd: ctx.cwd,
+          runId,
+          event: "pipeline-re-entered",
+          data: {
+            targetMode: to,
+            from,
+            reason: `loop-back from '${from}' to '${to}' (rework / fix iteration)`
+          }
+        });
+      }
+      const expectedKey = EMPTY_STEP_CHECK[from];
+      if (expectedKey !== void 0) {
+        const declared = STEP_ARTIFACTS[from];
+        if (declared.includes(expectedKey)) {
+          const slugResult = resolveActiveSlug(state);
+          if (slugResult.ok) {
+            const artifactPath = expectedArtifactPath(
+              ctx.cwd,
+              slugResult.slug,
+              expectedKey
+            );
+            if (artifactPath !== null && !existsSync(artifactPath)) {
+              appendLedger({
+                cwd: ctx.cwd,
+                runId,
+                event: "phase-empty-detected",
+                data: {
+                  from,
+                  to,
+                  slug: slugResult.slug,
+                  expectedArtifact: expectedKey,
+                  reason: `step '${from}' advanced to '${to}' without writing its expected artifact ('${expectedKey}') \u2014 possible empty/skipped step`
+                }
+              });
+            }
+          }
+        }
+      }
+    } catch {
+    }
+    try {
+      const fromCoarse = PIPELINE_STEP_TO_COARSE_PHASE[from];
+      const toCoarse = PIPELINE_STEP_TO_COARSE_PHASE[to];
+      if (fromCoarse === "EXECUTING" && toCoarse !== "EXECUTING") {
+        const slugResult = resolveActiveSlug(state);
+        if (slugResult.ok) {
+          const planFile = join(
+            ctx.cwd,
+            phasePathFor(slugResult.slug, "plan")
+          );
+          const roadmapEntry = state.roadmap[state.currentPhase - 1];
+          const phaseName = roadmapEntry?.name ?? slugResult.slug;
+          const tickResult = tickPhaseTasks(planFile, phaseName);
+          const runIdForTick = typeof state.sessionId === "string" ? state.sessionId : "";
+          appendLedger({
+            cwd: ctx.cwd,
+            runId: runIdForTick,
+            event: "plan-tick-result",
+            data: {
+              phase: phaseName,
+              slug: slugResult.slug,
+              planFile: tickResult.planFile,
+              success: tickResult.success,
+              tickedCount: tickResult.tickedCount,
+              alreadyTickedCount: tickResult.alreadyTickedCount,
+              reason: tickResult.reason ?? null
+            }
+          });
+        }
+      }
+    } catch {
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: `pipelineStep advanced: '${from}' \u2192 '${to}'`
+        }
+      ]
+    };
+  }
+};
+
+const inputSchema$4 = z.object({});
+const lucaStateReadTool = {
+  name: "luca_state_read",
+  description: "Read the current workflow state from .luca/state.json. Returns the parsed JSON including pipelineStep, currentPhase, iteration counters, and the roadmap.",
+  inputSchema: inputSchema$4,
+  // No allowedPhases — read-only tool available in every phase.
+  async handler(_args, ctx) {
+    const state = await loadCurrentState({ cwd: ctx.cwd });
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(state, null, 2)
+        }
+      ]
+    };
+  }
+};
+
+const inputSchema$3 = z.object({
+  title: z.string().min(1).max(200).describe(
+    "Short imperative description of the todo. Used to derive the id when one is not supplied."
+  ),
+  body: z.string().max(8192).optional().describe(
+    "Optional longer markdown body \u2014 context, acceptance criteria, references."
+  ),
+  /**
+   * Only pending and backlog are allowed at create time. Promoting
+   * to `done` happens via luca_todo_update with a verificationRef
+   * that points at a met criterion in verify.json.
+   */
+  status: z.enum(["pending", "backlog"]).default("pending"),
+  source: z.string().max(120).optional().describe(
+    'Where this todo originated \u2014 e.g. "gh-issue-#42", "phase-research", "manual".'
+  ),
+  metadata: z.record(z.string(), z.unknown()).optional().describe(
+    "Arbitrary structured fields the caller wants to record alongside the todo."
+  ),
+  id: TodoIdSchema.optional().describe(
+    "Optional explicit id (kebab-case). When omitted, derived from the title."
+  )
+});
+const lucaTodoAddTool = {
+  name: "luca_todo_add",
+  description: 'Create a new todo. Validates inputs server-side and returns a muninn_remember instruction for the agent to execute (delegation pattern \u2014 todos persist in MuninnDB under concept "todo:<id>"). Status defaults to pending; promotion to "done" goes through luca_todo_update.',
+  inputSchema: inputSchema$3,
+  async handler(args, ctx) {
+    const vault = await resolveRepoVault({ cwd: ctx.cwd });
+    let id;
+    try {
+      id = args.id ?? slugFromTitle(args.title);
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: err.message }],
+        isError: true
+      };
+    }
+    const todo = TodoSchema.parse({
+      schemaVersion: 1,
+      id,
+      title: args.title,
+      ...args.body !== void 0 ? { body: args.body } : {},
+      status: args.status,
+      ...args.source !== void 0 ? { source: args.source } : {},
+      ...args.metadata !== void 0 ? { metadata: args.metadata } : {},
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    const instruction = buildMuninnInstruction({
+      tool: "mcp__muninn__muninn_remember",
+      args: {
+        vault,
+        concept: todoConceptFor(id),
+        content: JSON.stringify(todo)
+      },
+      description: `Persist todo "${id}" (status=${todo.status}) to MuninnDB.`
+    });
+    return {
+      content: [
+        { type: "text", text: JSON.stringify(instruction, null, 2) }
+      ]
+    };
+  }
+};
+
+const inputSchema$2 = z.object({
+  status: TodoStatus.optional().describe(
+    "Optional status filter. Applied post-recall by the agent (muninn cannot filter on content metadata)."
+  ),
+  limit: z.number().int().min(1).max(200).default(50).describe("Max todos to recall (range 1\u2013200, default 50).")
+});
+const lucaTodoListTool = {
+  name: "luca_todo_list",
+  description: `List todos from MuninnDB. Returns a muninn_recall instruction with context ["todo:"] in the repo vault. Optional status filter is applied by the agent post-recall (recall returns the todo's JSON content; the agent filters by content.status).`,
+  inputSchema: inputSchema$2,
+  async handler(args, ctx) {
+    const vault = await resolveRepoVault({ cwd: ctx.cwd });
+    const description = args.status ? `Recall up to ${args.limit} todos. Parse each result's content JSON and keep only those where content.status === "${args.status}".` : `Recall up to ${args.limit} todos. Each result's content is JSON conforming to TodoSchema.`;
+    const instruction = buildMuninnInstruction({
+      tool: "mcp__muninn__muninn_recall",
+      args: {
+        vault,
+        context: [TODO_CONCEPT_PREFIX],
+        mode: "balanced",
+        limit: args.limit
+      },
+      description
+    });
+    return {
+      content: [
+        { type: "text", text: JSON.stringify(instruction, null, 2) }
+      ]
+    };
+  }
+};
+
+const inputSchema$1 = z.object({
+  id: TodoIdSchema.describe(
+    "Existing todo id (kebab-case). Used as the muninn concept suffix: todo:<id>."
+  ),
+  title: z.string().min(1).max(200).describe(
+    "Full title of the todo. Pass the existing title unchanged unless renaming."
+  ),
+  body: z.string().max(8192).optional(),
+  status: TodoStatus.describe(
+    `New status. Promoting to "done" requires verificationRef pointing at a met PASS criterion in the active phase's verify.json.`
+  ),
+  source: z.string().max(120).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  verificationRef: VerificationRefSchema.optional().describe(
+    `Required when status === "done". Points at a criterionId in the active phase's verify.json that is met=true with non-empty evidence and parent status=PASS.`
+  )
+});
+const lucaTodoUpdateTool = {
+  name: "luca_todo_update",
+  description: `Update a todo's state. Returns a muninn_remember instruction the agent executes (delegation pattern). Server-side verification-ref guard: transitioning to status="done" requires a verificationRef pointing at a met PASS criterion in the active phase's verify.json.`,
+  inputSchema: inputSchema$1,
+  async handler(args, ctx) {
+    if (args.status === "done") {
+      if (!args.verificationRef) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `luca_todo_update: verificationRef is required when status === "done". Provide { criterionId } pointing at a met PASS criterion in the active phase's verify.json.`
+            }
+          ],
+          isError: true
+        };
+      }
+      const err = await validateVerificationRef({
+        cwd: ctx.cwd,
+        ref: args.verificationRef
+      });
+      if (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `luca_todo_update: ${err.code} \u2014 ${err.message}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+    const todo = TodoSchema.parse({
+      schemaVersion: 1,
+      id: args.id,
+      title: args.title,
+      ...args.body !== void 0 ? { body: args.body } : {},
+      status: args.status,
+      ...args.source !== void 0 ? { source: args.source } : {},
+      ...args.metadata !== void 0 ? { metadata: args.metadata } : {},
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...args.verificationRef !== void 0 ? { verificationRef: args.verificationRef } : {}
+    });
+    const vault = await resolveRepoVault({ cwd: ctx.cwd });
+    const instruction = buildMuninnInstruction({
+      tool: "mcp__muninn__muninn_remember",
+      args: {
+        vault,
+        concept: todoConceptFor(args.id),
+        content: JSON.stringify(todo)
+      },
+      description: `Update todo "${args.id}" (status=${todo.status}).`
+    });
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(instruction, null, 2)
+        }
+      ]
+    };
+  }
+};
+
+const inputSchema = z.object({
+  confirm: z.boolean().default(false).describe(
+    "Must be true to actually perform the reset. Default false so accidental invocations are refused."
+  )
+});
+const lucaWorkflowResetTool = {
+  name: "luca_workflow_reset",
+  description: "Reset .luca/state.json to schema defaults and remove the pipeline lock. Destructive: requires confirm=true. Use when the workflow is wedged or a session ended mid-step and needs a clean restart.",
+  inputSchema,
+  async handler(args, ctx) {
+    if (!args.confirm) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "luca_workflow_reset refused: confirm=true required (destructive operation)."
+          }
+        ],
+        isError: true
+      };
+    }
+    const defaultState = lucaStateSchema.parse({});
+    const statePath = join(ctx.cwd, lucaRootPaths.state);
+    const lockPath = join(ctx.cwd, lucaRootPaths.lock);
+    await writeAtomicFile(
+      statePath,
+      JSON.stringify(defaultState, null, 2) + "\n"
+    );
+    await rm(lockPath, { force: true });
+    return {
+      content: [
+        {
+          type: "text",
+          text: `reset ${lucaRootPaths.state} to defaults; pipeline lock cleared if present.`
+        }
+      ]
+    };
+  }
+};
+
+async function runWriteHandler(command, tool, rawArgs) {
+  const cwd = process.cwd();
+  const allowedPhases = WRITE_COMMAND_PHASES[command];
+  if (allowedPhases && allowedPhases.length > 0) {
+    const state = await loadCurrentState({ cwd });
+    if (!allowedPhases.includes(state.pipelineStep)) {
+      console.error(
+        `luca ${command}: refused \u2014 current pipelineStep is '${state.pipelineStep}', but this command is only allowed in: [${allowedPhases.join(", ")}].`
+      );
+      process.exit(1);
+    }
+  }
+  const parsed = tool.inputSchema.safeParse(rawArgs);
+  if (!parsed.success) {
+    console.error(
+      `luca ${command}: invalid arguments \u2014 ${parsed.error.issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`).join("; ")}`
+    );
+    process.exit(1);
+  }
+  let result;
+  try {
+    result = await tool.handler(parsed.data, { cwd });
+  } catch (err) {
+    console.error(
+      `luca ${command}: handler error \u2014 ${err instanceof Error ? err.message : String(err)}`
+    );
+    process.exit(1);
+  }
+  const text = result.content.filter((block) => block.type === "text").map((block) => block.text).join("\n");
+  if (result.isError) {
+    console.error(text);
+    process.exit(1);
+  }
+  console.log(text);
+  process.exit(0);
+}
+async function readJsonPayload(command, filePath) {
+  let raw;
+  try {
+    raw = await readFile(filePath, "utf-8");
+  } catch (err) {
+    console.error(
+      `luca ${command}: could not read --file '${filePath}' \u2014 ${err instanceof Error ? err.message : String(err)}`
+    );
+    process.exit(1);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    console.error(
+      `luca ${command}: --file '${filePath}' is not valid JSON \u2014 ${err instanceof Error ? err.message : String(err)}`
+    );
+    process.exit(1);
+  }
+}
+
+export { lucaStateReadTool as a, lucaPhaseCurrentTool as b, readJsonPayload as c, lucaRoadmapReadTool as d, lucaRoadmapCreateTool as e, lucaPreferencesReadTool as f, lucaPreferencesWriteTool as g, lucaTodoUpdateTool as h, lucaTodoListTool as i, lucaTodoAddTool as j, lucaPrReviewDetectConvergenceTool as k, lucaStateAdvanceTool as l, lucaPrReviewFilterStaleTool as m, lucaPrReviewRegressionCheckTool as n, lucaRepoCleanupApplyTool as o, lucaChecksRunTool as p, lucaBranchGuardTool as q, runWriteHandler as r, lucaWorkflowResetTool as s, lucaConfidenceLogTool as t };