@topogram/cli 0.3.72 → 0.3.74

package/src/resolver/projections-cli.js

@@ -0,0 +1,158 @@
+// @ts-check
+
+import { blockEntries, getFieldValue } from "../validator/utils.js";
+
+/**
+ * @param {TopogramToken | null | undefined} token
+ * @returns {string | null}
+ */
+function tokenText(token) {
+  return token?.type === "symbol" || token?.type === "string" ? token.value : null;
+}
+
+/**
+ * @param {TopogramToken[]} items
+ * @returns {(string | string[])[]}
+ */
+function normalizeSequence(items) {
+  return items.map((item) => {
+    if (item.type === "symbol" || item.type === "string") {
+      return item.value;
+    }
+    if (item.type === "list") {
+      return item.items.map((nested) => tokenText(nested)).filter((value) => value !== null);
+    }
+    return item.type;
+  });
+}
+
+/**
+ * @param {TopogramToken[]} items
+ * @param {number} startIndex
+ * @returns {Record<string, string | string[]>}
+ */
+function parseDirectives(items, startIndex) {
+  /** @type {Record<string, string | string[]>} */
+  const directives = {};
+  for (let index = startIndex; index < items.length; index += 2) {
+    const key = tokenText(items[index]);
+    const valueToken = items[index + 1];
+    const value = valueToken?.type === "list"
+      ? valueToken.items.map((item) => tokenText(item)).filter((item) => item !== null)
+      : tokenText(valueToken);
+    if (key && value != null) {
+      directives[key] = value;
+    }
+  }
+  return directives;
+}
+
+/**
+ * @param {TopogramStatement} statement
+ * @param {TopogramRegistry} registry
+ * @returns {Record<string, any>[]}
+ */
+export function parseProjectionCliCommandsBlock(statement, registry) {
+  return blockEntries(getFieldValue(statement, "commands")).map((entry) => {
+    const commandId = tokenText(entry.items[1]);
+    const directives = parseDirectives(entry.items, 2);
+    const capabilityId = typeof directives.capability === "string" ? directives.capability : null;
+    return {
+      type: "cli_command",
+      id: commandId,
+      capability: capabilityId
+        ? {
+            id: capabilityId,
+            kind: registry.get(capabilityId)?.kind || null
+          }
+        : null,
+      usage: typeof directives.usage === "string" ? directives.usage : null,
+      mode: typeof directives.mode === "string" ? directives.mode : null,
+      description: typeof directives.description === "string" ? directives.description : null,
+      raw: normalizeSequence(entry.items),
+      loc: entry.loc
+    };
+  });
+}
+
+/**
+ * @param {TopogramStatement} statement
+ * @returns {Record<string, any>[]}
+ */
+export function parseProjectionCliOptionsBlock(statement) {
+  return blockEntries(getFieldValue(statement, "command_options")).map((entry) => {
+    const directives = parseDirectives(entry.items, 4);
+    return {
+      type: "cli_option",
+      command: tokenText(entry.items[1]),
+      name: tokenText(entry.items[3]),
+      optionType: typeof directives.type === "string" ? directives.type : null,
+      flag: typeof directives.flag === "string" ? directives.flag : null,
+      required: directives.required === "true",
+      defaultValue: directives.default ?? null,
+      description: typeof directives.description === "string" ? directives.description : null,
+      values: Array.isArray(directives.values) ? directives.values : [],
+      raw: normalizeSequence(entry.items),
+      loc: entry.loc
+    };
+  });
+}
+
+/**
+ * @param {TopogramStatement} statement
+ * @param {TopogramRegistry} registry
+ * @returns {Record<string, any>[]}
+ */
+export function parseProjectionCliOutputsBlock(statement, registry) {
+  return blockEntries(getFieldValue(statement, "command_outputs")).map((entry) => {
+    const directives = parseDirectives(entry.items, 4);
+    const schemaId = typeof directives.schema === "string" ? directives.schema : null;
+    return {
+      type: "cli_output",
+      command: tokenText(entry.items[1]),
+      format: tokenText(entry.items[3]),
+      schema: schemaId
+        ? {
+            id: schemaId,
+            kind: registry.get(schemaId)?.kind || null
+          }
+        : null,
+      description: typeof directives.description === "string" ? directives.description : null,
+      raw: normalizeSequence(entry.items),
+      loc: entry.loc
+    };
+  });
+}
+
+/**
+ * @param {TopogramStatement} statement
+ * @returns {Record<string, any>[]}
+ */
+export function parseProjectionCliEffectsBlock(statement) {
+  return blockEntries(getFieldValue(statement, "command_effects")).map((entry) => {
+    const directives = parseDirectives(entry.items, 4);
+    return {
+      type: "cli_effect",
+      command: tokenText(entry.items[1]),
+      effect: tokenText(entry.items[3]),
+      target: typeof directives.target === "string" ? directives.target : null,
+      description: typeof directives.description === "string" ? directives.description : null,
+      raw: normalizeSequence(entry.items),
+      loc: entry.loc
+    };
+  });
+}
+
+/**
+ * @param {TopogramStatement} statement
+ * @returns {Record<string, any>[]}
+ */
+export function parseProjectionCliExamplesBlock(statement) {
+  return blockEntries(getFieldValue(statement, "command_examples")).map((entry) => ({
+    type: "cli_example",
+    command: tokenText(entry.items[1]),
+    example: tokenText(entry.items[3]),
+    raw: normalizeSequence(entry.items),
+    loc: entry.loc
+  }));
+}

package/src/sdlc/adopt.js

@@ -7,18 +7,21 @@
 import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { DEFAULT_TOPO_FOLDER_NAME, resolveTopoRoot } from "../workspace-paths.js";
+import { sdlcRootForSdlc } from "./paths.js";
 
 const SDLC_FOLDERS = [
   "pitches",
   "requirements",
   "acceptance_criteria",
   "tasks",
+  "plans",
   "bugs",
+  "decisions",
   "_archive"
 ];
 
 function ensureFolder(root, name) {
-  const dir = path.join(resolveTopoRoot(root), name);
+  const dir = path.join(sdlcRootForSdlc(root), name);
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
     return { name, created: true };

package/src/sdlc/check.js

@@ -10,13 +10,15 @@
 // `--strict` mode.
 
 import { checkDoD } from "./dod/index.js";
-import { detectDriftedStatus, readHistory } from "./history.js";
+import { detectDriftedStatus, readHistory, validateHistory } from "./history.js";
+import { planStepHistoryId } from "./plan-steps.js";
 
 const SDLC_KINDS = new Set([
   "pitch",
   "requirement",
   "acceptance_criterion",
   "task",
+  "plan",
   "bug"
 ]);
 
@@ -47,6 +49,10 @@ export function checkWorkspace(workspaceRoot, resolved) {
   const history = readHistory(workspaceRoot);
   if (history.__error) {
     warnings.push({ message: `cannot read SDLC history sidecar: ${history.__error}` });
+  } else {
+    for (const warning of validateHistory(history)) {
+      warnings.push(warning);
+    }
   }
 
   const byId = new Map(resolved.graph.statements.map((s) => [s.id, s]));
@@ -59,10 +65,26 @@ export function checkWorkspace(workspaceRoot, resolved) {
     if (drift) {
       warnings.push({
         id: statement.id,
-        message: `status drift: history records '${drift.historyStatus}' but current is '${drift.currentStatus}'`
+        message: `status drift: history records '${drift.historyStatus}' but current is '${drift.currentStatus}'. Use topogram sdlc transition so status and history stay aligned.`
       });
     }
 
+    if (statement.kind === "plan") {
+      for (const step of statement.steps || []) {
+        const stepDrift = detectDriftedStatus(history, {
+          id: planStepHistoryId(statement.id, step.id),
+          kind: "plan_step",
+          status: step.status
+        });
+        if (stepDrift) {
+          warnings.push({
+            id: statement.id,
+            message: `step status drift: history records '${stepDrift.historyStatus}' for ${step.id} but current is '${stepDrift.currentStatus}'. Use topogram sdlc plan step transition so step status and history stay aligned.`
+          });
+        }
+      }
+    }
+
     // Re-run DoD against the *current* status to surface "approved without
     // ACs" or similar ongoing violations.
     const dod = checkDoD(statement.kind, statement, statement.status, { byId });

package/src/sdlc/complete.js

@@ -0,0 +1,47 @@
+// @ts-check
+
+import { linkSdlcRecord } from "./link.js";
+import { transitionStatement } from "./transition.js";
+
+/**
+ * @param {string} workspaceRoot
+ * @param {string} taskId
+ * @param {string} verificationId
+ * @param {{ write?: boolean, actor?: string|null, note?: string|null }} [options]
+ * @returns {Record<string, any>}
+ */
+export function completeTask(workspaceRoot, taskId, verificationId, options = {}) {
+  if (!verificationId) {
+    return { ok: false, error: "sdlc complete requires --verification <verification-id>" };
+  }
+  const link = linkSdlcRecord(workspaceRoot, taskId, verificationId, { write: Boolean(options.write) });
+  if (!link.ok) {
+    return { ok: false, taskId, verificationId, link };
+  }
+  if (!options.write) {
+    return {
+      ok: true,
+      dryRun: true,
+      taskId,
+      verificationId,
+      link,
+      transition: {
+        planned: true,
+        to: "done"
+      }
+    };
+  }
+
+  const transition = transitionStatement(workspaceRoot, taskId, "done", {
+    actor: options.actor || null,
+    note: options.note || null
+  });
+  return {
+    ok: Boolean(transition.ok),
+    dryRun: false,
+    taskId,
+    verificationId,
+    link,
+    transition
+  };
+}

package/src/sdlc/dod/index.js

@@ -4,6 +4,7 @@ import { checkDoD as checkPitch } from "./pitch.js";
 import { checkDoD as checkRequirement } from "./requirement.js";
 import { checkDoD as checkAcceptanceCriterion } from "./acceptance-criterion.js";
 import { checkDoD as checkTask } from "./task.js";
+import { checkDoD as checkPlan } from "./plan.js";
 import { checkDoD as checkBug } from "./bug.js";
 import { checkDoD as checkDocument } from "./document.js";
 
@@ -12,6 +13,7 @@ const CHECKS = {
   requirement: checkRequirement,
   acceptance_criterion: checkAcceptanceCriterion,
   task: checkTask,
+  plan: checkPlan,
   bug: checkBug,
   document: checkDocument
 };

package/src/sdlc/dod/plan.js

@@ -0,0 +1,15 @@
+// Plan DoD per status.
+
+export function checkDoD(plan, targetStatus) {
+  const errors = [];
+  const warnings = [];
+
+  if (targetStatus === "complete") {
+    const incomplete = (plan.steps || []).filter((step) => step.status !== "done" && step.status !== "skipped");
+    if (incomplete.length > 0) {
+      errors.push(`status 'complete' requires all plan steps to be done or skipped: ${incomplete.map((step) => step.id).join(", ")}`);
+    }
+  }
+
+  return { satisfied: errors.length === 0, errors, warnings };
+}

package/src/sdlc/dod/task.js

@@ -27,11 +27,15 @@ export function checkDoD(task, targetStatus, graph) {
 
   if (targetStatus === "done") {
     if (!task.satisfies || task.satisfies.length === 0) {
-      warnings.push("done task without `satisfies` references is hard to trace");
+      errors.push("status 'done' requires field 'satisfies'");
     }
     const acs = task.acceptanceRefs || [];
-    if (acs.length === 0 && task.workType !== "documentation" && task.workType !== "review") {
-      warnings.push("done task without `acceptance_refs` cannot tie back to verification");
+    if (acs.length === 0) {
+      errors.push("status 'done' requires field 'acceptance_refs'");
+    }
+    const verifications = task.verificationRefs || [];
+    if (verifications.length === 0) {
+      errors.push("status 'done' requires field 'verification_refs'");
     }
   }
 

package/src/sdlc/explain.js

@@ -14,6 +14,7 @@ import { checkDoD } from "./dod/index.js";
 import { legalTransitionsFor, isTerminalStatus } from "./transitions/index.js";
 import { defaultActiveStatuses } from "./status-filter.js";
 import { readHistory, lastTransition, detectDriftedStatus } from "./history.js";
+import { planStepHistoryId } from "./plan-steps.js";
 
 function pickNextStatus(legal) {
   // Prefer the canonical forward path (skipping rollback options).
@@ -22,9 +23,9 @@ function pickNextStatus(legal) {
     "approved",
     "submitted",
     "shaped",
-    "claimed",
     "in-progress",
     "done",
+    "claimed",
     "fixed",
     "verified",
     "review",
@@ -48,6 +49,54 @@ function buildBlockers(statement, byId) {
     .filter(Boolean);
 }
 
+function summarizePlan(plan, history) {
+  const steps = (plan.steps || []).map((step) => ({
+    id: step.id,
+    status: step.status,
+    description: step.description,
+    notes: step.notes || null,
+    outcome: step.outcome || null,
+    last_transition: lastTransition(history, planStepHistoryId(plan.id, step.id))
+  }));
+  return {
+    id: plan.id,
+    status: plan.status,
+    task: plan.task?.id || null,
+    steps,
+    next_step: steps.find((step) => step.status !== "done" && step.status !== "skipped") || null
+  };
+}
+
+function plansForTask(graph, task, history) {
+  const planIds = task.kind === "task" ? task.plans || [] : [];
+  return planIds
+    .map((id) => graph.statements.find((statement) => statement.id === id && statement.kind === "plan" && !statement.archived))
+    .filter(Boolean)
+    .map((plan) => summarizePlan(plan, history));
+}
+
+function recommendedQueries(statement) {
+  if (statement.kind === "task") {
+    return [
+      `topogram query slice ./topo --task ${statement.id} --json`,
+      `topogram query single-agent-plan ./topo --mode modeling --task ${statement.id} --json`
+    ];
+  }
+  if (statement.kind === "bug") {
+    return [
+      `topogram query slice ./topo --bug ${statement.id} --json`,
+      `topogram query single-agent-plan ./topo --mode modeling --bug ${statement.id} --json`
+    ];
+  }
+  if (statement.kind === "plan") {
+    return [
+      `topogram sdlc plan explain ${statement.id} --json`,
+      `topogram query slice ./topo --plan ${statement.id} --json`
+    ];
+  }
+  return [`topogram query slice ./topo --${statement.kind} ${statement.id} --json`];
+}
+
 export function explain(workspaceRoot, resolved, id, options = {}) {
   const statement = resolved.graph.statements.find((s) => s.id === id);
   if (!statement) {
@@ -110,6 +159,9 @@ export function explain(workspaceRoot, resolved, id, options = {}) {
     last_transition: last,
     drift,
     blockers,
+    plans: statement.kind === "task" ? plansForTask(resolved.graph, statement, history) : undefined,
+    plan: statement.kind === "plan" ? summarizePlan(statement, history) : undefined,
+    recommended_queries: recommendedQueries(statement),
     next_action: nextAction,
     history: options.includeHistory ? history[id] || [] : undefined
   };