@topogram/cli 0.3.34

package/src/sdlc/scaffold.js

@@ -0,0 +1,89 @@
+// `sdlc new <kind> <slug>` — scaffold a new SDLC `.tg` file with sensible
+// defaults so the author can fill in details rather than start blank.
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+const TEMPLATES = {
+  pitch: (slug) => `pitch pitch_${slug} {
+  name "${humanize(slug)}"
+  description "Why this work matters."
+  appetite "TBD — small / medium / large"
+  problem "Describe the user-visible problem."
+  solution_sketch "Describe the proposed shape, not the implementation."
+  rabbit_holes "Known traps to avoid."
+  no_go_areas "Things this pitch deliberately won't touch."
+  affects []
+  priority medium
+  status draft
+}
+`,
+  requirement: (slug) => `requirement req_${slug} {
+  name "${humanize(slug)}"
+  description "What the system must do."
+  affects []
+  introduces_rules []
+  respects_rules []
+  priority medium
+  status draft
+}
+`,
+  acceptance_criterion: (slug) => `acceptance_criterion ac_${slug} {
+  name "${humanize(slug)}"
+  description "Given <state>, when <action>, then <observable>."
+  requirement req_TODO
+  status draft
+}
+`,
+  task: (slug) => `task task_${slug} {
+  name "${humanize(slug)}"
+  description "What the agent or human will do."
+  satisfies []
+  acceptance_refs []
+  affects []
+  blocked_by []
+  priority medium
+  work_type implementation
+  status unclaimed
+}
+`,
+  bug: (slug) => `bug bug_${slug} {
+  name "${humanize(slug)}"
+  description "What goes wrong."
+  reproduction "Steps to reproduce."
+  affects []
+  violates []
+  priority medium
+  severity medium
+  status open
+}
+`
+};
+
+function humanize(slug) {
+  return slug
+    .replace(/[_-]+/g, " ")
+    .replace(/\b\w/g, (m) => m.toUpperCase());
+}
+
+export function scaffoldNew(workspaceRoot, kind, slug) {
+  if (!TEMPLATES[kind]) {
+    return { ok: false, error: `Unsupported kind '${kind}' (allowed: ${Object.keys(TEMPLATES).join(", ")})` };
+  }
+  if (!slug || !/^[a-z][a-z0-9_]*$/.test(slug)) {
+    return { ok: false, error: `Invalid slug '${slug}' — must match /^[a-z][a-z0-9_]*$/` };
+  }
+  const targetDir = path.join(workspaceRoot, "topogram", `${kind === "acceptance_criterion" ? "acceptance_criteria" : kind + "s"}`);
+  if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true });
+  const targetFile = path.join(targetDir, `${slug}.tg`);
+  if (existsSync(targetFile)) {
+    return { ok: false, error: `Refusing to overwrite '${targetFile}'` };
+  }
+  writeFileSync(targetFile, TEMPLATES[kind](slug), "utf8");
+  return {
+    ok: true,
+    kind,
+    slug,
+    file: targetFile
+  };
+}

package/src/sdlc/status-filter.js

@@ -0,0 +1,54 @@
+// Default-active status filtering for SDLC queries.
+//
+// Most CLI surfaces (board, slice, traceability) want to omit terminal
+// statuses unless the caller passes `--include-status` or
+// `--include-archived`. This module centralizes the rules.
+
+import {
+  isArchivableStatus,
+  isTerminalStatus
+} from "./transitions/index.js";
+
+const ALWAYS_VISIBLE_TERMINAL_STATUSES = new Set([
+  "approved",
+  "superseded",
+  "verified",
+  "wont-fix",
+  "done"
+]);
+
+export function defaultActiveStatuses(kind) {
+  // For a given kind, the statuses that show up in queries by default.
+  // Terminal statuses are still visible if they aren't archive-eligible
+  // (e.g. requirement.superseded is terminal but stays for traceability).
+  switch (kind) {
+    case "pitch":
+      return new Set(["draft", "shaped", "submitted", "approved"]);
+    case "requirement":
+      return new Set(["draft", "in-review", "approved", "superseded"]);
+    case "acceptance_criterion":
+      return new Set(["draft", "approved", "superseded"]);
+    case "task":
+      return new Set(["unclaimed", "claimed", "in-progress", "blocked"]);
+    case "bug":
+      return new Set(["open", "in-progress", "fixed"]);
+    case "document":
+      return new Set(["draft", "review", "published"]);
+    default:
+      return null;
+  }
+}
+
+export function filterStatements(statements, options = {}) {
+  const includeArchived = options.includeArchived === true;
+  const includeStatuses = options.includeStatuses ? new Set(options.includeStatuses) : null;
+  return statements.filter((s) => {
+    if (s.archived && !includeArchived) return false;
+    const defaults = defaultActiveStatuses(s.kind);
+    if (!defaults) return true;
+    if (includeStatuses && includeStatuses.has(s.status)) return true;
+    return defaults.has(s.status);
+  });
+}
+
+export { isTerminalStatus, isArchivableStatus, ALWAYS_VISIBLE_TERMINAL_STATUSES };

package/src/sdlc/transition.js

@@ -0,0 +1,112 @@
+// SDLC transition orchestrator.
+//
+// `transitionStatement(workspace, id, targetStatus, options)`:
+//   1. Locate the statement in the resolved graph.
+//   2. Validate the transition with the kind's state machine.
+//   3. Run DoD (Definition of Done) checks. Errors block; warnings advise.
+//   4. Surgically rewrite the `status` value in the source `.tg` file.
+//   5. Append a history record to `.topogram-sdlc-history.json`.
+//
+// The rewrite is byte-precise — we only swap the status symbol token, so
+// formatting, comments, and adjacent fields are untouched.
+
+import { readFileSync, writeFileSync } from "node:fs";
+
+import { parsePath } from "../parser.js";
+import { resolveWorkspace } from "../resolver/index.js";
+import { validateTransition, isArchivableStatus } from "./transitions/index.js";
+import { checkDoD } from "./dod/index.js";
+import { appendTransition } from "./history.js";
+
+function findStatementInAst(workspaceAst, id) {
+  for (const file of workspaceAst.files) {
+    for (const statement of file.statements) {
+      if (statement.id === id) {
+        return statement;
+      }
+    }
+  }
+  return null;
+}
+
+function findStatusField(statement) {
+  for (const field of statement.fields) {
+    if (field.key === "status") return field;
+  }
+  return null;
+}
+
+function rewriteStatusInSource(source, statusField, newStatus) {
+  const start = statusField.value.loc.start.offset;
+  const end = statusField.value.loc.end.offset;
+  return source.slice(0, start) + newStatus + source.slice(end);
+}
+
+export function transitionStatement(workspaceRoot, id, targetStatus, options = {}) {
+  const ast = parsePath(workspaceRoot);
+  const resolved = resolveWorkspace(ast);
+  if (!resolved.ok) {
+    return {
+      ok: false,
+      error: "workspace failed validation; cannot transition",
+      validation: resolved.validation
+    };
+  }
+
+  const astStatement = findStatementInAst(ast, id);
+  if (!astStatement) {
+    return { ok: false, error: `Statement '${id}' not found` };
+  }
+
+  const resolvedStatement = resolved.graph.statements.find((s) => s.id === id);
+  if (!resolvedStatement) {
+    return { ok: false, error: `Statement '${id}' not found in resolved graph` };
+  }
+
+  const fromStatus = resolvedStatement.status;
+  const transition = validateTransition(astStatement.kind, fromStatus, targetStatus);
+  if (!transition.ok) {
+    return { ok: false, error: transition.error };
+  }
+
+  const byId = new Map(resolved.graph.statements.map((s) => [s.id, s]));
+  const dod = checkDoD(astStatement.kind, resolvedStatement, targetStatus, { byId });
+  if (!dod.satisfied && !options.force) {
+    return {
+      ok: false,
+      error: `Definition of Done not satisfied: ${dod.errors.join("; ")}`,
+      dod
+    };
+  }
+
+  const statusField = findStatusField(astStatement);
+  if (!statusField) {
+    return { ok: false, error: `Statement '${id}' has no status field to rewrite` };
+  }
+
+  const sourcePath = astStatement.loc.file;
+  const original = readFileSync(sourcePath, "utf8");
+  const rewritten = rewriteStatusInSource(original, statusField, targetStatus);
+
+  if (!options.dryRun) {
+    writeFileSync(sourcePath, rewritten, "utf8");
+    appendTransition(workspaceRoot, id, {
+      from: fromStatus,
+      to: targetStatus,
+      by: options.actor || null,
+      note: options.note || null
+    });
+  }
+
+  return {
+    ok: true,
+    id,
+    kind: astStatement.kind,
+    from: fromStatus,
+    to: targetStatus,
+    file: sourcePath,
+    archivable: isArchivableStatus(astStatement.kind, targetStatus),
+    dod,
+    dryRun: options.dryRun === true
+  };
+}

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

@@ -0,0 +1,28 @@
+// Acceptance criterion state machine.
+//
+// draft → approved → superseded
+//
+// ACs are always-live like requirements.
+
+export const LEGAL_TRANSITIONS = {
+  draft: ["approved"],
+  approved: ["superseded", "draft"],
+  superseded: []
+};
+
+export const TERMINAL_STATUSES = new Set(["superseded"]);
+export const ARCHIVABLE_STATUSES = new Set();
+
+export function validateTransition(from, to) {
+  const allowed = LEGAL_TRANSITIONS[from];
+  if (!allowed) {
+    return { ok: false, error: `Unknown acceptance_criterion status '${from}'` };
+  }
+  if (!allowed.includes(to)) {
+    return {
+      ok: false,
+      error: `Acceptance criterion cannot transition from '${from}' to '${to}' — allowed: ${allowed.join(", ") || "(terminal)"}`
+    };
+  }
+  return { ok: true };
+}

package/src/sdlc/transitions/bug.js

@@ -0,0 +1,31 @@
+// Bug state machine.
+//
+// open → in-progress → fixed → verified
+//   └──────────┴────────┴────→ wont-fix
+//
+// `verified` and `wont-fix` are archive-eligible.
+
+export const LEGAL_TRANSITIONS = {
+  open: ["in-progress", "wont-fix"],
+  "in-progress": ["fixed", "open", "wont-fix"],
+  fixed: ["verified", "in-progress", "wont-fix"],
+  verified: ["in-progress"],
+  "wont-fix": ["open"]
+};
+
+export const TERMINAL_STATUSES = new Set(["verified", "wont-fix"]);
+export const ARCHIVABLE_STATUSES = new Set(["verified", "wont-fix"]);
+
+export function validateTransition(from, to) {
+  const allowed = LEGAL_TRANSITIONS[from];
+  if (!allowed) {
+    return { ok: false, error: `Unknown bug status '${from}'` };
+  }
+  if (!allowed.includes(to)) {
+    return {
+      ok: false,
+      error: `Bug cannot transition from '${from}' to '${to}' — allowed: ${allowed.join(", ")}`
+    };
+  }
+  return { ok: true };
+}

package/src/sdlc/transitions/document.js

@@ -0,0 +1,29 @@
+// Document state machine (mirrors workspace-docs.DOC_STATUSES extension).
+//
+// draft → review → published → archived
+//                      ↓
+//                    review (when linked component changes — staleness signal)
+
+export const LEGAL_TRANSITIONS = {
+  draft: ["review"],
+  review: ["published", "draft"],
+  published: ["review", "archived"],
+  archived: ["draft"]
+};
+
+export const TERMINAL_STATUSES = new Set(["archived"]);
+export const ARCHIVABLE_STATUSES = new Set(["archived"]);
+
+export function validateTransition(from, to) {
+  const allowed = LEGAL_TRANSITIONS[from];
+  if (!allowed) {
+    return { ok: false, error: `Unknown document status '${from}'` };
+  }
+  if (!allowed.includes(to)) {
+    return {
+      ok: false,
+      error: `Document cannot transition from '${from}' to '${to}' — allowed: ${allowed.join(", ")}`
+    };
+  }
+  return { ok: true };
+}

package/src/sdlc/transitions/index.js

@@ -0,0 +1,56 @@
+// Per-kind dispatch for SDLC transitions.
+
+import * as pitch from "./pitch.js";
+import * as requirement from "./requirement.js";
+import * as acceptanceCriterion from "./acceptance-criterion.js";
+import * as task from "./task.js";
+import * as bug from "./bug.js";
+import * as document from "./document.js";
+
+const MODULES = {
+  pitch,
+  requirement,
+  acceptance_criterion: acceptanceCriterion,
+  task,
+  bug,
+  document
+};
+
+export function getTransitionModule(kind) {
+  return MODULES[kind] || null;
+}
+
+export function legalTransitionsFor(kind, from) {
+  const mod = MODULES[kind];
+  if (!mod) return [];
+  return mod.LEGAL_TRANSITIONS[from] || [];
+}
+
+export function isTerminalStatus(kind, status) {
+  const mod = MODULES[kind];
+  if (!mod) return false;
+  return mod.TERMINAL_STATUSES.has(status);
+}
+
+export function isArchivableStatus(kind, status) {
+  const mod = MODULES[kind];
+  if (!mod) return false;
+  return mod.ARCHIVABLE_STATUSES.has(status);
+}
+
+export function validateTransition(kind, from, to) {
+  const mod = MODULES[kind];
+  if (!mod) {
+    return { ok: false, error: `No state machine for kind '${kind}'` };
+  }
+  return mod.validateTransition(from, to);
+}
+
+export {
+  pitch,
+  requirement,
+  acceptanceCriterion,
+  task,
+  bug,
+  document
+};

package/src/sdlc/transitions/pitch.js

@@ -0,0 +1,34 @@
+// Pitch state machine.
+//
+// draft → shaped → submitted → approved
+//   ↓        ↓         ↓          ↓
+//   └────────┴─────────┴───→ rejected
+//
+// A pitch may skip `shaped` and go straight to `submitted` for small or
+// obvious work (per the SDLC design). All terminal-status pitches stay in
+// the active workspace except `rejected`, which is archive-eligible.
+
+export const LEGAL_TRANSITIONS = {
+  draft: ["shaped", "submitted", "rejected"],
+  shaped: ["submitted", "rejected", "draft"],
+  submitted: ["approved", "rejected", "shaped"],
+  approved: ["rejected"],
+  rejected: ["draft"]
+};
+
+export const TERMINAL_STATUSES = new Set(["approved", "rejected"]);
+export const ARCHIVABLE_STATUSES = new Set(["rejected"]);
+
+export function validateTransition(from, to) {
+  const allowed = LEGAL_TRANSITIONS[from];
+  if (!allowed) {
+    return { ok: false, error: `Unknown pitch status '${from}'` };
+  }
+  if (!allowed.includes(to)) {
+    return {
+      ok: false,
+      error: `Pitch cannot transition from '${from}' to '${to}' — allowed: ${allowed.join(", ")}`
+    };
+  }
+  return { ok: true };
+}

package/src/sdlc/transitions/requirement.js

@@ -0,0 +1,31 @@
+// Requirement state machine.
+//
+// draft → in-review → approved → superseded
+//
+// Requirements are always-live: even `superseded` requirements stay in the
+// active workspace because tasks may still reference them in the
+// traceability matrix.
+
+export const LEGAL_TRANSITIONS = {
+  draft: ["in-review"],
+  "in-review": ["approved", "draft"],
+  approved: ["superseded", "in-review"],
+  superseded: []
+};
+
+export const TERMINAL_STATUSES = new Set(["superseded"]);
+export const ARCHIVABLE_STATUSES = new Set();
+
+export function validateTransition(from, to) {
+  const allowed = LEGAL_TRANSITIONS[from];
+  if (!allowed) {
+    return { ok: false, error: `Unknown requirement status '${from}'` };
+  }
+  if (!allowed.includes(to)) {
+    return {
+      ok: false,
+      error: `Requirement cannot transition from '${from}' to '${to}' — allowed: ${allowed.join(", ") || "(terminal)"}`
+    };
+  }
+  return { ok: true };
+}

package/src/sdlc/transitions/task.js

@@ -0,0 +1,34 @@
+// Task state machine.
+//
+// unclaimed → claimed → in-progress → done
+//                 ↓         ↓
+//                 └────→ blocked ←──┘
+//
+// `blocked` is exit-able back to whichever in-flight status the task came
+// from; in practice agents return through `in-progress`. `done` is
+// archive-eligible.
+
+export const LEGAL_TRANSITIONS = {
+  unclaimed: ["claimed"],
+  claimed: ["in-progress", "unclaimed", "blocked"],
+  "in-progress": ["done", "blocked", "claimed"],
+  blocked: ["claimed", "in-progress"],
+  done: []
+};
+
+export const TERMINAL_STATUSES = new Set(["done"]);
+export const ARCHIVABLE_STATUSES = new Set(["done"]);
+
+export function validateTransition(from, to) {
+  const allowed = LEGAL_TRANSITIONS[from];
+  if (!allowed) {
+    return { ok: false, error: `Unknown task status '${from}'` };
+  }
+  if (!allowed.includes(to)) {
+    return {
+      ok: false,
+      error: `Task cannot transition from '${from}' to '${to}' — allowed: ${allowed.join(", ") || "(terminal)"}`
+    };
+  }
+  return { ok: true };
+}