@picoai/tickets 0.3.0 → 0.5.0

package/src/lib/planning.js

@@ -1,43 +1,18 @@
-import fs from "node:fs";
-import path from "node:path";
-
-import { loadWorkflowProfile } from "./config.js";
-import { deriveActiveClaim, loadClaimEvents } from "./claims.js";
-import { collectTicketPaths } from "./validation.js";
-import { loadTicket, readJsonl } from "./util.js";
-
 const TERMINAL_STATUSES = new Set(["done", "canceled"]);
-
-function isTerminal(status) {
+const GROUP_NODE_TYPES = new Set(["group", "checkpoint"]);
+const PRIORITY_ORDER = new Map([
+  ["critical", 0],
+  ["high", 1],
+  ["medium", 2],
+  ["low", 3],
+  ["", 4],
+]);
+
+export function isTerminalStatus(status) {
   return TERMINAL_STATUSES.has(status);
 }
 
-function lastUpdated(ticketDir) {
-  const logsDir = path.join(ticketDir, "logs");
-  let latest = "";
-
-  if (!fs.existsSync(logsDir)) {
-    return latest;
-  }
-
-  const logFiles = fs
-    .readdirSync(logsDir, { withFileTypes: true })
-    .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
-    .map((entry) => path.join(logsDir, entry.name));
-
-  for (const logFile of logFiles) {
-    for (const entry of readJsonl(logFile)) {
-      const ts = entry.ts;
-      if (typeof ts === "string" && (latest === "" || ts > latest)) {
-        latest = ts;
-      }
-    }
-  }
-
-  return latest;
-}
-
-function normalizePlanning(frontMatter, profile) {
+export function normalizePlanning(frontMatter, profile) {
   const planning = frontMatter.planning ?? {};
   return {
     node_type: planning.node_type ?? profile.defaults?.planning?.node_type ?? "work",
@@ -49,6 +24,30 @@ function normalizePlanning(frontMatter, profile) {
   };
 }
 
+function cloneRow(row) {
+  return {
+    ...row,
+    labels: Array.isArray(row.labels) ? [...row.labels] : [],
+    dependencies: Array.isArray(row.dependencies) ? [...row.dependencies] : [],
+    blocks: Array.isArray(row.blocks) ? [...row.blocks] : [],
+    related: Array.isArray(row.related) ? [...row.related] : [],
+    planning: {
+      node_type: row.planning?.node_type ?? "work",
+      group_ids: Array.isArray(row.planning?.group_ids) ? [...row.planning.group_ids] : [],
+      lane: row.planning?.lane ?? null,
+      rank: row.planning?.rank ?? null,
+      horizon: row.planning?.horizon ?? null,
+      precedes: Array.isArray(row.planning?.precedes) ? [...row.planning.precedes] : [],
+    },
+    active_claim: row.active_claim ? { ...row.active_claim } : null,
+    blocked_by: {
+      dependencies: Array.isArray(row.blocked_by?.dependencies) ? [...row.blocked_by.dependencies] : [],
+      predecessors: Array.isArray(row.blocked_by?.predecessors) ? [...row.blocked_by.predecessors] : [],
+    },
+    rollup: row.rollup ? { ...row.rollup } : null,
+  };
+}
+
 function collectGroupLeaves(groupId, membersByGroup, nodesById, seen = new Set(), leaves = new Set()) {
   if (seen.has(groupId)) {
     return leaves;
@@ -71,7 +70,7 @@ function collectGroupLeaves(groupId, membersByGroup, nodesById, seen = new Set()
 }
 
 function computeRollup(row, membersByGroup, nodesById) {
-  if (!["group", "checkpoint"].includes(row.planning.node_type)) {
+  if (!GROUP_NODE_TYPES.has(row.planning.node_type)) {
     return null;
   }
 
@@ -97,6 +96,106 @@ function computeRollup(row, membersByGroup, nodesById) {
   };
 }
 
+function compareNullableStrings(a, b) {
+  return String(a ?? "").localeCompare(String(b ?? ""));
+}
+
+function compareNullableNumbers(a, b) {
+  const left = Number.isInteger(a) ? a : Number.MAX_SAFE_INTEGER;
+  const right = Number.isInteger(b) ? b : Number.MAX_SAFE_INTEGER;
+  return left - right;
+}
+
+function comparePriority(a, b) {
+  const left = PRIORITY_ORDER.get(a.priority ?? "") ?? PRIORITY_ORDER.get("");
+  const right = PRIORITY_ORDER.get(b.priority ?? "") ?? PRIORITY_ORDER.get("");
+  return left - right;
+}
+
+function compareLastUpdated(a, b) {
+  return String(b.last_updated ?? "").localeCompare(String(a.last_updated ?? ""));
+}
+
+function applyComparatorChain(a, b, comparators) {
+  for (const comparator of comparators) {
+    const result = comparator(a, b);
+    if (result !== 0) {
+      return result;
+    }
+  }
+  return 0;
+}
+
+function baseOperationalComparators() {
+  return [
+    (a, b) => compareNullableStrings(a.planning.lane, b.planning.lane),
+    (a, b) => compareNullableNumbers(a.planning.rank, b.planning.rank),
+    (a, b) => compareNullableStrings(a.title, b.title),
+  ];
+}
+
+export function formatClaimSummary(activeClaim) {
+  if (!activeClaim?.holder_id) {
+    return "";
+  }
+  const until = activeClaim.expires_at ? ` until ${activeClaim.expires_at}` : "";
+  return `${activeClaim.holder_id}${until}`;
+}
+
+export function buildPlanningSnapshotFromRows(rows, profile) {
+  const snapshotRows = rows.map((row) => cloneRow(row));
+  const nodesById = new Map(snapshotRows.map((row) => [row.id, row]));
+  const predecessorsById = new Map();
+  const membersByGroup = new Map();
+
+  for (const row of snapshotRows) {
+    for (const successorId of row.planning.precedes) {
+      if (!predecessorsById.has(successorId)) {
+        predecessorsById.set(successorId, []);
+      }
+      predecessorsById.get(successorId).push(row.id);
+    }
+    for (const groupId of row.planning.group_ids) {
+      if (!membersByGroup.has(groupId)) {
+        membersByGroup.set(groupId, []);
+      }
+      membersByGroup.get(groupId).push(row.id);
+    }
+  }
+
+  for (const row of snapshotRows) {
+    const unresolvedDependencies = row.dependencies.filter((id) => {
+      const dependency = nodesById.get(id);
+      return dependency ? !isTerminalStatus(dependency.status) : true;
+    });
+    const unresolvedPredecessors = (predecessorsById.get(row.id) ?? []).filter((id) => {
+      const predecessor = nodesById.get(id);
+      return predecessor ? !isTerminalStatus(predecessor.status) : true;
+    });
+
+    row.blocked_by = {
+      dependencies: unresolvedDependencies,
+      predecessors: unresolvedPredecessors,
+    };
+    row.ready =
+      row.planning.node_type === "work" &&
+      !isTerminalStatus(row.status) &&
+      row.mode !== "human_only" &&
+      unresolvedDependencies.length === 0 &&
+      unresolvedPredecessors.length === 0;
+    row.claim_summary = formatClaimSummary(row.active_claim);
+    row.rollup = computeRollup(row, membersByGroup, nodesById);
+  }
+
+  return {
+    profile,
+    rows: snapshotRows,
+    nodesById,
+    predecessorsById,
+    membersByGroup,
+  };
+}
+
 function passesFilters(row, filters) {
   if (filters.status && row.status !== filters.status) {
     return false;
@@ -144,90 +243,42 @@ function passesFilters(row, filters) {
   return true;
 }
 
-export function buildPlanningSnapshot(options = {}) {
-  const profile = options.profile ?? loadWorkflowProfile();
-  const paths = collectTicketPaths(null);
-  const rows = [];
-
-  for (const ticketPath of paths) {
-    try {
-      const [frontMatter, body] = loadTicket(ticketPath);
-      const ticketDir = path.dirname(ticketPath);
-      const activeClaim = deriveActiveClaim(loadClaimEvents(path.join(ticketDir, "logs")));
-
-      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: lastUpdated(ticketDir),
-      });
-    } catch {
-      // Invalid tickets are surfaced by `validate`; views skip them.
-    }
-  }
-
-  const nodesById = new Map(rows.map((row) => [row.id, row]));
-  const predecessorsById = new Map();
-  const membersByGroup = new Map();
-
-  for (const row of rows) {
-    for (const successorId of row.planning.precedes) {
-      if (!predecessorsById.has(successorId)) {
-        predecessorsById.set(successorId, []);
-      }
-      predecessorsById.get(successorId).push(row.id);
-    }
-    for (const groupId of row.planning.group_ids) {
-      if (!membersByGroup.has(groupId)) {
-        membersByGroup.set(groupId, []);
-      }
-      membersByGroup.get(groupId).push(row.id);
-    }
-  }
-
-  for (const row of rows) {
-    const depsSatisfied = row.dependencies.every((id) => {
-      const dependency = nodesById.get(id);
-      return dependency ? isTerminal(dependency.status) : false;
-    });
-    const predecessorsSatisfied = (predecessorsById.get(row.id) ?? []).every((id) => {
-      const predecessor = nodesById.get(id);
-      return predecessor ? isTerminal(predecessor.status) : false;
-    });
-
-    row.ready =
-      row.planning.node_type === "work" &&
-      !isTerminal(row.status) &&
-      row.mode !== "human_only" &&
-      depsSatisfied &&
-      predecessorsSatisfied;
-    row.rollup = computeRollup(row, membersByGroup, nodesById);
-  }
+export function listPlanningRows(snapshot, filters = {}) {
+  return snapshot.rows.filter((row) => passesFilters(row, filters));
+}
 
-  return {
-    profile,
-    rows,
-    nodesById,
-    predecessorsById,
-    membersByGroup,
+export function sortPlanningRows(rows, sortBy = null, reverse = false) {
+  const comparatorsBySort = {
+    default: [
+      (a, b) => Number(b.ready) - Number(a.ready),
+      comparePriority,
+      ...baseOperationalComparators(),
+      compareLastUpdated,
+      (a, b) => compareNullableStrings(a.title, b.title),
+    ],
+    ready: [
+      (a, b) => Number(b.ready) - Number(a.ready),
+      ...baseOperationalComparators(),
+      comparePriority,
+      compareLastUpdated,
+    ],
+    priority: [comparePriority, ...baseOperationalComparators(), compareLastUpdated],
+    lane: [...baseOperationalComparators(), comparePriority, compareLastUpdated],
+    rank: [
+      (a, b) => compareNullableNumbers(a.planning.rank, b.planning.rank),
+      (a, b) => compareNullableStrings(a.planning.lane, b.planning.lane),
+      comparePriority,
+      compareLastUpdated,
+      (a, b) => compareNullableStrings(a.title, b.title),
+    ],
+    updated: [compareLastUpdated, ...baseOperationalComparators(), comparePriority],
+    title: [(a, b) => compareNullableStrings(a.title, b.title), comparePriority, ...baseOperationalComparators()],
   };
-}
 
-export function listPlanningRows(filters = {}, options = {}) {
-  const snapshot = buildPlanningSnapshot(options);
-  return snapshot.rows.filter((row) => passesFilters(row, filters));
+  const key = sortBy ?? "default";
+  const comparators = comparatorsBySort[key] ?? comparatorsBySort.default;
+  const sorted = [...rows].sort((a, b) => applyComparatorChain(a, b, comparators));
+  return reverse ? sorted.reverse() : sorted;
 }
 
 export function buildGraphData(snapshot, options = {}) {
@@ -304,52 +355,98 @@ export function buildGraphData(snapshot, options = {}) {
   };
 }
 
-export function buildPlanSummary(options = {}) {
-  const snapshot = buildPlanningSnapshot(options);
+function collectScopedIds(groupId, membersByGroup) {
+  const seen = new Set();
+  const queue = [groupId];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current || seen.has(current)) {
+      continue;
+    }
+    seen.add(current);
+    for (const childId of membersByGroup.get(current) ?? []) {
+      queue.push(childId);
+    }
+  }
+
+  return seen;
+}
+
+function buildPlanRow(row) {
+  return {
+    id: row.id,
+    title: row.title,
+    status: row.status,
+    priority: row.priority,
+    node_type: row.planning.node_type,
+    lane: row.planning.lane,
+    rank: row.planning.rank,
+    horizon: row.planning.horizon,
+    group_ids: [...row.planning.group_ids],
+    active_claim: row.active_claim,
+    claim_summary: row.claim_summary,
+    owner: row.owner,
+    mode: row.mode,
+    blocked_by: {
+      dependencies: [...row.blocked_by.dependencies],
+      predecessors: [...row.blocked_by.predecessors],
+    },
+  };
+}
+
+export function buildPlanSummary(snapshot, options = {}) {
   let rows = snapshot.rows;
 
   if (options.group) {
-    rows = rows.filter((row) => row.id === options.group || row.planning.group_ids.includes(options.group));
+    const scopedIds = collectScopedIds(options.group, snapshot.membersByGroup);
+    rows = rows.filter((row) => scopedIds.has(row.id));
   }
   if (options.horizon) {
     rows = rows.filter((row) => row.planning.horizon === options.horizon);
   }
 
-  const groups = rows.filter((row) => ["group", "checkpoint"].includes(row.planning.node_type));
-  const ready = rows
-    .filter((row) => row.ready)
-    .sort((a, b) => {
-      const lane = String(a.planning.lane ?? "").localeCompare(String(b.planning.lane ?? ""));
-      if (lane !== 0) {
-        return lane;
-      }
-      const rankA = a.planning.rank ?? Number.MAX_SAFE_INTEGER;
-      const rankB = b.planning.rank ?? Number.MAX_SAFE_INTEGER;
-      if (rankA !== rankB) {
-        return rankA - rankB;
-      }
-      return a.title.localeCompare(b.title);
-    });
+  const workRows = rows.filter((row) => row.planning.node_type === "work" && !isTerminalStatus(row.status));
+  const ready = sortPlanningRows(
+    workRows.filter((row) => row.ready && row.status === "todo"),
+    "lane",
+    false,
+  ).map(buildPlanRow);
+  const active = sortPlanningRows(
+    workRows.filter((row) => row.status === "doing"),
+    "lane",
+    false,
+  ).map(buildPlanRow);
+  const blocked = sortPlanningRows(
+    workRows.filter(
+      (row) =>
+        !row.ready &&
+        (row.status === "blocked" || row.blocked_by.dependencies.length > 0 || row.blocked_by.predecessors.length > 0),
+    ),
+    "lane",
+    false,
+  ).map(buildPlanRow);
+  const groups = sortPlanningRows(
+    rows.filter((row) => GROUP_NODE_TYPES.has(row.planning.node_type)),
+    "lane",
+    false,
+  ).map((row) => ({
+    id: row.id,
+    title: row.title,
+    node_type: row.planning.node_type,
+    lane: row.planning.lane,
+    rank: row.planning.rank,
+    horizon: row.planning.horizon,
+    rollup: row.rollup,
+  }));
 
   return {
     generated_at: new Date().toISOString(),
     workflow_mode: snapshot.profile.workflow?.mode ?? "auto",
     semantics: snapshot.profile.semantics?.terms ?? {},
-    ready: ready.map((row) => ({
-      id: row.id,
-      title: row.title,
-      lane: row.planning.lane,
-      rank: row.planning.rank,
-      horizon: row.planning.horizon,
-      active_claim: row.active_claim,
-    })),
-    groups: groups.map((row) => ({
-      id: row.id,
-      title: row.title,
-      node_type: row.planning.node_type,
-      lane: row.planning.lane,
-      horizon: row.planning.horizon,
-      rollup: row.rollup,
-    })),
+    ready,
+    active,
+    blocked,
+    groups,
   };
 }

package/src/lib/projections.js

@@ -30,8 +30,14 @@ export function renderRepoSkill(profile = loadDefaultProfile()) {
     "",
     "## Required behavior",
     "- Read `TICKETS.md` for the full repo contract when context is missing.",
+    "- Consult `.tickets/config.yml` for repo-local defaults and semantic overrides before interpreting planning terminology or creating new tickets.",
     "- Validate assigned tickets before implementation with `npx @picoai/tickets validate`.",
+    "- Before setting a ticket to `done`, confirm the ticket's `## Acceptance Criteria` are met and its `## Verification` checks passed.",
+    "- If those completion gates are not satisfied, stop and ask a human whether to keep working or explicitly override the gates. Only move the ticket to `done` after that human decision.",
+    "- Record `completion` metadata every time a ticket is moved to `done`.",
+    "- When a human overrides incomplete completion gates, record the exception through `npx @picoai/tickets status --status done --acceptance-criteria ... --verification-state ... --override-by ... --override-reason ...` so `ticket.md` and the status log both reflect it.",
     "- Use `npx @picoai/tickets status`, `log`, `claim`, `plan`, and `graph` instead of editing derived state manually.",
+    "- When humans use terms like feature, phase, milestone, roadmap, or repo-specific equivalents, translate them through `.tickets/config.yml` and then call the generic CLI fields.",
     "- Respect repo overrides in `.tickets/config.yml` and any narrative guidance in `TICKETS.override.md` if present.",
     "",
     "## Core planning model",
@@ -44,12 +50,19 @@ export function renderRepoSkill(profile = loadDefaultProfile()) {
     "## Default semantic mapping",
     renderSemanticTerms(config),
     "",
+    "Repo-specific semantic overrides live in `.tickets/config.yml`. Treat the list above as defaults only.",
+    "",
     "## Claims",
     "- Claims are optional advisory leases stored in ticket logs.",
     "- Acquire or renew with `npx @picoai/tickets claim --ticket <id>`.",
     "- Release with `npx @picoai/tickets claim --ticket <id> --release`.",
     `- Default claim TTL is ${config.defaults?.claims?.ttl_minutes ?? 60} minutes unless the repo config overrides it.`,
     "",
+    "## Planning views",
+    "- Use `npx @picoai/tickets list` for broad queue/reporting views.",
+    "- Use `npx @picoai/tickets plan` for operational state: ready, in-progress, blocked, and group rollups.",
+    "- Use `npx @picoai/tickets graph` for structural relationships, not execution state.",
+    "",
   ].join("\n");
 }