@picoai/tickets 0.1.0 → 0.3.0

package/src/cli.js

@@ -8,12 +8,20 @@ import yaml from "yaml";
 import {
   ASSIGNMENT_MODE_VALUES,
   BASE_DIR,
+  DEFAULT_CLAIM_TTL_MINUTES,
   FORMAT_VERSION,
   FORMAT_VERSION_URL,
+  GRAPH_VIEW_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 { listTickets } from "./lib/listing.js";
+import { buildGraphData, buildPlanSummary, buildPlanningSnapshot } 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 {
@@ -40,9 +48,55 @@ function hasErrors(issues) {
   return issues.some((issue) => issue.severity === "error");
 }
 
+function isValidActorType(value) {
+  return ["human", "agent"].includes(value);
+}
+
+function resolveActorId(explicitActorId) {
+  const candidate = explicitActorId ?? process.env.TICKETS_ACTOR_ID;
+  if (typeof candidate === "string" && candidate.trim()) {
+    return candidate.trim();
+  }
+
+  const localUser = process.env.USER ?? process.env.USERNAME;
+  if (typeof localUser === "string" && localUser.trim()) {
+    return `@${localUser.trim()}`;
+  }
+
+  return "unknown";
+}
+
+function resolveActorType(explicitActorType, actorId) {
+  const candidate = explicitActorType ?? process.env.TICKETS_ACTOR_TYPE;
+  if (typeof candidate === "string" && candidate.trim()) {
+    if (!isValidActorType(candidate.trim())) {
+      throw new Error("Invalid actor type. Use one of: human, agent");
+    }
+    return candidate.trim();
+  }
+
+  if (typeof actorId === "string") {
+    if (actorId.startsWith("agent:")) {
+      return "agent";
+    }
+    if (actorId.startsWith("@")) {
+      return "human";
+    }
+  }
+
+  return "human";
+}
+
+function normalizeContextItems(values) {
+  if (!Array.isArray(values)) {
+    return [];
+  }
+  return values.map((value) => String(value).trim()).filter(Boolean);
+}
+
 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`);
   }
 }
@@ -65,11 +119,14 @@ function buildRepairsFromIssues(issues, options = {}) {
   for (const issue of issues) {
     const code = issue.code;
     const ticketPath = issue.ticket_path;
-    if (!ticketPath) {
+    const logLocation = issue.log;
+    const logPath = logLocation ? String(logLocation).replace(/:\d+$/, "") : null;
+    if (!ticketPath && !logPath) {
       continue;
     }
 
-    const key = `${code}:${ticketPath}`;
+    const targetPath = ticketPath ?? logPath;
+    const key = `${code}:${targetPath}`;
     if (seen.has(key)) {
       continue;
     }
@@ -85,10 +142,31 @@ function buildRepairsFromIssues(issues, options = {}) {
       id: nextId,
       enabled: false,
       issue_ids: [issue.id ?? ""],
-      ticket_path: ticketPath,
     };
+    if (ticketPath) {
+      base.ticket_path = ticketPath;
+    }
+    if (logPath) {
+      base.log_path = logPath;
+    }
 
-    if (code === "MISSING_SECTION") {
+    if (["LOG_EVENT_TYPE_MISSING", "LOG_EVENT_TYPE_INVALID"].includes(code)) {
+      repairs.push({
+        ...base,
+        safe: true,
+        action: "set_log_event_type",
+        params: {},
+        optional: false,
+      });
+    } else if (["CONTEXT_INVALID", "CONTEXT_EMPTY", "CONTEXT_ENTRY_INVALID", "CONTEXT_MISSING"].includes(code)) {
+      repairs.push({
+        ...base,
+        safe: true,
+        action: "normalize_log_context",
+        params: {},
+        optional: false,
+      });
+    } else if (code === "MISSING_SECTION") {
       repairs.push({ ...base, safe: true, action: "add_sections", params: {}, optional: false });
     } else if (["VERSION_MISSING", "VERSION_INVALID"].includes(code)) {
       repairs.push({
@@ -166,90 +244,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",
@@ -259,7 +254,7 @@ function renderMermaid(graph, includeRelated, timestamp) {
   };
 
   const lines = [
-    "# Ticket dependency graph",
+    `# Ticket ${view} graph`,
     `_Generated at ${timestamp} UTC_`,
     "",
     "```mermaid",
@@ -286,7 +281,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)) {
@@ -333,8 +329,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("}");
@@ -657,6 +653,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: {
@@ -678,6 +675,7 @@ function generateExampleTickets() {
       logs: [
         {
           summary: "Epic created and split into child tickets.",
+          context: ["Parent planning context for Feature Alpha", "Child tickets were split for parallel execution"],
           tickets_created: ["backend", "frontend", "testing", "docs"],
           next_steps: ["Coordinate release window", "Monitor blockers"],
         },
@@ -689,6 +687,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"],
@@ -709,7 +708,12 @@ function generateExampleTickets() {
           summary: "Scaffolded API and outlined endpoints.",
           decisions: ["Using UUID primary keys", "Respond with JSON:API style"],
           created_from: "parent",
-          context_carried_over: ["Acceptance criteria from parent", "Release target"],
+          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 },
         },
       ],
     },
@@ -719,6 +723,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"] },
@@ -732,7 +737,7 @@ function generateExampleTickets() {
           summary: "Waiting on API responses to stabilize.",
           blockers: ["Backend contract not finalized"],
           created_from: "parent",
-          context_carried_over: ["Design mocks v1.2", "API schema draft"],
+          context: ["Design mocks v1.2", "API schema draft"],
         },
       ],
     },
@@ -742,6 +747,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: {
@@ -754,7 +760,7 @@ function generateExampleTickets() {
           summary: "Outlined E2E scenarios to automate.",
           next_steps: ["Set up test data fixtures"],
           created_from: "parent",
-          context_carried_over: ["Frontend flow chart", "Backend contract v1"],
+          context: ["Frontend flow chart", "Backend contract v1"],
         },
       ],
     },
@@ -764,6 +770,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: {
@@ -776,7 +783,7 @@ function generateExampleTickets() {
           summary: "Preparing outline; waiting on test results.",
           blockers: ["Integration tests pending"],
           created_from: "parent",
-          context_carried_over: ["Feature overview", "Known limitations"],
+          context: ["Feature overview", "Known limitations"],
         },
       ],
     },
@@ -786,6 +793,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"] },
@@ -797,6 +805,7 @@ function generateExampleTickets() {
       logs: [
         {
           summary: "Drafted release checklist; waiting on test green.",
+          context: ["Release checklist draft", "Waiting on integration test completion"],
           next_steps: ["Book release window"],
         },
       ],
@@ -804,9 +813,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"] },
@@ -817,8 +828,9 @@ function generateExampleTickets() {
       },
       logs: [
         {
-          summary: "Blocked until backend fix lands.",
-          blockers: ["Awaiting backend deployment"],
+          summary: "Dropped after mitigation in backend workstream.",
+          context: ["Regression repro identified", "Awaiting backend deployment before retry"],
+          decisions: ["Folded remediation into backend ticket"],
         },
       ],
     },
@@ -847,6 +859,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]);
@@ -886,16 +908,18 @@ function generateExampleTickets() {
         actor_type: "agent",
         actor_id: "tickets-init",
         summary: logSpec.summary,
+        event_type: logSpec.event_type ?? "work",
         written_by: "tickets",
       };
 
       for (const key of [
+        "context",
+        "claim",
         "decisions",
         "next_steps",
         "blockers",
         "tickets_created",
         "created_from",
-        "context_carried_over",
       ]) {
         if (!(key in logSpec)) {
           continue;
@@ -905,6 +929,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];
         }
@@ -923,6 +953,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");
@@ -935,8 +967,18 @@ async function cmdInit(options) {
   const versionDir = path.join(repoBaseDir, "version");
   ensureDir(versionDir);
 
-  const specPath = path.join(versionDir, "20260205-tickets-spec.md");
-  writeTemplateFile(specPath, path.join(".tickets", "spec", "version", "20260205-tickets-spec.md"), apply);
+  const currentSpecPath = path.join(versionDir, "20260317-tickets-spec.md");
+  writeTemplateFile(currentSpecPath, path.join(".tickets", "spec", "version", "20260317-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);
 
   const proposedPath = path.join(versionDir, "PROPOSED-tickets-spec.md");
   writeTemplateFile(proposedPath, path.join(".tickets", "spec", "version", "PROPOSED-tickets-spec.md"), apply);
@@ -951,6 +993,7 @@ async function cmdInit(options) {
 
 async function cmdNew(options) {
   ensureDir(ticketsDir());
+  const profile = loadWorkflowProfile();
   const ticketId = newUuidv7().toLowerCase();
   const ticketDir = path.join(ticketsDir(), ticketId);
   ensureDir(path.join(ticketDir, "logs"));
@@ -1007,6 +1050,17 @@ 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 : [],
+  };
+  if (options.resolution) {
+    frontMatter.resolution = options.resolution;
+  }
 
   const body = [
     "# Ticket",
@@ -1033,6 +1087,8 @@ async function cmdValidate(options) {
   const ticketPaths = collectTicketPaths(options.ticket);
   const issues = [];
 
+  issues.push(...validateRepoConfig(repoRoot()));
+
   for (const ticketPath of ticketPaths) {
     const [ticketIssues] = validateTicket(ticketPath, options.allFields);
     issues.push(...ticketIssues);
@@ -1085,28 +1141,37 @@ async function cmdValidate(options) {
 async function cmdStatus(options) {
   const ticketPath = resolveTicketPath(options.ticket);
   const [frontMatter, body] = loadTicket(ticketPath);
+  const previousStatus = frontMatter.status;
+  const actorId = resolveActorId(options.actorId);
+  const actorType = resolveActorType(options.actorType, actorId);
+  const context = normalizeContextItems(options.context);
 
   frontMatter.status = options.status;
   writeTicket(ticketPath, frontMatter, body);
 
-  if (options.log) {
-    const runId = options.runId || newUuidv7();
-    const runStarted = (options.runStarted || isoBasic(nowUtc())).replaceAll(" ", "");
-    const entry = {
-      version: FORMAT_VERSION,
-      version_url: FORMAT_VERSION_URL,
-      ts: iso8601(nowUtc()),
-      run_started: runStarted,
-      actor_type: "human",
-      actor_id: "status-change",
-      summary: `Status set to ${options.status}`,
-      written_by: "tickets",
-    };
-
-    const logPath = path.join(path.dirname(ticketPath), "logs", `${runStarted}-${runId}.jsonl`);
-    appendJsonl(logPath, entry);
+  const runId = options.runId || newUuidv7();
+  const runStarted = (options.runStarted || isoBasic(nowUtc())).replaceAll(" ", "");
+  const entry = {
+    version: FORMAT_VERSION,
+    version_url: FORMAT_VERSION_URL,
+    ts: iso8601(nowUtc()),
+    run_started: runStarted,
+    actor_type: actorType,
+    actor_id: actorId,
+    summary:
+      previousStatus === options.status
+        ? `Status reaffirmed as ${options.status}`
+        : `Status changed from ${previousStatus ?? "unknown"} to ${options.status}`,
+    event_type: "status",
+    written_by: "tickets",
+  };
+  if (context.length > 0) {
+    entry.context = context;
   }
 
+  const logPath = path.join(path.dirname(ticketPath), "logs", `${runStarted}-${runId}.jsonl`);
+  appendJsonl(logPath, entry);
+
   return 0;
 }
 
@@ -1114,16 +1179,26 @@ async function cmdLog(options) {
   const ticketPath = resolveTicketPath(options.ticket);
   const runId = options.runId || newUuidv7();
   const runStarted = (options.runStarted || isoBasic(nowUtc())).replaceAll(" ", "");
+  const actorId = resolveActorId(options.actorId);
+  const actorType = resolveActorType(options.actorType, actorId);
+  const context = normalizeContextItems(options.context);
+  if (options.machine && context.length === 0) {
+    throw new Error("Machine-written work logs require at least one --context item");
+  }
 
   const entry = {
     version: FORMAT_VERSION,
     version_url: FORMAT_VERSION_URL,
     ts: iso8601(nowUtc()),
     run_started: runStarted,
-    actor_type: options.actorType,
-    actor_id: options.actorId,
+    actor_type: actorType,
+    actor_id: actorId,
     summary: options.summary,
+    event_type: "work",
   };
+  if (context.length > 0) {
+    entry.context = context;
+  }
 
   if (options.machine) {
     entry.written_by = "tickets";
@@ -1146,9 +1221,6 @@ async function cmdLog(options) {
   if (options.createdFrom) {
     entry.created_from = options.createdFrom;
   }
-  if (options.contextCarriedOver?.length) {
-    entry.context_carried_over = options.contextCarriedOver;
-  }
   if (options.verificationCommands?.length || options.verificationResults) {
     entry.verification = {
       commands: options.verificationCommands || [],
@@ -1169,6 +1241,13 @@ async function cmdList(options) {
     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),
   });
 
   if (options.json) {
@@ -1181,7 +1260,20 @@ async function cmdList(options) {
     return 0;
   }
 
-  const headers = ["id", "title", "status", "priority", "owner", "mode", "last_updated"];
+  const headers = [
+    "id",
+    "title",
+    "status",
+    "priority",
+    "node_type",
+    "lane",
+    "rank",
+    "horizon",
+    "ready",
+    "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`);
@@ -1190,6 +1282,119 @@ async function cmdList(options) {
   return 0;
 }
 
+async function cmdPlan(options) {
+  const summary = buildPlanSummary({
+    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;
+  }
+
+  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 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 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);
+  process.stdout.write(`${summary}\n`);
+  return 0;
+}
+
 async function cmdRepair(options) {
   const nonInteractive = options.nonInteractive;
 
@@ -1226,6 +1431,24 @@ async function cmdRepair(options) {
         autoEnableSafe: !options.interactive,
       }),
     );
+
+    const logsDir = path.join(path.dirname(ticketPath), "logs");
+    if (!fs.existsSync(logsDir)) {
+      continue;
+    }
+    const logFiles = fs
+      .readdirSync(logsDir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+      .map((entry) => path.join(logsDir, entry.name))
+      .sort((a, b) => a.localeCompare(b));
+    for (const logFile of logFiles) {
+      repairs.push(
+        ...buildRepairsFromIssues(validateRunLog(logFile, false), {
+          includeOptional: options.allFields,
+          autoEnableSafe: !options.interactive,
+        }),
+      );
+    }
   }
 
   const changes = options.interactive
@@ -1243,7 +1466,12 @@ async function cmdRepair(options) {
 }
 
 async function cmdGraph(options) {
-  const graph = loadTicketGraph(options.ticket);
+  const snapshot = buildPlanningSnapshot();
+  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;
@@ -1254,8 +1482,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)
@@ -1267,7 +1495,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`);
@@ -1308,6 +1536,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(", ")}`);
@@ -1320,6 +1555,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,
@@ -1340,6 +1590,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,
       });
     });
 
@@ -1364,17 +1621,24 @@ export async function run(argv = process.argv.slice(2)) {
     .description("Update ticket status")
     .requiredOption("--ticket <ticket>")
     .requiredOption("--status <status>")
-    .option("--log", "Write a status-change log entry")
+    .option("--actor-type <actorType>")
+    .option("--actor-id <actorId>")
+    .option("--context <items...>")
     .option("--run-id <runId>")
     .option("--run-started <runStarted>")
     .action(async (options) => {
       if (!STATUS_VALUES.includes(options.status)) {
         throw new Error(`Invalid --status. Use one of: ${STATUS_VALUES.join(", ")}`);
       }
+      if (options.actorType && !isValidActorType(options.actorType)) {
+        throw new Error("Invalid --actor-type. Use one of: human, agent");
+      }
       process.exitCode = await cmdStatus({
         ticket: options.ticket,
         status: options.status,
-        log: Boolean(options.log),
+        actorType: options.actorType,
+        actorId: options.actorId,
+        context: options.context,
         runId: options.runId,
         runStarted: options.runStarted,
       });
@@ -1386,8 +1650,8 @@ export async function run(argv = process.argv.slice(2)) {
     .requiredOption("--ticket <ticket>")
     .option("--run-id <runId>")
     .option("--run-started <runStarted>")
-    .requiredOption("--actor-type <actorType>")
-    .requiredOption("--actor-id <actorId>")
+    .option("--actor-type <actorType>")
+    .option("--actor-id <actorId>")
     .requiredOption("--summary <summary>")
     .option("--machine")
     .option("--changes <files...>")
@@ -1396,11 +1660,11 @@ export async function run(argv = process.argv.slice(2)) {
     .option("--blockers <blockers...>")
     .option("--tickets-created <tickets...>")
     .option("--created-from <ticketId>")
-    .option("--context-carried-over <items...>")
+    .option("--context <items...>")
     .option("--verification-commands <commands...>")
     .option("--verification-results <results>")
     .action(async (options) => {
-      if (!["human", "agent"].includes(options.actorType)) {
+      if (options.actorType && !isValidActorType(options.actorType)) {
         throw new Error("Invalid --actor-type. Use one of: human, agent");
       }
       process.exitCode = await cmdLog({
@@ -1417,7 +1681,7 @@ export async function run(argv = process.argv.slice(2)) {
         blockers: options.blockers,
         ticketsCreated: options.ticketsCreated,
         createdFrom: options.createdFrom,
-        contextCarriedOver: options.contextCarriedOver,
+        context: options.context,
         verificationCommands: options.verificationCommands,
         verificationResults: options.verificationResults,
       });
@@ -1432,11 +1696,32 @@ 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("--json", "JSON output")
     .action(async (options) => {
       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")
@@ -1459,9 +1744,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")
@@ -1469,14 +1755,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) {