@picoai/tickets 0.3.0 → 0.4.0

package/src/cli.js

@@ -12,6 +12,7 @@ import {
   FORMAT_VERSION,
   FORMAT_VERSION_URL,
   GRAPH_VIEW_VALUES,
+  LIST_SORT_VALUES,
   PLANNING_NODE_TYPES,
   PRIORITY_VALUES,
   RESOLUTION_VALUES,
@@ -19,11 +20,12 @@ import {
 } from "./lib/constants.js";
 import { deriveActiveClaim, loadClaimEvents } from "./lib/claims.js";
 import { loadWorkflowProfile, validateRepoConfig } from "./lib/config.js";
+import { invalidatePlanningIndex, loadPlanningSnapshot, refreshPlanningIndexIfPresent } from "./lib/index.js";
 import { listTickets } from "./lib/listing.js";
-import { buildGraphData, buildPlanSummary, buildPlanningSnapshot } from "./lib/planning.js";
+import { buildGraphData, buildPlanSummary } from "./lib/planning.js";
 import { syncRepoConfig, syncRepoSkill } from "./lib/projections.js";
 import { applyRepairs, loadIssuesFile, runInteractive } from "./lib/repair.js";
-import { collectTicketPaths, validateRunLog, validateTicket } from "./lib/validation.js";
+import { collectTicketPaths, validatePlanningTopology, validateRunLog, validateTicket } from "./lib/validation.js";
 import {
   appendJsonl,
   ensureDir,
@@ -94,6 +96,61 @@ function normalizeContextItems(values) {
   return values.map((value) => String(value).trim()).filter(Boolean);
 }
 
+function groupIdSignature(groupIds = []) {
+  return [...groupIds].sort((a, b) => a.localeCompare(b)).join(",");
+}
+
+function resolveGroupTargets(groupIds, snapshot) {
+  const targets = [];
+  for (const groupId of groupIds ?? []) {
+    const row = snapshot.nodesById.get(groupId);
+    if (!row) {
+      throw new Error(`Unknown --group-id target: ${groupId}`);
+    }
+    if (!["group", "checkpoint"].includes(row.planning.node_type)) {
+      throw new Error(`--group-id must reference a group or checkpoint ticket: ${groupId}`);
+    }
+    targets.push(row);
+  }
+  return targets;
+}
+
+function inferInheritedScalar(groupTargets, key, optionName) {
+  const values = [...new Set(groupTargets.map((row) => row.planning[key]).filter((value) => value))];
+  if (values.length > 1) {
+    throw new Error(`Cannot infer --${optionName}; referenced groups disagree.`);
+  }
+  return values[0] ?? null;
+}
+
+function inferNextRank(snapshot, planning) {
+  if (!planning.lane) {
+    return null;
+  }
+
+  const signature = groupIdSignature(planning.group_ids);
+  let maxRank = 0;
+  for (const row of snapshot.rows) {
+    if (row.planning.node_type !== planning.node_type) {
+      continue;
+    }
+    if (groupIdSignature(row.planning.group_ids) !== signature) {
+      continue;
+    }
+    if (row.planning.lane !== planning.lane) {
+      continue;
+    }
+    if ((row.planning.horizon ?? null) !== (planning.horizon ?? null)) {
+      continue;
+    }
+    if (Number.isInteger(row.planning.rank) && row.planning.rank > maxRank) {
+      maxRank = row.planning.rank;
+    }
+  }
+
+  return maxRank + 1;
+}
+
 function printIssues(issues) {
   for (const issue of issues) {
     const location = issue.ticket_path ?? issue.log ?? issue.config_path ?? "";
@@ -266,7 +323,17 @@ function renderMermaid(graph, includeRelated, timestamp, view) {
     const nodeRef = `n${idx}`;
     nodeIds.set(node.id, nodeRef);
     const title = (node.title || node.id).replaceAll('"', '\\"');
-    const label = `${title}\\n(${node.id})`;
+    const metadata = [
+      `status=${node.status || "todo"}`,
+      `type=${node.planning.node_type ?? ""}`,
+      `lane=${node.planning.lane ?? "-"}`,
+      `rank=${node.planning.rank ?? "-"}`,
+      `horizon=${node.planning.horizon ?? "-"}`,
+    ];
+    if (node.resolution) {
+      metadata.push(`resolution=${node.resolution}`);
+    }
+    const label = `${title}\\n(${node.id})\\n${metadata.join("\\n")}`;
     const status = (node.status || "todo").toLowerCase();
     lines.push(`  ${nodeRef}["${label}"]:::status_${status}`);
     lines.push(`  click ${nodeRef} "/.tickets/${node.id}/ticket.md" "_blank"`);
@@ -314,7 +381,17 @@ function renderDot(graph, includeRelated) {
     nodeIds.set(node.id, nodeRef);
     const status = (node.status || "todo").toLowerCase();
     const color = colors[status] ?? colors.todo;
-    const label = `${node.title || node.id}\\n(${node.id})\\n${status}`;
+    const metadata = [
+      `status=${status}`,
+      `type=${node.planning.node_type ?? ""}`,
+      `lane=${node.planning.lane ?? "-"}`,
+      `rank=${node.planning.rank ?? "-"}`,
+      `horizon=${node.planning.horizon ?? "-"}`,
+    ];
+    if (node.resolution) {
+      metadata.push(`resolution=${node.resolution}`);
+    }
+    const label = `${node.title || node.id}\\n(${node.id})\\n${metadata.join("\\n")}`;
     lines.push(
       `  ${nodeRef} [label="${label}", fillcolor="${color}", URL="/.tickets/${node.id}/ticket.md", target="_blank"];`,
     );
@@ -349,6 +426,14 @@ function renderJson(graph, includeRelated) {
       priority: node.priority,
       owner: node.owner,
       mode: node.mode,
+      node_type: node.planning.node_type,
+      group_ids: node.planning.group_ids,
+      lane: node.planning.lane,
+      rank: node.planning.rank,
+      horizon: node.planning.horizon,
+      precedes: node.planning.precedes,
+      resolution: node.resolution,
+      ready: node.ready,
       href: `/.tickets/${node.id}/ticket.md`,
     })),
   };
@@ -967,8 +1052,8 @@ async function cmdInit(options) {
   const versionDir = path.join(repoBaseDir, "version");
   ensureDir(versionDir);
 
-  const currentSpecPath = path.join(versionDir, "20260317-tickets-spec.md");
-  writeTemplateFile(currentSpecPath, path.join(".tickets", "spec", "version", "20260317-tickets-spec.md"), apply);
+  const currentSpecPath = path.join(versionDir, "20260317-2-tickets-spec.md");
+  writeTemplateFile(currentSpecPath, path.join(".tickets", "spec", "version", "20260317-2-tickets-spec.md"), apply);
 
   const previousCurrentSpecPath = path.join(versionDir, "20260311-tickets-spec.md");
   writeTemplateFile(
@@ -987,6 +1072,7 @@ async function cmdInit(options) {
     generateExampleTickets();
   }
 
+  invalidatePlanningIndex();
   process.stdout.write("Initialized.\n");
   return 0;
 }
@@ -994,9 +1080,40 @@ async function cmdInit(options) {
 async function cmdNew(options) {
   ensureDir(ticketsDir());
   const profile = loadWorkflowProfile();
+  const snapshot = loadPlanningSnapshot({ persist: false });
   const ticketId = newUuidv7().toLowerCase();
   const ticketDir = path.join(ticketsDir(), ticketId);
   ensureDir(path.join(ticketDir, "logs"));
+  const groupIds = options.groupIds?.length ? options.groupIds : [];
+  const groupTargets = resolveGroupTargets(groupIds, snapshot);
+
+  let lane = options.lane ?? null;
+  if (lane === null && groupTargets.length > 0) {
+    lane = inferInheritedScalar(groupTargets, "lane", "lane");
+  }
+  if (lane === null) {
+    lane = profile.defaults?.planning?.lane ?? null;
+  }
+
+  let horizon = options.horizon ?? null;
+  if (horizon === null && groupTargets.length > 0) {
+    horizon = inferInheritedScalar(groupTargets, "horizon", "horizon");
+  }
+  if (horizon === null) {
+    horizon = profile.defaults?.planning?.horizon ?? null;
+  }
+
+  const planning = {
+    node_type: options.nodeType || profile.defaults?.planning?.node_type || "work",
+    group_ids: groupIds,
+    lane,
+    rank: options.rank ?? null,
+    horizon,
+    precedes: options.precedes?.length ? options.precedes : [],
+  };
+  if (planning.rank === null && planning.lane) {
+    planning.rank = inferNextRank(snapshot, planning);
+  }
 
   const frontMatter = {
     id: ticketId,
@@ -1050,14 +1167,7 @@ async function cmdNew(options) {
   if (options.verificationCommands?.length) {
     frontMatter.verification = { commands: options.verificationCommands };
   }
-  frontMatter.planning = {
-    node_type: options.nodeType || profile.defaults?.planning?.node_type || "work",
-    group_ids: options.groupIds?.length ? options.groupIds : [],
-    lane: options.lane ?? null,
-    rank: options.rank ?? null,
-    horizon: options.horizon ?? null,
-    precedes: options.precedes?.length ? options.precedes : [],
-  };
+  frontMatter.planning = planning;
   if (options.resolution) {
     frontMatter.resolution = options.resolution;
   }
@@ -1079,12 +1189,14 @@ async function cmdNew(options) {
   ].join("\n");
 
   writeTicket(path.join(ticketDir, "ticket.md"), frontMatter, body);
+  refreshPlanningIndexIfPresent();
   process.stdout.write(`${ticketId}\n`);
   return 0;
 }
 
 async function cmdValidate(options) {
   const ticketPaths = collectTicketPaths(options.ticket);
+  const allTicketPaths = collectTicketPaths(null);
   const issues = [];
 
   issues.push(...validateRepoConfig(repoRoot()));
@@ -1109,6 +1221,8 @@ async function cmdValidate(options) {
     }
   }
 
+  issues.push(...validatePlanningTopology(ticketPaths, allTicketPaths));
+
   issues.forEach((issue, index) => {
     if (!issue.id) {
       issue.id = `I${String(index + 1).padStart(4, "0")}`;
@@ -1171,6 +1285,7 @@ async function cmdStatus(options) {
 
   const logPath = path.join(path.dirname(ticketPath), "logs", `${runStarted}-${runId}.jsonl`);
   appendJsonl(logPath, entry);
+  refreshPlanningIndexIfPresent();
 
   return 0;
 }
@@ -1230,25 +1345,41 @@ async function cmdLog(options) {
 
   const logPath = path.join(path.dirname(ticketPath), "logs", `${runStarted}-${runId}.jsonl`);
   appendJsonl(logPath, entry);
+  refreshPlanningIndexIfPresent();
   return 0;
 }
 
+function renderTable(headers, rows) {
+  process.stdout.write(`${headers.join(" | ")}\n`);
+  for (const row of rows) {
+    process.stdout.write(`${headers.map((key) => String(row[key] ?? "")).join(" | ")}\n`);
+  }
+}
+
 async function cmdList(options) {
-  const rows = listTickets({
-    status: options.status,
-    priority: options.priority,
-    mode: options.mode,
-    owner: options.owner,
-    label: options.label,
-    text: options.text,
-    nodeType: options.nodeType,
-    group: options.group,
-    lane: options.lane,
-    horizon: options.horizon,
-    claimed: Boolean(options.claimed),
-    claimedBy: options.claimedBy,
-    ready: Boolean(options.ready),
-  });
+  const snapshot = loadPlanningSnapshot();
+  const rows = listTickets(
+    snapshot,
+    {
+      status: options.status,
+      priority: options.priority,
+      mode: options.mode,
+      owner: options.owner,
+      label: options.label,
+      text: options.text,
+      nodeType: options.nodeType,
+      group: options.group,
+      lane: options.lane,
+      horizon: options.horizon,
+      claimed: Boolean(options.claimed),
+      claimedBy: options.claimedBy,
+      ready: Boolean(options.ready),
+    },
+    {
+      sortBy: options.sort,
+      reverse: Boolean(options.reverse),
+    },
+  );
 
   if (options.json) {
     process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
@@ -1270,20 +1401,18 @@ async function cmdList(options) {
     "rank",
     "horizon",
     "ready",
+    "claim",
     "owner",
-    "mode",
     "last_updated",
   ];
-  process.stdout.write(`${headers.join(" | ")}\n`);
-  for (const row of rows) {
-    process.stdout.write(`${headers.map((key) => String(row[key] ?? "")).join(" | ")}\n`);
-  }
+  renderTable(headers, rows.map((row) => ({ ...row, claim: row.claim_summary })));
 
   return 0;
 }
 
 async function cmdPlan(options) {
-  const summary = buildPlanSummary({
+  const snapshot = loadPlanningSnapshot();
+  const summary = buildPlanSummary(snapshot, {
     group: options.group ?? options.root ?? null,
     horizon: options.horizon ?? null,
   });
@@ -1293,19 +1422,41 @@ async function cmdPlan(options) {
     return 0;
   }
 
-  process.stdout.write("Ready queue\n");
-  for (const row of summary.ready) {
-    process.stdout.write(
-      `${row.id} | ${row.title} | lane=${row.lane ?? ""} | rank=${row.rank ?? ""} | horizon=${row.horizon ?? ""}\n`,
-    );
-  }
-  process.stdout.write("\nGroups\n");
-  for (const group of summary.groups) {
+  const itemHeaders = [
+    "id",
+    "title",
+    "status",
+    "priority",
+    "node_type",
+    "lane",
+    "rank",
+    "horizon",
+    "claim",
+    "owner",
+  ];
+  const groupHeaders = ["id", "title", "node_type", "lane", "rank", "horizon", "rollup_summary"];
+
+  const activeRows = summary.active.map((row) => ({ ...row }));
+  const blockedRows = summary.blocked.map((row) => ({
+    ...row,
+    blocked_by: JSON.stringify(row.blocked_by),
+  }));
+  const groupRows = summary.groups.map((group) => {
     const rollup = group.rollup ?? {};
-    process.stdout.write(
-      `${group.id} | ${group.title} | ${group.node_type} | ${rollup.done_completed ?? 0}/${rollup.active_leaf ?? 0} complete | merged=${rollup.merged ?? 0} | dropped=${rollup.dropped ?? 0}\n`,
-    );
-  }
+    return {
+      ...group,
+      rollup_summary: `${rollup.done_completed ?? 0}/${rollup.active_leaf ?? 0} complete | merged=${rollup.merged ?? 0} | dropped=${rollup.dropped ?? 0}`,
+    };
+  });
+
+  process.stdout.write("Ready\n");
+  renderTable(itemHeaders, summary.ready.map((row) => ({ ...row, claim: row.claim_summary })));
+  process.stdout.write("\nIn Progress\n");
+  renderTable(itemHeaders, activeRows.map((row) => ({ ...row, claim: row.claim_summary })));
+  process.stdout.write("\nBlocked\n");
+  renderTable([...itemHeaders, "blocked_by"], blockedRows.map((row) => ({ ...row, claim: row.claim_summary })));
+  process.stdout.write("\nGroups / Checkpoints\n");
+  renderTable(groupHeaders, groupRows);
 
   return 0;
 }
@@ -1391,6 +1542,7 @@ async function cmdClaim(options) {
   }
 
   appendJsonl(path.join(logsDir, `${runStarted}-${runId}.jsonl`), entry);
+  refreshPlanningIndexIfPresent();
   process.stdout.write(`${summary}\n`);
   return 0;
 }
@@ -1466,7 +1618,7 @@ async function cmdRepair(options) {
 }
 
 async function cmdGraph(options) {
-  const snapshot = buildPlanningSnapshot();
+  const snapshot = loadPlanningSnapshot();
   const graph = buildGraphData(snapshot, {
     ticket: options.ticket,
     view: options.view,
@@ -1703,8 +1855,13 @@ export async function run(argv = process.argv.slice(2)) {
     .option("--claimed", "Only show claimed tickets")
     .option("--claimed-by <actorId>")
     .option("--ready", "Only show ready tickets")
+    .option("--sort <sort>", "ready | priority | lane | rank | updated | title")
+    .option("--reverse", "Reverse the sort order")
     .option("--json", "JSON output")
     .action(async (options) => {
+      if (options.sort && !LIST_SORT_VALUES.includes(options.sort)) {
+        throw new Error(`Invalid --sort. Use one of: ${LIST_SORT_VALUES.join(", ")}`);
+      }
       process.exitCode = await cmdList(options);
     });
 

package/src/lib/config.js

@@ -68,6 +68,8 @@ export function buildInitialRepoConfig(profile = loadDefaultProfile()) {
     defaults: {
       planning: {
         node_type: profile.defaults?.planning?.node_type ?? "work",
+        lane: profile.defaults?.planning?.lane ?? null,
+        horizon: profile.defaults?.planning?.horizon ?? null,
       },
       claims: {
         ttl_minutes: profile.defaults?.claims?.ttl_minutes ?? DEFAULT_CLAIM_TTL_MINUTES,
@@ -133,6 +135,18 @@ export function validateRepoConfig(root = repoRoot()) {
     });
   }
 
+  for (const key of ["lane", "horizon"]) {
+    const value = config.defaults?.planning?.[key];
+    if (value !== undefined && value !== null && typeof value !== "string") {
+      issues.push({
+        severity: "error",
+        code: "CONFIG_DEFAULT_PLANNING_SCALAR_INVALID",
+        message: `defaults.planning.${key} must be a string or null`,
+        config_path: configPath,
+      });
+    }
+  }
+
   const ttlMinutes = config.defaults?.claims?.ttl_minutes;
   if (ttlMinutes !== undefined && (!Number.isInteger(ttlMinutes) || ttlMinutes <= 0)) {
     issues.push({

package/src/lib/constants.js

@@ -1,6 +1,6 @@
 export const BASE_DIR = ".tickets/spec";
 export const FORMAT_VERSION = 3;
-export const FORMAT_VERSION_URL = "version/20260317-tickets-spec.md";
+export const FORMAT_VERSION_URL = "version/20260317-2-tickets-spec.md";
 
 export const STATUS_VALUES = ["todo", "doing", "blocked", "done", "canceled"];
 export const PRIORITY_VALUES = ["low", "medium", "high", "critical"];
@@ -11,3 +11,6 @@ export const CLAIM_ACTION_VALUES = ["acquire", "renew", "release", "override"];
 export const WORKFLOW_MODE_VALUES = ["auto", "doc_first", "skill_first"];
 export const GRAPH_VIEW_VALUES = ["dependency", "sequence", "portfolio", "all"];
 export const DEFAULT_CLAIM_TTL_MINUTES = 60;
+export const LIST_SORT_VALUES = ["ready", "priority", "lane", "rank", "updated", "title"];
+export const PLANNING_INDEX_FORMAT_ID = "0195a1b7-4a17-7c2e-8db2-4d5cb0f0d642";
+export const PLANNING_INDEX_FORMAT_LABEL = "planning-index-2026-03-17";

package/src/lib/index.js

@@ -0,0 +1,241 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  FORMAT_VERSION,
+  FORMAT_VERSION_URL,
+  PLANNING_INDEX_FORMAT_ID,
+  PLANNING_INDEX_FORMAT_LABEL,
+} from "./constants.js";
+import { loadClaimEvents, deriveActiveClaim } from "./claims.js";
+import { loadWorkflowProfile, repoConfigPath } from "./config.js";
+import { buildPlanningSnapshotFromRows, normalizePlanning } from "./planning.js";
+import { collectTicketPaths } from "./validation.js";
+import { ensureDir, loadTicket, readJsonl, repoRoot, ticketsDir } from "./util.js";
+
+function fileSignature(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  const stat = fs.statSync(filePath);
+  return `${Math.trunc(stat.mtimeMs)}:${stat.size}`;
+}
+
+function listLogFiles(logsDir) {
+  if (!fs.existsSync(logsDir)) {
+    return [];
+  }
+
+  return fs
+    .readdirSync(logsDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+function computeLastUpdated(logsDir) {
+  let latest = "";
+
+  for (const name of listLogFiles(logsDir)) {
+    const logPath = path.join(logsDir, name);
+    for (const entry of readJsonl(logPath)) {
+      const ts = entry.ts;
+      if (typeof ts === "string" && (latest === "" || ts > latest)) {
+        latest = ts;
+      }
+    }
+  }
+
+  return latest;
+}
+
+function ticketPathsForRoot(root = repoRoot()) {
+  const previous = process.cwd();
+  try {
+    process.chdir(root);
+    return collectTicketPaths(null);
+  } finally {
+    process.chdir(previous);
+  }
+}
+
+function collectSourceState(root = repoRoot()) {
+  const configPath = repoConfigPath(root);
+  const ticketStates = ticketPathsForRoot(root)
+    .map((ticketPath) => {
+      const ticketDir = path.dirname(ticketPath);
+      const logsDir = path.join(ticketDir, "logs");
+      const logFiles = listLogFiles(logsDir);
+      return {
+        id: path.basename(ticketDir),
+        ticket_path: path.relative(root, ticketPath),
+        ticket_signature: fileSignature(ticketPath),
+        log_count: logFiles.length,
+        logs: logFiles.map((name) => ({
+          name,
+          signature: fileSignature(path.join(logsDir, name)),
+        })),
+      };
+    })
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  return {
+    config_fingerprint: fileSignature(configPath),
+    ticket_count: ticketStates.length,
+    tickets: ticketStates,
+  };
+}
+
+function buildRows(root = repoRoot(), profile = loadWorkflowProfile(root)) {
+  const rows = [];
+
+  for (const ticketPath of ticketPathsForRoot(root)) {
+    try {
+      const [frontMatter, body] = loadTicket(ticketPath);
+      const ticketDir = path.dirname(ticketPath);
+      const logsDir = path.join(ticketDir, "logs");
+      const activeClaim = deriveActiveClaim(loadClaimEvents(logsDir));
+
+      rows.push({
+        id: frontMatter.id ?? "",
+        title: frontMatter.title ?? "",
+        status: frontMatter.status ?? "",
+        priority: frontMatter.priority ?? "",
+        owner: frontMatter.assignment?.owner ?? null,
+        mode: frontMatter.assignment?.mode ?? null,
+        labels: Array.isArray(frontMatter.labels)
+          ? frontMatter.labels.filter((label) => typeof label === "string")
+          : [],
+        body: body ?? "",
+        path: ticketPath,
+        dependencies: Array.isArray(frontMatter.dependencies) ? frontMatter.dependencies : [],
+        blocks: Array.isArray(frontMatter.blocks) ? frontMatter.blocks : [],
+        related: Array.isArray(frontMatter.related) ? frontMatter.related : [],
+        planning: normalizePlanning(frontMatter, profile),
+        resolution: frontMatter.resolution ?? null,
+        active_claim: activeClaim,
+        last_updated: computeLastUpdated(logsDir),
+      });
+    } catch {
+      // Invalid tickets are surfaced by `validate`; derived views skip them.
+    }
+  }
+
+  return rows;
+}
+
+function indexPath(root = repoRoot()) {
+  return path.join(root, ".tickets", "derived", "planning-index.json");
+}
+
+function serializeMap(map) {
+  return Object.fromEntries([...map.entries()].map(([key, value]) => [key, [...value]]));
+}
+
+function buildIndexDocument(root = repoRoot()) {
+  const profile = loadWorkflowProfile(root);
+  const rows = buildRows(root, profile);
+  const snapshot = buildPlanningSnapshotFromRows(rows, profile);
+
+  return {
+    index_format_id: PLANNING_INDEX_FORMAT_ID,
+    index_format_label: PLANNING_INDEX_FORMAT_LABEL,
+    tool: {
+      format_version: FORMAT_VERSION,
+      format_version_url: FORMAT_VERSION_URL,
+    },
+    source_state: collectSourceState(root),
+    profile,
+    rows: snapshot.rows,
+    predecessors_by_id: serializeMap(snapshot.predecessorsById),
+    members_by_group: serializeMap(snapshot.membersByGroup),
+  };
+}
+
+function readIndex(root = repoRoot()) {
+  const outPath = indexPath(root);
+  if (!fs.existsSync(outPath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(outPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function isFresh(index, root = repoRoot()) {
+  if (!index) {
+    return false;
+  }
+  if (index.index_format_id !== PLANNING_INDEX_FORMAT_ID) {
+    return false;
+  }
+  if (index.tool?.format_version !== FORMAT_VERSION) {
+    return false;
+  }
+  if (index.tool?.format_version_url !== FORMAT_VERSION_URL) {
+    return false;
+  }
+
+  const currentState = collectSourceState(root);
+  return JSON.stringify(index.source_state ?? null) === JSON.stringify(currentState);
+}
+
+export function planningIndexPath(root = repoRoot()) {
+  return indexPath(root);
+}
+
+export function invalidatePlanningIndex(root = repoRoot()) {
+  const outPath = indexPath(root);
+  if (fs.existsSync(outPath)) {
+    fs.unlinkSync(outPath);
+  }
+}
+
+export function rebuildPlanningIndex(root = repoRoot()) {
+  const outPath = indexPath(root);
+  ensureDir(path.dirname(outPath));
+  const index = buildIndexDocument(root);
+  fs.writeFileSync(outPath, `${JSON.stringify(index, null, 2)}\n`);
+  return buildPlanningSnapshotFromRows(index.rows, index.profile);
+}
+
+export function refreshPlanningIndexIfPresent(root = repoRoot()) {
+  const outPath = indexPath(root);
+  if (!fs.existsSync(outPath)) {
+    return null;
+  }
+
+  try {
+    return rebuildPlanningIndex(root);
+  } catch {
+    invalidatePlanningIndex(root);
+    return null;
+  }
+}
+
+export function loadPlanningSnapshot(options = {}) {
+  const root = options.root ?? repoRoot();
+  const persist = options.persist ?? true;
+  const existing = readIndex(root);
+  if (existing && isFresh(existing, root)) {
+    return buildPlanningSnapshotFromRows(existing.rows ?? [], existing.profile ?? loadWorkflowProfile(root));
+  }
+
+  if (!persist) {
+    const profile = loadWorkflowProfile(root);
+    return buildPlanningSnapshotFromRows(buildRows(root, profile), profile);
+  }
+
+  return rebuildPlanningIndex(root);
+}
+
+export function currentSourceState(root = repoRoot()) {
+  return collectSourceState(root);
+}
+
+export function planningIndexExists(root = repoRoot()) {
+  return fs.existsSync(indexPath(root));
+}