@picoai/tickets 0.2.0 → 0.4.0

package/src/cli.js

@@ -8,14 +8,24 @@ import yaml from "yaml";
 import {
   ASSIGNMENT_MODE_VALUES,
   BASE_DIR,
+  DEFAULT_CLAIM_TTL_MINUTES,
   FORMAT_VERSION,
   FORMAT_VERSION_URL,
+  GRAPH_VIEW_VALUES,
+  LIST_SORT_VALUES,
+  PLANNING_NODE_TYPES,
   PRIORITY_VALUES,
+  RESOLUTION_VALUES,
   STATUS_VALUES,
 } 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 } 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,
@@ -86,9 +96,64 @@ 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 ?? "";
+    const location = issue.ticket_path ?? issue.log ?? issue.config_path ?? "";
     process.stdout.write(`${String(issue.severity ?? "?").toUpperCase()}: ${issue.message} (${location})\n`);
   }
 }
@@ -236,90 +301,7 @@ function buildRepairsFromIssues(issues, options = {}) {
   return repairs;
 }
 
-function loadNodeById(ticketId) {
-  const ticketPath = path.join(ticketsDir(), ticketId, "ticket.md");
-  if (fs.existsSync(ticketPath)) {
-    try {
-      const [frontMatter] = loadTicket(ticketPath);
-      return {
-        id: ticketId,
-        title: frontMatter.title ?? ticketId,
-        status: frontMatter.status ?? "",
-        priority: frontMatter.priority,
-        owner: frontMatter.assignment?.owner,
-        mode: frontMatter.assignment?.mode,
-        path: ticketPath,
-      };
-    } catch {
-      // ignore
-    }
-  }
-
-  return {
-    id: ticketId,
-    title: ticketId,
-    status: "",
-    path: `/.tickets/${ticketId}/ticket.md`,
-  };
-}
-
-function loadTicketGraph(ticketRef) {
-  const nodes = new Map();
-  const edges = [];
-  const paths = collectTicketPaths(ticketRef);
-  let rootId = null;
-
-  for (const ticketPath of paths) {
-    const [frontMatter] = loadTicket(ticketPath);
-    const ticketId = frontMatter.id;
-    if (!ticketId) {
-      continue;
-    }
-
-    if (ticketRef && !rootId) {
-      rootId = ticketId;
-    }
-
-    nodes.set(ticketId, {
-      id: ticketId,
-      title: frontMatter.title ?? "",
-      status: frontMatter.status ?? "",
-      priority: frontMatter.priority,
-      owner: frontMatter.assignment?.owner,
-      mode: frontMatter.assignment?.mode,
-      path: ticketPath,
-    });
-
-    for (const dependency of frontMatter.dependencies ?? []) {
-      if (!nodes.has(dependency)) {
-        nodes.set(dependency, loadNodeById(dependency));
-      }
-      edges.push({ type: "dependency", from: dependency, to: ticketId });
-    }
-
-    for (const blocked of frontMatter.blocks ?? []) {
-      if (!nodes.has(blocked)) {
-        nodes.set(blocked, loadNodeById(blocked));
-      }
-      edges.push({ type: "blocks", from: ticketId, to: blocked });
-    }
-
-    for (const related of frontMatter.related ?? []) {
-      if (!nodes.has(related)) {
-        nodes.set(related, loadNodeById(related));
-      }
-      edges.push({ type: "related", from: ticketId, to: related });
-    }
-  }
-
-  return {
-    nodes: [...nodes.values()],
-    edges,
-    root_id: rootId,
-  };
-}
-
-function renderMermaid(graph, includeRelated, timestamp) {
+function renderMermaid(graph, includeRelated, timestamp, view) {
   const statusClasses = {
     todo: "fill:#ddd,stroke:#999",
     doing: "fill:#d0e7ff,stroke:#3b82f6",
@@ -329,7 +311,7 @@ function renderMermaid(graph, includeRelated, timestamp) {
   };
 
   const lines = [
-    "# Ticket dependency graph",
+    `# Ticket ${view} graph`,
     `_Generated at ${timestamp} UTC_`,
     "",
     "```mermaid",
@@ -341,7 +323,17 @@ function renderMermaid(graph, includeRelated, timestamp) {
     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"`);
@@ -356,7 +348,8 @@ function renderMermaid(graph, includeRelated, timestamp) {
     if (!source || !target) {
       continue;
     }
-    lines.push(`  ${source} --> ${target}`);
+    const connector = edge.type === "contains" ? "-.->" : "-->";
+    lines.push(`  ${source} ${connector}|${edge.type}| ${target}`);
   }
 
   for (const [status, style] of Object.entries(statusClasses)) {
@@ -388,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"];`,
     );
@@ -403,8 +406,8 @@ function renderDot(graph, includeRelated) {
     if (!source || !target) {
       continue;
     }
-    const style = edge.type === "related" ? "dashed" : "solid";
-    lines.push(`  ${source} -> ${target} [style=${style}];`);
+    const style = ["related", "contains"].includes(edge.type) ? "dashed" : "solid";
+    lines.push(`  ${source} -> ${target} [style=${style}, label="${edge.type}"];`);
   }
 
   lines.push("}");
@@ -423,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`,
     })),
   };
@@ -727,6 +738,7 @@ function generateExampleTickets() {
       status: "doing",
       priority: "high",
       labels: ["epic", "planning"],
+      planning: { node_type: "group", lane: "build", rank: 1, horizon: "current" },
       assignment: { mode: "mixed", owner: "team:core" },
       related: ["backend", "frontend", "testing", "docs", "release"],
       agent_limits: {
@@ -760,6 +772,7 @@ function generateExampleTickets() {
       status: "doing",
       priority: "high",
       labels: ["backend", "api"],
+      planning: { node_type: "work", group_ids: ["parent"], lane: "build", rank: 1, horizon: "current", precedes: ["frontend", "testing"] },
       assignment: { mode: "agent_only", owner: "agent:codex" },
       dependencies: ["parent"],
       blocks: ["frontend", "testing", "release"],
@@ -782,6 +795,11 @@ function generateExampleTickets() {
           created_from: "parent",
           context: ["Acceptance criteria from parent", "Release target"],
         },
+        {
+          summary: "Agent claimed backend work.",
+          event_type: "claim",
+          claim: { action: "acquire", holder_id: "agent:codex", holder_type: "agent", ttl_minutes: 60 },
+        },
       ],
     },
     {
@@ -790,6 +808,7 @@ function generateExampleTickets() {
       status: "todo",
       priority: "medium",
       labels: ["frontend", "ui"],
+      planning: { node_type: "work", group_ids: ["parent"], lane: "build", rank: 2, horizon: "current" },
       dependencies: ["backend"],
       related: ["testing"],
       verification: { commands: ["npm test", "npm run lint"] },
@@ -813,6 +832,7 @@ function generateExampleTickets() {
       status: "todo",
       priority: "medium",
       labels: ["qa"],
+      planning: { node_type: "work", group_ids: ["parent"], lane: "verify", rank: 1, horizon: "current" },
       dependencies: ["backend", "frontend"],
       verification: { commands: ["npm test"] },
       body: {
@@ -835,6 +855,7 @@ function generateExampleTickets() {
       status: "todo",
       priority: "low",
       labels: ["docs"],
+      planning: { node_type: "work", group_ids: ["parent"], lane: "launch", rank: 2, horizon: "next" },
       dependencies: ["testing"],
       verification: { commands: ["npm run lint:docs"] },
       body: {
@@ -857,6 +878,7 @@ function generateExampleTickets() {
       status: "todo",
       priority: "high",
       labels: ["release"],
+      planning: { node_type: "checkpoint", group_ids: ["parent"], lane: "launch", rank: 1, horizon: "current" },
       dependencies: ["testing"],
       blocks: ["bugfix"],
       verification: { commands: ["npx @picoai/tickets validate"] },
@@ -876,9 +898,11 @@ function generateExampleTickets() {
     {
       key: "bugfix",
       title: "Bugfix: address regression found during Alpha",
-      status: "blocked",
+      status: "canceled",
       priority: "high",
       labels: ["bug", "regression"],
+      planning: { node_type: "work", group_ids: ["parent"], lane: "build", rank: 3, horizon: "current" },
+      resolution: "dropped",
       dependencies: ["backend"],
       related: ["testing"],
       verification: { commands: ["npm test"] },
@@ -889,9 +913,9 @@ function generateExampleTickets() {
       },
       logs: [
         {
-          summary: "Blocked until backend fix lands.",
+          summary: "Dropped after mitigation in backend workstream.",
           context: ["Regression repro identified", "Awaiting backend deployment before retry"],
-          blockers: ["Awaiting backend deployment"],
+          decisions: ["Folded remediation into backend ticket"],
         },
       ],
     },
@@ -920,6 +944,16 @@ function generateExampleTickets() {
     if (spec.assignment) {
       frontMatter.assignment = spec.assignment;
     }
+    if (spec.planning) {
+      frontMatter.planning = {
+        ...spec.planning,
+        group_ids: spec.planning.group_ids?.map((value) => ids[value]) ?? spec.planning.group_ids,
+        precedes: spec.planning.precedes?.map((value) => ids[value]) ?? spec.planning.precedes,
+      };
+    }
+    if (spec.resolution) {
+      frontMatter.resolution = spec.resolution;
+    }
     for (const relationshipKey of ["dependencies", "blocks", "related"]) {
       if (spec[relationshipKey]) {
         frontMatter[relationshipKey] = spec[relationshipKey].map((value) => ids[value]);
@@ -959,12 +993,13 @@ function generateExampleTickets() {
         actor_type: "agent",
         actor_id: "tickets-init",
         summary: logSpec.summary,
-        event_type: "work",
+        event_type: logSpec.event_type ?? "work",
         written_by: "tickets",
       };
 
       for (const key of [
         "context",
+        "claim",
         "decisions",
         "next_steps",
         "blockers",
@@ -979,6 +1014,12 @@ function generateExampleTickets() {
           logEntry[key] = logSpec[key].map((value) => ids[value]);
         } else if (key === "created_from") {
           logEntry[key] = ids[logSpec[key]] ?? logSpec[key];
+        } else if (key === "claim") {
+          logEntry.claim = {
+            ...logSpec.claim,
+            claim_id: newUuidv7().toLowerCase(),
+            expires_at: iso8601(new Date(now.getTime() + (logSpec.claim.ttl_minutes ?? 60) * 60 * 1000)),
+          };
         } else {
           logEntry[key] = logSpec[key];
         }
@@ -997,6 +1038,8 @@ async function cmdInit(options) {
   const apply = Boolean(options.apply);
 
   syncTicketsMd(root, apply);
+  syncRepoConfig(root);
+  syncRepoSkill(root, apply);
 
   const agentsPath = path.join(root, "AGENTS_EXAMPLE.md");
   const agentsTemplatePath = path.join(".tickets", "spec", "AGENTS_EXAMPLE.md");
@@ -1009,8 +1052,15 @@ async function cmdInit(options) {
   const versionDir = path.join(repoBaseDir, "version");
   ensureDir(versionDir);
 
-  const currentSpecPath = path.join(versionDir, "20260311-tickets-spec.md");
-  writeTemplateFile(currentSpecPath, path.join(".tickets", "spec", "version", "20260311-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(
+    previousCurrentSpecPath,
+    path.join(".tickets", "spec", "version", "20260311-tickets-spec.md"),
+    apply,
+  );
 
   const previousSpecPath = path.join(versionDir, "20260205-tickets-spec.md");
   writeTemplateFile(previousSpecPath, path.join(".tickets", "spec", "version", "20260205-tickets-spec.md"), apply);
@@ -1022,15 +1072,48 @@ async function cmdInit(options) {
     generateExampleTickets();
   }
 
+  invalidatePlanningIndex();
   process.stdout.write("Initialized.\n");
   return 0;
 }
 
 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,
@@ -1084,6 +1167,10 @@ async function cmdNew(options) {
   if (options.verificationCommands?.length) {
     frontMatter.verification = { commands: options.verificationCommands };
   }
+  frontMatter.planning = planning;
+  if (options.resolution) {
+    frontMatter.resolution = options.resolution;
+  }
 
   const body = [
     "# Ticket",
@@ -1102,14 +1189,18 @@ 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()));
+
   for (const ticketPath of ticketPaths) {
     const [ticketIssues] = validateTicket(ticketPath, options.allFields);
     issues.push(...ticketIssues);
@@ -1130,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")}`;
@@ -1192,6 +1285,7 @@ async function cmdStatus(options) {
 
   const logPath = path.join(path.dirname(ticketPath), "logs", `${runStarted}-${runId}.jsonl`);
   appendJsonl(logPath, entry);
+  refreshPlanningIndexIfPresent();
 
   return 0;
 }
@@ -1251,18 +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,
-  });
+  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`);
@@ -1274,12 +1391,159 @@ async function cmdList(options) {
     return 0;
   }
 
-  const headers = ["id", "title", "status", "priority", "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`);
+  const headers = [
+    "id",
+    "title",
+    "status",
+    "priority",
+    "node_type",
+    "lane",
+    "rank",
+    "horizon",
+    "ready",
+    "claim",
+    "owner",
+    "last_updated",
+  ];
+  renderTable(headers, rows.map((row) => ({ ...row, claim: row.claim_summary })));
+
+  return 0;
+}
+
+async function cmdPlan(options) {
+  const snapshot = loadPlanningSnapshot();
+  const summary = buildPlanSummary(snapshot, {
+    group: options.group ?? options.root ?? null,
+    horizon: options.horizon ?? null,
+  });
+
+  if (options.format === "json") {
+    process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+    return 0;
+  }
+
+  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 ?? {};
+    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;
+}
+
+async function cmdClaim(options) {
+  const ticketPath = resolveTicketPath(options.ticket);
+  const logsDir = path.join(path.dirname(ticketPath), "logs");
+  ensureDir(logsDir);
+  const profile = loadWorkflowProfile();
+
+  const actorId = resolveActorId(options.actorId);
+  const actorType = resolveActorType(options.actorType, actorId);
+  const events = loadClaimEvents(logsDir);
+  const activeClaim = deriveActiveClaim(events, nowUtc());
+  const runId = options.runId || newUuidv7();
+  const runStarted = (options.runStarted || isoBasic(nowUtc())).replaceAll(" ", "");
+  const ttlMinutes = options.ttlMinutes || profile.defaults?.claims?.ttl_minutes || DEFAULT_CLAIM_TTL_MINUTES;
+  const now = nowUtc();
+
+  let action;
+  let summary;
+  let claimId = newUuidv7().toLowerCase();
+  let supersedesClaimId = null;
+
+  if (options.release) {
+    if (!activeClaim) {
+      process.stdout.write("No active claim.\n");
+      return 1;
+    }
+    if (activeClaim.holder_id !== actorId && !options.force) {
+      process.stdout.write(`Ticket is claimed by ${activeClaim.holder_id} until ${activeClaim.expires_at}.\n`);
+      return 1;
+    }
+    if (activeClaim.holder_id !== actorId && options.force && !options.reason) {
+      throw new Error("Forced claim release requires --reason");
+    }
+    action = "release";
+    claimId = activeClaim.claim_id;
+    summary = `Released claim ${claimId}`;
+  } else if (activeClaim && activeClaim.holder_id === actorId) {
+    action = "renew";
+    claimId = activeClaim.claim_id;
+    summary = `Renewed claim ${claimId}`;
+  } else if (activeClaim && activeClaim.holder_id !== actorId) {
+    if (!options.force) {
+      process.stdout.write(`Ticket is claimed by ${activeClaim.holder_id} until ${activeClaim.expires_at}.\n`);
+      return 1;
+    }
+    if (!options.reason) {
+      throw new Error("Forced claim override requires --reason");
+    }
+    action = "override";
+    supersedesClaimId = activeClaim.claim_id;
+    summary = `Overrode claim ${activeClaim.claim_id}`;
+  } else {
+    action = "acquire";
+    summary = `Acquired claim ${claimId}`;
+  }
+
+  const entry = {
+    version: FORMAT_VERSION,
+    version_url: FORMAT_VERSION_URL,
+    ts: iso8601(now),
+    run_started: runStarted,
+    actor_type: actorType,
+    actor_id: actorId,
+    summary,
+    event_type: "claim",
+    written_by: "tickets",
+    claim: {
+      action,
+      claim_id: claimId,
+      holder_id: actorId,
+      holder_type: actorType,
+      reason: options.reason ?? "",
+      supersedes_claim_id: supersedesClaimId,
+    },
+  };
+
+  if (action !== "release") {
+    entry.claim.ttl_minutes = ttlMinutes;
+    entry.claim.expires_at = iso8601(new Date(now.getTime() + ttlMinutes * 60 * 1000));
   }
 
+  appendJsonl(path.join(logsDir, `${runStarted}-${runId}.jsonl`), entry);
+  refreshPlanningIndexIfPresent();
+  process.stdout.write(`${summary}\n`);
   return 0;
 }
 
@@ -1354,7 +1618,12 @@ async function cmdRepair(options) {
 }
 
 async function cmdGraph(options) {
-  const graph = loadTicketGraph(options.ticket);
+  const snapshot = loadPlanningSnapshot();
+  const graph = buildGraphData(snapshot, {
+    ticket: options.ticket,
+    view: options.view,
+    includeRelated: options.related,
+  });
   if (graph.nodes.length === 0) {
     process.stdout.write("No tickets found.\n");
     return 1;
@@ -1365,8 +1634,8 @@ async function cmdGraph(options) {
 
   const timestamp = isoBasic(nowUtc());
   const base = options.ticket
-    ? `dependencies_for_${graph.root_id || "subset"}`
-    : "dependencies";
+    ? `${options.view}_for_${graph.root_id || "subset"}`
+    : options.view;
   const ext = { mermaid: "md", dot: "dot", json: "json" }[options.format];
   const outPath = options.output
     ? path.resolve(repoRoot(), options.output)
@@ -1378,7 +1647,7 @@ async function cmdGraph(options) {
   } else if (options.format === "dot") {
     fs.writeFileSync(outPath, renderDot(graph, options.related));
   } else {
-    fs.writeFileSync(outPath, renderMermaid(graph, options.related, timestamp));
+    fs.writeFileSync(outPath, renderMermaid(graph, options.related, timestamp, options.view));
   }
 
   process.stdout.write(`${outPath}\n`);
@@ -1419,6 +1688,13 @@ export async function run(argv = process.argv.slice(2)) {
     .option("--checkpoint-every-minutes <minutes>")
     .option("--verification-command <command>", "Verification command", collectOption, [])
     .option("--created-at <timestamp>")
+    .option("--node-type <nodeType>")
+    .option("--group-id <groupId>", "Group membership ticket id", collectOption, [])
+    .option("--lane <lane>")
+    .option("--rank <rank>")
+    .option("--horizon <horizon>")
+    .option("--precedes <ticketId>", "Sequence successor ticket id", collectOption, [])
+    .option("--resolution <resolution>")
     .action(async (options) => {
       if (!STATUS_VALUES.includes(options.status)) {
         throw new Error(`Invalid --status. Use one of: ${STATUS_VALUES.join(", ")}`);
@@ -1431,6 +1707,21 @@ export async function run(argv = process.argv.slice(2)) {
           `Invalid --assignment-mode. Use one of: ${ASSIGNMENT_MODE_VALUES.join(", ")}`,
         );
       }
+      if (options.nodeType && !PLANNING_NODE_TYPES.includes(options.nodeType)) {
+        throw new Error(`Invalid --node-type. Use one of: ${PLANNING_NODE_TYPES.join(", ")}`);
+      }
+      if (options.resolution && !RESOLUTION_VALUES.includes(options.resolution)) {
+        throw new Error(`Invalid --resolution. Use one of: ${RESOLUTION_VALUES.join(", ")}`);
+      }
+      if (options.rank) {
+        const rank = Number.parseInt(options.rank, 10);
+        if (!Number.isInteger(rank) || rank <= 0) {
+          throw new Error("Invalid --rank. Use a positive integer");
+        }
+      }
+      if (options.resolution && !["done", "canceled"].includes(options.status)) {
+        throw new Error("Resolution requires terminal status done or canceled");
+      }
       process.exitCode = await cmdNew({
         title: options.title,
         status: options.status,
@@ -1451,6 +1742,13 @@ export async function run(argv = process.argv.slice(2)) {
           : undefined,
         verificationCommands: options.verificationCommand,
         createdAt: options.createdAt,
+        nodeType: options.nodeType,
+        groupIds: options.groupId,
+        lane: options.lane,
+        rank: options.rank ? Number.parseInt(options.rank, 10) : null,
+        horizon: options.horizon,
+        precedes: options.precedes,
+        resolution: options.resolution,
       });
     });
 
@@ -1550,11 +1848,37 @@ export async function run(argv = process.argv.slice(2)) {
     .option("--owner <owner>")
     .option("--label <label>")
     .option("--text <text>")
+    .option("--node-type <nodeType>")
+    .option("--group <ticketId>")
+    .option("--lane <lane>")
+    .option("--horizon <horizon>")
+    .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);
     });
 
+  program
+    .command("plan")
+    .description("Summarize portfolio rollups and ready work")
+    .option("--root <ticket>")
+    .option("--group <ticket>")
+    .option("--horizon <horizon>")
+    .option("--format <format>", "table | json", "table")
+    .action(async (options) => {
+      if (!["table", "json"].includes(options.format)) {
+        throw new Error("Invalid --format. Use one of: table, json");
+      }
+      process.exitCode = await cmdPlan(options);
+    });
+
   program
     .command("repair")
     .description("Repair tickets")
@@ -1577,9 +1901,10 @@ export async function run(argv = process.argv.slice(2)) {
 
   program
     .command("graph")
-    .description("Dependency graph")
+    .description("Ticket graph")
     .option("--ticket <ticket>")
     .option("--format <format>", "mermaid | dot | json", "mermaid")
+    .option("--view <view>", "dependency | sequence | portfolio | all", "dependency")
     .option("--output <file>")
     .option("--related", "Include related edges")
     .option("--no-related", "Exclude related edges")
@@ -1587,14 +1912,53 @@ export async function run(argv = process.argv.slice(2)) {
       if (!["mermaid", "dot", "json"].includes(options.format)) {
         throw new Error("Invalid --format. Use one of: mermaid, dot, json");
       }
+      if (!GRAPH_VIEW_VALUES.includes(options.view)) {
+        throw new Error(`Invalid --view. Use one of: ${GRAPH_VIEW_VALUES.join(", ")}`);
+      }
       process.exitCode = await cmdGraph({
         ticket: options.ticket,
         format: options.format,
+        view: options.view,
         output: options.output,
         related: options.related,
       });
     });
 
+  program
+    .command("claim")
+    .description("Acquire, renew, release, or override an advisory ticket claim")
+    .requiredOption("--ticket <ticket>")
+    .option("--actor-type <actorType>")
+    .option("--actor-id <actorId>")
+    .option("--run-id <runId>")
+    .option("--run-started <runStarted>")
+    .option("--ttl-minutes <minutes>")
+    .option("--release", "Release the active claim")
+    .option("--force", "Override an active claim held by another actor")
+    .option("--reason <reason>")
+    .action(async (options) => {
+      if (options.actorType && !isValidActorType(options.actorType)) {
+        throw new Error("Invalid --actor-type. Use one of: human, agent");
+      }
+      if (options.ttlMinutes) {
+        const ttl = Number.parseInt(options.ttlMinutes, 10);
+        if (!Number.isInteger(ttl) || ttl <= 0) {
+          throw new Error("Invalid --ttl-minutes. Use a positive integer");
+        }
+      }
+      process.exitCode = await cmdClaim({
+        ticket: options.ticket,
+        actorType: options.actorType,
+        actorId: options.actorId,
+        runId: options.runId,
+        runStarted: options.runStarted,
+        ttlMinutes: options.ttlMinutes ? Number.parseInt(options.ttlMinutes, 10) : undefined,
+        release: Boolean(options.release),
+        force: Boolean(options.force),
+        reason: options.reason,
+      });
+    });
+
   try {
     await program.parseAsync(argv, { from: "user" });
   } catch (error) {