@topogram/cli 0.3.71 → 0.3.73

package/src/resolver/enrich/task.js

@@ -4,6 +4,7 @@
 // Back-link arrays:
 //   blockingMe   — tasks whose `blocks` references this task (reciprocal of blocked_by)
 //   blockedByMe  — tasks whose `blocked_by` references this task (reciprocal of blocks)
+//   plans         — implementation plans attached to this task
 //
 // Note: we deliberately compute *both* directions even though `blocks` and
 // `blocked_by` are reciprocal, because authors only write one side. The
@@ -13,6 +14,7 @@
 export function enrichTask(task, index) {
   return {
     blockingMe: (index.tasksThatBlockTarget.get(task.id) || []).slice().sort(),
-    blockedByMe: (index.tasksBlockedByTarget.get(task.id) || []).slice().sort()
+    blockedByMe: (index.tasksBlockedByTarget.get(task.id) || []).slice().sort(),
+    plans: (index.plansByTask.get(task.id) || []).slice().sort()
   };
 }

package/src/resolver/index.js

@@ -114,6 +114,7 @@ export function resolveWorkspace(workspaceAst) {
         pitches: [],
         requirements: [],
         tasks: [],
+        plans: [],
         bugs: [],
         documents: []
       });
@@ -130,6 +131,7 @@ export function resolveWorkspace(workspaceAst) {
     pitch: "pitches",
     requirement: "requirements",
     task: "tasks",
+    plan: "plans",
     bug: "bugs"
   };
   for (const statement of resolvedStatements) {
@@ -175,6 +177,7 @@ export function resolveWorkspace(workspaceAst) {
     rulesByFromRequirement: new Map(),
     tasksThatBlockTarget: new Map(),
     tasksBlockedByTarget: new Map(),
+    plansByTask: new Map(),
     affectedByPitches: new Map(),
     affectedByRequirements: new Map(),
     affectedByTasks: new Map(),
@@ -227,6 +230,9 @@ export function resolveWorkspace(workspaceAst) {
         pushIndexFromList(sdlcIndex.tasksThatBlockTarget, statement.blocks, statement.id);
         pushIndexFromList(sdlcIndex.tasksBlockedByTarget, statement.blockedBy, statement.id);
         break;
+      case "plan":
+        pushIndex(sdlcIndex.plansByTask, statement.task?.id, statement.id);
+        break;
       case "bug":
         pushIndexFromList(sdlcIndex.affectedByBugs, statement.affects, statement.id);
         pushIndexFromList(sdlcIndex.rulesViolatedByBug, statement.violates, statement.id);

package/src/resolver/normalize.js

@@ -43,6 +43,13 @@ import {
   parseProjectionHttpResponsesBlock,
   parseProjectionHttpStatusBlock
 } from "./projections-api.js";
+import {
+  parseProjectionCliCommandsBlock,
+  parseProjectionCliEffectsBlock,
+  parseProjectionCliExamplesBlock,
+  parseProjectionCliOptionsBlock,
+  parseProjectionCliOutputsBlock
+} from "./projections-cli.js";
 import {
   parseProjectionUiActionsBlock,
   parseProjectionUiAppShellBlock,
@@ -67,6 +74,7 @@ import {
   parseProjectionDbTablesBlock,
   parseProjectionGeneratorDefaultsBlock
 } from "./projections-db.js";
+import { parsePlanSteps } from "../sdlc/plan-steps.js";
 
 export function normalizeStatement(statement, registry) {
   const fieldMap = collectFieldMap(statement);
@@ -209,6 +217,11 @@ export function normalizeStatement(statement, registry) {
         httpDownload: parseProjectionHttpDownloadBlock(statement, registry),
         httpAuthz: parseProjectionHttpAuthzBlock(statement, registry),
         httpCallbacks: parseProjectionHttpCallbacksBlock(statement, registry),
+        commands: parseProjectionCliCommandsBlock(statement, registry),
+        commandOptions: parseProjectionCliOptionsBlock(statement),
+        commandOutputs: parseProjectionCliOutputsBlock(statement, registry),
+        commandEffects: parseProjectionCliEffectsBlock(statement),
+        commandExamples: parseProjectionCliExamplesBlock(statement),
         uiScreens: parseProjectionUiScreensBlock(statement, registry),
         screens: parseProjectionUiScreensBlock(statement, registry),
         uiCollections: parseProjectionUiCollectionsBlock(statement),
@@ -343,9 +356,11 @@ export function normalizeStatement(statement, registry) {
         ...base,
         priority: symbolValue(getFieldValue(statement, "priority")),
         workType: symbolValue(getFieldValue(statement, "work_type")),
+        disposition: symbolValue(getFieldValue(statement, "disposition")),
         affects: resolveReferenceList(registry, getFieldValue(statement, "affects")),
         satisfies: resolveReferenceList(registry, getFieldValue(statement, "satisfies")),
         acceptanceRefs: resolveReferenceList(registry, getFieldValue(statement, "acceptance_refs")),
+        verificationRefs: resolveReferenceList(registry, getFieldValue(statement, "verification_refs")),
         blocks: resolveReferenceList(registry, getFieldValue(statement, "blocks")),
         blockedBy: resolveReferenceList(registry, getFieldValue(statement, "blocked_by")),
         claimedBy: resolveReferenceList(registry, getFieldValue(statement, "claimed_by")),
@@ -356,6 +371,22 @@ export function normalizeStatement(statement, registry) {
         updated: stringValue(getFieldValue(statement, "updated")),
         resolvedDomain: resolveDomainTag(statement, registry)
       };
+    case "plan":
+      return {
+        ...base,
+        task: getFieldValue(statement, "task")
+          ? {
+              id: symbolValue(getFieldValue(statement, "task")),
+              target: toRef(resolveReference(registry, symbolValue(getFieldValue(statement, "task"))))
+            }
+          : null,
+        priority: symbolValue(getFieldValue(statement, "priority")),
+        notes: stringValue(getFieldValue(statement, "notes")),
+        outcome: stringValue(getFieldValue(statement, "outcome")),
+        steps: parsePlanSteps(getFieldValue(statement, "steps")),
+        updated: stringValue(getFieldValue(statement, "updated")),
+        resolvedDomain: resolveDomainTag(statement, registry)
+      };
     case "bug":
       return {
         ...base,

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
   };