@topogram/cli 0.3.34

package/src/resolver/normalize.js

@@ -0,0 +1 @@
+export { normalizeStatement } from "./index.js";

package/src/resolver.js

@@ -0,0 +1 @@
+export * from "./resolver/index.js";

package/src/sdlc/adopt.js

@@ -0,0 +1,65 @@
+// `sdlc adopt` — brownfield onramp.
+//
+// Sets up the SDLC folder skeleton inside an existing topogram workspace
+// without backfilling historical artifacts. After running, an author can
+// `topogram sdlc new pitch <slug>` to start adding artifacts immediately.
+
+import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+
+const SDLC_FOLDERS = [
+  "pitches",
+  "requirements",
+  "acceptance_criteria",
+  "tasks",
+  "bugs",
+  "_archive"
+];
+
+function ensureFolder(root, name) {
+  const dir = path.join(root, "topogram", name);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+    return { name, created: true };
+  }
+  return { name, created: false };
+}
+
+function scanPressure(root) {
+  // Pressure scan: count statements per kind so the operator knows the
+  // workspace's current shape. We do not attempt to backfill — that's the
+  // operator's job after they pick a starting point.
+  const tg = path.join(root, "topogram");
+  if (!existsSync(tg)) return { error: `No 'topogram/' directory found at ${root}` };
+  let totalFiles = 0;
+  function walk(dir) {
+    for (const entry of readdirSync(dir)) {
+      const full = path.join(dir, entry);
+      const st = statSync(full);
+      if (st.isDirectory()) {
+        if (entry === "_archive" || entry.startsWith(".")) continue;
+        walk(full);
+      } else if (entry.endsWith(".tg")) {
+        totalFiles += 1;
+      }
+    }
+  }
+  walk(tg);
+  return { totalFiles };
+}
+
+export function sdlcAdopt(workspaceRoot) {
+  const root = path.resolve(workspaceRoot);
+  if (!existsSync(path.join(root, "topogram"))) {
+    return { ok: false, error: `No 'topogram/' directory at ${root}; run 'topogram new' first` };
+  }
+  const folders = SDLC_FOLDERS.map((name) => ensureFolder(root, name));
+  const pressure = scanPressure(root);
+  return {
+    ok: true,
+    workspaceRoot: root,
+    folders_created: folders.filter((f) => f.created).map((f) => f.name),
+    folders_existing: folders.filter((f) => !f.created).map((f) => f.name),
+    pressure
+  };
+}

package/src/sdlc/check.js

@@ -0,0 +1,86 @@
+// `sdlc check` — workspace-wide SDLC sanity scan.
+//
+// Surfaces:
+//   * Status drift (current status doesn't match last history entry)
+//   * DoD violations on currently-recorded status
+//   * Stale documents (linked component changed since publish)
+//   * Reciprocal blocks/blocked_by mismatches
+//
+// Returns { ok, errors, warnings } so the CLI can exit non-zero in
+// `--strict` mode.
+
+import { checkDoD } from "./dod/index.js";
+import { detectDriftedStatus, readHistory } from "./history.js";
+
+const SDLC_KINDS = new Set([
+  "pitch",
+  "requirement",
+  "acceptance_criterion",
+  "task",
+  "bug"
+]);
+
+function checkBlockingReciprocity(graph) {
+  const warnings = [];
+  const tasks = (graph.byKind?.task || []).filter((task) => !task.archived);
+  const tasksById = new Map(tasks.map((t) => [t.id, t]));
+  for (const task of tasks) {
+    for (const ref of task.blocks || []) {
+      const targetId = typeof ref === "string" ? ref : ref?.id;
+      const target = tasksById.get(targetId);
+      if (!target) continue;
+      const reciprocal = (target.blockedBy || []).some((r) => (typeof r === "string" ? r : r?.id) === task.id);
+      if (!reciprocal) {
+        warnings.push({
+          id: task.id,
+          message: `task ${task.id} blocks ${target.id}, but ${target.id} does not list ${task.id} in blocked_by`
+        });
+      }
+    }
+  }
+  return warnings;
+}
+
+export function checkWorkspace(workspaceRoot, resolved) {
+  const errors = [];
+  const warnings = [];
+  const history = readHistory(workspaceRoot);
+  if (history.__error) {
+    warnings.push({ message: `cannot read SDLC history sidecar: ${history.__error}` });
+  }
+
+  const byId = new Map(resolved.graph.statements.map((s) => [s.id, s]));
+
+  for (const statement of resolved.graph.statements) {
+    if (statement.archived) continue;
+    if (!SDLC_KINDS.has(statement.kind)) continue;
+
+    const drift = detectDriftedStatus(history, statement);
+    if (drift) {
+      warnings.push({
+        id: statement.id,
+        message: `status drift: history records '${drift.historyStatus}' but current is '${drift.currentStatus}'`
+      });
+    }
+
+    // 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 });
+    for (const err of dod.errors) {
+      errors.push({ id: statement.id, message: `DoD: ${err}` });
+    }
+    for (const warn of dod.warnings) {
+      warnings.push({ id: statement.id, message: `DoD: ${warn}` });
+    }
+  }
+
+  for (const w of checkBlockingReciprocity(resolved.graph)) {
+    warnings.push(w);
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings
+  };
+}

package/src/sdlc/dod/acceptance-criterion.js

@@ -0,0 +1,22 @@
+// Acceptance criterion DoD per status.
+
+export function checkDoD(ac, targetStatus, graph) {
+  const errors = [];
+  const warnings = [];
+
+  if (!ac.requirement) {
+    errors.push("acceptance_criterion must reference a requirement");
+  }
+
+  if (targetStatus === "approved") {
+    const byId = graph?.byId;
+    if (byId && ac.requirement?.id) {
+      const req = byId.get(ac.requirement.id);
+      if (req && req.status === "draft") {
+        warnings.push(`acceptance_criterion approved while parent requirement '${req.id}' is still draft`);
+      }
+    }
+  }
+
+  return { satisfied: errors.length === 0, errors, warnings };
+}

package/src/sdlc/dod/bug.js

@@ -0,0 +1,26 @@
+// Bug DoD per status.
+
+export function checkDoD(bug, targetStatus, graph) {
+  const errors = [];
+  const warnings = [];
+
+  if (targetStatus === "fixed" || targetStatus === "verified") {
+    if (!bug.fixedIn || bug.fixedIn.length === 0) {
+      errors.push(`status '${targetStatus}' requires field 'fixed_in' (the task that fixed it)`);
+    }
+  }
+
+  if (targetStatus === "verified") {
+    if (!bug.fixedInVerification || bug.fixedInVerification.length === 0) {
+      errors.push("verified bug must reference 'fixed_in_verification' (the verification that proved the fix)");
+    }
+  }
+
+  if (targetStatus === "wont-fix") {
+    if (!bug.reproduction) {
+      warnings.push("wont-fix bug without `reproduction` is hard to revisit later");
+    }
+  }
+
+  return { satisfied: errors.length === 0, errors, warnings };
+}

package/src/sdlc/dod/document.js

@@ -0,0 +1,23 @@
+// Document DoD per status. Documents are markdown-only, so the input here
+// is the normalized doc record from `engine/src/workspace-docs.js`.
+
+export function checkDoD(doc, targetStatus, graph) {
+  const errors = [];
+  const warnings = [];
+
+  if (targetStatus === "review" || targetStatus === "published") {
+    if (!doc.title) errors.push("document must have a title");
+    if (!doc.summary) warnings.push("document should have a summary for indexing");
+  }
+
+  if (targetStatus === "published") {
+    if (!doc.appVersion && !doc.metadata?.app_version) {
+      warnings.push("published document should record `app_version` to anchor staleness");
+    }
+    if (doc.confidence === "low") {
+      warnings.push("publishing a low-confidence document — consider review first");
+    }
+  }
+
+  return { satisfied: errors.length === 0, errors, warnings };
+}

package/src/sdlc/dod/index.js

@@ -0,0 +1,25 @@
+// Per-kind dispatch for DoD checks.
+
+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 checkBug } from "./bug.js";
+import { checkDoD as checkDocument } from "./document.js";
+
+const CHECKS = {
+  pitch: checkPitch,
+  requirement: checkRequirement,
+  acceptance_criterion: checkAcceptanceCriterion,
+  task: checkTask,
+  bug: checkBug,
+  document: checkDocument
+};
+
+export function checkDoD(kind, statement, targetStatus, graph) {
+  const check = CHECKS[kind];
+  if (!check) {
+    return { satisfied: true, errors: [], warnings: [] };
+  }
+  return check(statement, targetStatus, graph);
+}

package/src/sdlc/dod/pitch.js

@@ -0,0 +1,23 @@
+// Pitch DoD per status.
+//
+// Returns { satisfied, errors, warnings }. Errors block the transition;
+// warnings advise the author/agent.
+
+export function checkDoD(pitch, targetStatus, graph) {
+  const errors = [];
+  const warnings = [];
+
+  if (targetStatus === "shaped" || targetStatus === "submitted" || targetStatus === "approved") {
+    if (!pitch.appetite) errors.push("appetite must be filled before leaving draft");
+    if (!pitch.problem) errors.push("problem must be filled before leaving draft");
+    if (!pitch.solutionSketch) warnings.push("solution_sketch is recommended");
+  }
+
+  if (targetStatus === "approved") {
+    if (!pitch.affects || pitch.affects.length === 0) {
+      warnings.push("approved pitch has no `affects` references (no downstream impact recorded)");
+    }
+  }
+
+  return { satisfied: errors.length === 0, errors, warnings };
+}

package/src/sdlc/dod/requirement.js

@@ -0,0 +1,34 @@
+// Requirement DoD per status.
+
+export function checkDoD(requirement, targetStatus, graph) {
+  const errors = [];
+  const warnings = [];
+
+  if (targetStatus === "in-review" || targetStatus === "approved") {
+    if (!requirement.affects || requirement.affects.length === 0) {
+      errors.push("requirement must list at least one `affects` target before review");
+    }
+  }
+
+  if (targetStatus === "approved") {
+    if (!requirement.acceptanceCriteria || requirement.acceptanceCriteria.length === 0) {
+      errors.push("approved requirement must have at least one acceptance_criterion");
+    }
+    const acs = requirement.acceptanceCriteria || [];
+    const byId = graph?.byId;
+    if (byId) {
+      const undraftedAcs = acs.filter((id) => byId.get(id)?.status === "draft");
+      if (undraftedAcs.length > 0) {
+        warnings.push(`approved requirement has draft ACs: ${undraftedAcs.join(", ")}`);
+      }
+    }
+  }
+
+  if (targetStatus === "superseded") {
+    if (!requirement.supersedes || requirement.supersedes.length === 0) {
+      warnings.push("superseded status without listing what supersedes it loses traceability");
+    }
+  }
+
+  return { satisfied: errors.length === 0, errors, warnings };
+}

package/src/sdlc/dod/task.js

@@ -0,0 +1,39 @@
+// Task DoD per status.
+
+export function checkDoD(task, targetStatus, graph) {
+  const errors = [];
+  const warnings = [];
+
+  if (targetStatus === "claimed" || targetStatus === "in-progress" || targetStatus === "done") {
+    if (!task.claimedBy || task.claimedBy.length === 0) {
+      errors.push(`status '${targetStatus}' requires field 'claimed_by'`);
+    }
+  }
+
+  if (targetStatus === "in-progress") {
+    const byId = graph?.byId;
+    const blockers = task.blockedBy || [];
+    if (byId && blockers.length > 0) {
+      const stillBlocking = blockers
+        .map((ref) => byId.get(typeof ref === "string" ? ref : ref?.id))
+        .filter((b) => b && b.status !== "done");
+      if (stillBlocking.length > 0) {
+        errors.push(
+          `cannot start work — blocked_by tasks not yet done: ${stillBlocking.map((b) => b.id).join(", ")}`
+        );
+      }
+    }
+  }
+
+  if (targetStatus === "done") {
+    if (!task.satisfies || task.satisfies.length === 0) {
+      warnings.push("done task without `satisfies` references is hard to trace");
+    }
+    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");
+    }
+  }
+
+  return { satisfied: errors.length === 0, errors, warnings };
+}

package/src/sdlc/explain.js

@@ -0,0 +1,116 @@
+// `sdlc explain <id>` — agent-facing inspector.
+//
+// Returns a structured payload an agent can script against. The
+// `next_action` shape is intentionally stable across versions:
+//
+//   {
+//     kind: "transition" | "work" | "wait" | "review" | "none",
+//     to?: <statusName>,            // when kind === "transition"
+//     reason: <human-readable>,
+//     blockers?: [<id>, ...]        // when kind === "wait"
+//   }
+
+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";
+
+function pickNextStatus(legal) {
+  // Prefer the canonical forward path (skipping rollback options).
+  const FORWARD_BIAS = [
+    "in-review",
+    "approved",
+    "submitted",
+    "shaped",
+    "claimed",
+    "in-progress",
+    "done",
+    "fixed",
+    "verified",
+    "review",
+    "published"
+  ];
+  for (const candidate of FORWARD_BIAS) {
+    if (legal.includes(candidate)) return candidate;
+  }
+  return legal[0] || null;
+}
+
+function buildBlockers(statement, byId) {
+  if (statement.kind !== "task") return [];
+  const blockers = statement.blockedBy || [];
+  return blockers
+    .map((ref) => {
+      const id = typeof ref === "string" ? ref : ref?.id;
+      const target = byId.get(id);
+      return target && target.status !== "done" ? id : null;
+    })
+    .filter(Boolean);
+}
+
+export function explain(workspaceRoot, resolved, id, options = {}) {
+  const statement = resolved.graph.statements.find((s) => s.id === id);
+  if (!statement) {
+    return { ok: false, error: `Statement '${id}' not found` };
+  }
+
+  const byId = new Map(resolved.graph.statements.map((s) => [s.id, s]));
+  const history = readHistory(workspaceRoot);
+  const last = lastTransition(history, id);
+  const drift = detectDriftedStatus(history, statement);
+  const blockers = buildBlockers(statement, byId);
+
+  const legal = legalTransitionsFor(statement.kind, statement.status);
+  const nextStatus = pickNextStatus(legal);
+  const dod = nextStatus ? checkDoD(statement.kind, statement, nextStatus, { byId }) : { satisfied: true, errors: [], warnings: [] };
+  const dodCurrent = checkDoD(statement.kind, statement, statement.status, { byId });
+
+  let nextAction;
+  if (blockers.length > 0) {
+    nextAction = {
+      kind: "wait",
+      reason: `blocked_by tasks not yet done`,
+      blockers
+    };
+  } else if (drift) {
+    nextAction = {
+      kind: "review",
+      reason: `status drift: history says '${drift.historyStatus}', current says '${drift.currentStatus}'`
+    };
+  } else if (!dodCurrent.satisfied) {
+    nextAction = {
+      kind: "work",
+      reason: `current-status DoD failing: ${dodCurrent.errors.join("; ")}`
+    };
+  } else if (isTerminalStatus(statement.kind, statement.status)) {
+    nextAction = { kind: "none", reason: "terminal status" };
+  } else if (nextStatus && dod.satisfied) {
+    nextAction = {
+      kind: "transition",
+      to: nextStatus,
+      reason: `forward path is open (${statement.status} → ${nextStatus})`
+    };
+  } else if (nextStatus) {
+    nextAction = {
+      kind: "work",
+      reason: `next status '${nextStatus}' DoD not satisfied: ${dod.errors.join("; ")}`
+    };
+  } else {
+    nextAction = { kind: "none", reason: "no legal forward transitions" };
+  }
+
+  return {
+    ok: true,
+    id: statement.id,
+    kind: statement.kind,
+    status: statement.status,
+    legal_transitions: legal,
+    dod_current: dodCurrent,
+    dod_next: nextStatus ? { target: nextStatus, ...dod } : null,
+    last_transition: last,
+    drift,
+    blockers,
+    next_action: nextAction,
+    history: options.includeHistory ? history[id] || [] : undefined
+  };
+}

package/src/sdlc/history.js

@@ -0,0 +1,80 @@
+// SDLC history sidecar.
+//
+// Stored at `<topogram-root>/.topogram-sdlc-history.json` as a
+// JSON object keyed by statement id. Each entry is an append-only array of
+// transition records:
+//
+//   {
+//     "task_audit_logging": [
+//       { "from": "claimed", "to": "in-progress", "at": "2026-05-01T12:00:00Z", "by": "agent-7", "note": "..." },
+//       { "from": "in-progress", "to": "done", "at": "2026-05-02T09:30:00Z", "by": "agent-7" }
+//     ]
+//   }
+//
+// `topogram check` consults this file to surface "status edited outside the
+// CLI" warnings when an artifact's current status doesn't match the last
+// recorded transition.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { topogramRootForSdlc } from "./paths.js";
+
+const HISTORY_FILENAME = ".topogram-sdlc-history.json";
+
+export function historyPath(workspaceRoot) {
+  return path.join(topogramRootForSdlc(workspaceRoot), HISTORY_FILENAME);
+}
+
+export function readHistory(workspaceRoot) {
+  const file = historyPath(workspaceRoot);
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch (err) {
+    return { __error: err.message };
+  }
+}
+
+export function writeHistory(workspaceRoot, history) {
+  const file = historyPath(workspaceRoot);
+  writeFileSync(file, JSON.stringify(history, null, 2) + "\n", "utf8");
+}
+
+export function appendTransition(workspaceRoot, id, record) {
+  const history = readHistory(workspaceRoot);
+  if (history.__error) {
+    throw new Error(`Cannot read history file: ${history.__error}`);
+  }
+  if (!history[id]) history[id] = [];
+  history[id].push({
+    from: record.from,
+    to: record.to,
+    at: record.at || new Date().toISOString(),
+    by: record.by || null,
+    note: record.note || null
+  });
+  writeHistory(workspaceRoot, history);
+  return history[id];
+}
+
+export function lastTransition(history, id) {
+  const entries = history[id];
+  if (!entries || entries.length === 0) return null;
+  return entries[entries.length - 1];
+}
+
+export function detectDriftedStatus(history, statement) {
+  // If the last recorded transition's `to` doesn't match the statement's
+  // current status, the artifact was edited outside the CLI.
+  const last = lastTransition(history, statement.id);
+  if (!last) return null;
+  if (last.to !== statement.status) {
+    return {
+      id: statement.id,
+      kind: statement.kind,
+      historyStatus: last.to,
+      currentStatus: statement.status
+    };
+  }
+  return null;
+}

package/src/sdlc/paths.js

@@ -0,0 +1,11 @@
+import path from "node:path";
+
+export function topogramRootForSdlc(inputPath) {
+  const absolute = path.resolve(inputPath);
+  return path.basename(absolute) === "topogram" ? absolute : path.join(absolute, "topogram");
+}
+
+export function projectRootForSdlc(inputPath) {
+  const absolute = path.resolve(inputPath);
+  return path.basename(absolute) === "topogram" ? path.dirname(absolute) : absolute;
+}

package/src/sdlc/release.js

@@ -0,0 +1,106 @@
+// `topogram release --app-version X.Y.Z` — single best-effort checkpointed
+// operation:
+//   1. Assemble release notes (from current/archived terminal-status data)
+//   2. Stamp `app_version` on documents whose `app_version` is missing or
+//      older than the release version
+//   3. Archive eligible terminal-status artifacts
+//
+// `--dry-run` prints the planned mutations without touching disk.
+
+import { readFileSync, writeFileSync } from "node:fs";
+
+import { parsePath } from "../parser.js";
+import { resolveWorkspace } from "../resolver/index.js";
+import { generateSdlcReleaseNotes } from "../generator/sdlc/release-notes.js";
+import { archiveBatch, archiveEligibleStatements } from "../archive/archive.js";
+
+function parseComparableVersion(value) {
+  if (value == null || value === "") return null;
+  const match = String(value).trim().match(/^v?(\d+(?:\.\d+)*)(?:[-+].*)?$/i);
+  if (!match) return null;
+  return match[1].split(".").map((part) => Number.parseInt(part, 10));
+}
+
+function compareVersions(left, right) {
+  const leftParts = parseComparableVersion(left);
+  const rightParts = parseComparableVersion(right);
+  if (!leftParts || !rightParts) return null;
+  const length = Math.max(leftParts.length, rightParts.length);
+  for (let i = 0; i < length; i += 1) {
+    const leftPart = leftParts[i] ?? 0;
+    const rightPart = rightParts[i] ?? 0;
+    if (leftPart < rightPart) return -1;
+    if (leftPart > rightPart) return 1;
+  }
+  return 0;
+}
+
+function shouldStampDocVersion(existingVersion, appVersion) {
+  if (existingVersion == null || existingVersion === "") return true;
+  const comparison = compareVersions(existingVersion, appVersion);
+  return comparison === -1;
+}
+
+function stampDocsWithVersion(docs, appVersion, options = {}) {
+  const planned = [];
+  const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n/;
+  for (const doc of docs) {
+    if (doc.parseError || !doc.file) continue;
+    let raw;
+    try {
+      raw = readFileSync(doc.file, "utf8");
+    } catch {
+      continue;
+    }
+    const match = raw.match(FRONTMATTER_RE);
+    if (!match) continue;
+    const frontmatter = match[1];
+    const existingVersion = doc.metadata?.app_version || null;
+    if (!shouldStampDocVersion(existingVersion, appVersion)) continue;
+
+    const updated = frontmatter.includes("app_version:")
+      ? frontmatter.replace(/app_version:.*$/m, `app_version: ${appVersion}`)
+      : frontmatter + `\napp_version: ${appVersion}`;
+    const newRaw = raw.replace(FRONTMATTER_RE, `---\n${updated}\n---\n`);
+    planned.push({ file: doc.file, before: doc.metadata?.app_version || null, after: appVersion });
+    if (!options.dryRun) {
+      writeFileSync(doc.file, newRaw, "utf8");
+    }
+  }
+  return planned;
+}
+
+export function runRelease(workspaceRoot, options = {}) {
+  if (!options.appVersion) {
+    return { ok: false, error: "release requires --app-version <label>" };
+  }
+
+  const ast = parsePath(workspaceRoot);
+  const resolved = resolveWorkspace(ast);
+  if (!resolved.ok) {
+    return { ok: false, error: "workspace failed validation; cannot release", validation: resolved.validation };
+  }
+
+  const releaseNotes = generateSdlcReleaseNotes(resolved.graph, {
+    appVersion: options.appVersion,
+    sinceTag: options.sinceTag
+  });
+
+  const docPlan = stampDocsWithVersion(ast.docs || [], options.appVersion, { dryRun: options.dryRun });
+
+  const archiveCandidates = archiveEligibleStatements(resolved, {});
+  const archiveResult = archiveBatch(workspaceRoot, archiveCandidates, {
+    dryRun: options.dryRun,
+    by: options.actor,
+    release: options.appVersion
+  });
+
+  return {
+    ok: true,
+    appVersion: options.appVersion,
+    dryRun: options.dryRun === true,
+    release_notes: releaseNotes,
+    document_app_version_updates: docPlan,
+    archive: { candidates: archiveCandidates, ...archiveResult }
+  };
+}