@topogram/cli 0.3.72 → 0.3.74

package/src/sdlc/prep.js

@@ -0,0 +1,186 @@
+// @ts-check
+
+import childProcess from "node:child_process";
+import path from "node:path";
+
+import { parsePath } from "../parser.js";
+import { resolveWorkspace } from "../resolver.js";
+import { resolveTopoRoot, resolveWorkspaceContext } from "../workspace-paths.js";
+
+/**
+ * @typedef {Object} SdlcCommitPrepOptions
+ * @property {string|null} [base]
+ * @property {string|null} [head]
+ * @property {string[]} [changedFiles]
+ */
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function normalizePath(value) {
+  return value.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string[]} args
+ * @returns {string[]}
+ */
+function gitFileList(projectRoot, args) {
+  const result = childProcess.spawnSync("git", args, {
+    cwd: projectRoot,
+    encoding: "utf8"
+  });
+  if (result.status !== 0) {
+    return [];
+  }
+  return result.stdout.split(/\r?\n/).map(/** @param {string} line */ (line) => line.trim()).filter(Boolean);
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string|null|undefined} base
+ * @param {string|null|undefined} head
+ * @returns {string[]}
+ */
+function changedFiles(projectRoot, base, head) {
+  const localChanges = [
+    ...gitFileList(projectRoot, ["diff", "--name-only", "--cached"]),
+    ...gitFileList(projectRoot, ["diff", "--name-only"]),
+    ...gitFileList(projectRoot, ["ls-files", "--others", "--exclude-standard"])
+  ];
+  if (base && head) {
+    return [...new Set([
+      ...gitFileList(projectRoot, ["diff", "--name-only", `${base}...${head}`]),
+      ...localChanges
+    ])];
+  }
+  return [...new Set(localChanges)];
+}
+
+/**
+ * @param {Record<string, any>} ast
+ * @param {string} projectRoot
+ * @returns {Map<string, { file: string, ids: string[] }>}
+ */
+function taskFilesFromAst(ast, projectRoot) {
+  const map = new Map();
+  for (const file of ast.files || []) {
+    const ids = (file.statements || [])
+      .filter(/** @param {Record<string, any>} statement */ (statement) => statement.kind === "task")
+      .map(/** @param {Record<string, any>} statement */ (statement) => statement.id);
+    if (ids.length === 0) continue;
+    const rel = normalizePath(path.relative(projectRoot, file.file));
+    map.set(rel, { file: rel, ids });
+  }
+  return map;
+}
+
+/**
+ * @param {Record<string, any>} task
+ * @returns {boolean}
+ */
+function isOpenTask(task) {
+  return task.status !== "done";
+}
+
+/**
+ * @param {Record<string, any>} task
+ * @returns {boolean}
+ */
+function needsExplicitDisposition(task) {
+  if (!isOpenTask(task)) return false;
+  if (task.disposition) return false;
+  return !["claimed", "in-progress"].includes(String(task.status));
+}
+
+/**
+ * @param {string} inputPath
+ * @param {SdlcCommitPrepOptions} [options]
+ * @returns {Record<string, any>}
+ */
+export function runSdlcCommitPrep(inputPath = ".", options = {}) {
+  const context = resolveWorkspaceContext(inputPath || ".");
+  const projectRoot = context.projectRoot;
+  const topogramRoot = resolveTopoRoot(inputPath || ".");
+  const files = (options.changedFiles || changedFiles(projectRoot, options.base, options.head)).map(normalizePath);
+  const changedFileSet = new Set(files);
+  const ast = parsePath(topogramRoot);
+  const resolved = resolveWorkspace(ast);
+  if (!resolved.ok) {
+    return {
+      type: "sdlc_commit_prep",
+      version: "1",
+      ok: false,
+      projectRoot,
+      topogramRoot,
+      changedFiles: files,
+      taskFiles: [],
+      changedTasks: [],
+      openTasks: [],
+      warnings: [],
+      errors: ["workspace resolution failed"]
+    };
+  }
+
+  const taskFiles = taskFilesFromAst(ast, projectRoot);
+  const changedTaskFiles = [...taskFiles.values()]
+    .filter((entry) => changedFileSet.has(entry.file))
+    .map((entry) => entry.file)
+    .sort();
+  const taskIds = new Set(changedTaskFiles.flatMap((file) => taskFiles.get(file)?.ids || []));
+  const tasksById = new Map((resolved.graph.byKind.task || []).map(/** @param {Record<string, any>} task */ (task) => [task.id, task]));
+  const resolvedTasks = /** @type {Record<string, any>[]} */ ([...taskIds]
+    .map((id) => tasksById.get(id))
+    .filter(Boolean));
+  const changedTasks = resolvedTasks
+    .map((task) => {
+      const source = [...taskFiles.values()].find((entry) => entry.ids.includes(task.id))?.file || null;
+      const disposition = task.disposition || (["claimed", "in-progress"].includes(String(task.status)) ? "active" : null);
+      return {
+        id: task.id,
+        status: task.status,
+        priority: task.priority || null,
+        disposition,
+        explicitDisposition: Boolean(task.disposition),
+        file: source,
+        requiresDisposition: needsExplicitDisposition(task)
+      };
+    })
+    .sort((a, b) => a.id.localeCompare(b.id));
+  const openTasks = changedTasks.filter((task) => task.status !== "done");
+  const errors = [];
+  const warnings = [];
+
+  for (const task of openTasks) {
+    if (task.requiresDisposition) {
+      errors.push(`Open task ${task.id} in ${task.file} needs explicit disposition active|follow_up|deferred|backlog|blocker before commit.`);
+    }
+    if (task.disposition === "blocker") {
+      errors.push(`Open task ${task.id} is marked disposition blocker.`);
+    }
+    if (task.priority === "high" && ["follow_up", "deferred", "backlog"].includes(String(task.disposition))) {
+      warnings.push(`High priority task ${task.id} remains open as ${task.disposition}.`);
+    }
+  }
+
+  return {
+    type: "sdlc_commit_prep",
+    version: "1",
+    ok: errors.length === 0,
+    projectRoot,
+    topogramRoot,
+    changedFiles: files,
+    taskFiles: changedTaskFiles,
+    changedTasks,
+    openTasks,
+    warnings,
+    errors,
+    nextCommands: [
+      "topogram sdlc explain <task-id> --json",
+      "topogram query slice ./topo --task <task-id> --json",
+      "topogram sdlc gate . --base <ref> --head <ref> --require-adopted"
+    ]
+  };
+}

package/src/sdlc/scaffold.js

@@ -3,7 +3,7 @@
 
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { resolveTopoRoot } from "../workspace-paths.js";
+import { sdlcRootForSdlc } from "./paths.js";
 
 const TEMPLATES = {
   pitch: (slug) => `pitch pitch_${slug} {
@@ -41,8 +41,10 @@ const TEMPLATES = {
   description "What the agent or human will do."
   satisfies []
   acceptance_refs []
+  verification_refs []
   affects []
   blocked_by []
+  disposition active
   priority medium
   work_type implementation
   status unclaimed
@@ -74,7 +76,7 @@ export function scaffoldNew(workspaceRoot, kind, slug) {
   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(resolveTopoRoot(workspaceRoot), `${kind === "acceptance_criterion" ? "acceptance_criteria" : kind + "s"}`);
+  const targetDir = path.join(sdlcRootForSdlc(workspaceRoot), `${kind === "acceptance_criterion" ? "acceptance_criteria" : kind + "s"}`);
   if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true });
   const targetFile = path.join(targetDir, `${slug}.tg`);
   if (existsSync(targetFile)) {

package/src/sdlc/status-filter.js

@@ -30,6 +30,8 @@ export function defaultActiveStatuses(kind) {
       return new Set(["draft", "approved", "superseded"]);
     case "task":
       return new Set(["unclaimed", "claimed", "in-progress", "blocked"]);
+    case "plan":
+      return new Set(["draft", "active"]);
     case "bug":
       return new Set(["open", "in-progress", "fixed"]);
     case "document":

package/src/sdlc/transitions/index.js

@@ -4,6 +4,7 @@ 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 plan from "./plan.js";
 import * as bug from "./bug.js";
 import * as document from "./document.js";
 
@@ -12,6 +13,7 @@ const MODULES = {
   requirement,
   acceptance_criterion: acceptanceCriterion,
   task,
+  plan,
   bug,
   document
 };
@@ -51,6 +53,7 @@ export {
   requirement,
   acceptanceCriterion,
   task,
+  plan,
   bug,
   document
 };

package/src/sdlc/transitions/plan.js

@@ -0,0 +1,32 @@
+// Plan state machine.
+//
+// draft → active → complete
+//          └────→ superseded
+//
+// `complete` and `superseded` are archive-eligible. Plans are optional
+// support artifacts; their state machine tracks the plan artifact, not the
+// owning task's DoD.
+
+export const LEGAL_TRANSITIONS = {
+  draft: ["active", "superseded"],
+  active: ["complete", "superseded", "draft"],
+  complete: [],
+  superseded: []
+};
+
+export const TERMINAL_STATUSES = new Set(["complete", "superseded"]);
+export const ARCHIVABLE_STATUSES = new Set(["complete", "superseded"]);
+
+export function validateTransition(from, to) {
+  const allowed = LEGAL_TRANSITIONS[from];
+  if (!allowed) {
+    return { ok: false, error: `Unknown plan status '${from}'` };
+  }
+  if (!allowed.includes(to)) {
+    return {
+      ok: false,
+      error: `Plan cannot transition from '${from}' to '${to}' — allowed: ${allowed.join(", ") || "(terminal)"}`
+    };
+  }
+  return { ok: true };
+}

package/src/validator/common.js

@@ -197,9 +197,16 @@ function validateFieldShapes(errors, statement, fieldMap) {
   ensureSingleValueField(errors, statement, fieldMap, "method", ["symbol"]);
   ensureSingleValueField(errors, statement, fieldMap, "severity", ["symbol"]);
   ensureSingleValueField(errors, statement, fieldMap, "category", ["symbol"]);
+  ensureSingleValueField(errors, statement, fieldMap, "priority", ["symbol"]);
+  ensureSingleValueField(errors, statement, fieldMap, "work_type", ["symbol"]);
+  ensureSingleValueField(errors, statement, fieldMap, "disposition", ["symbol"]);
+  ensureSingleValueField(errors, statement, fieldMap, "task", ["symbol"]);
   ensureSingleValueField(errors, statement, fieldMap, "version", ["string"]);
+  ensureSingleValueField(errors, statement, fieldMap, "updated", ["string"]);
+  ensureSingleValueField(errors, statement, fieldMap, "notes", ["string"]);
+  ensureSingleValueField(errors, statement, fieldMap, "outcome", ["string"]);
 
-  for (const key of [
+  const listFields = [
     "aliases",
     "excludes",
     "uses_terms",
@@ -220,7 +227,6 @@ function validateFieldShapes(errors, statement, fieldMap) {
     "realizes",
     "outputs",
     "inputs",
-    "steps",
     "validates",
     "scenarios",
     "observes",
@@ -233,11 +239,19 @@ function validateFieldShapes(errors, statement, fieldMap) {
     "lookups",
     "dependencies",
     "approvals"
-  ]) {
+  ];
+  if (statement.kind === "orchestration") {
+    listFields.push("steps");
+  }
+  for (const key of listFields) {
     ensureSingleValueField(errors, statement, fieldMap, key, ["list"]);
   }
 
-  for (const key of ["fields", "props", "events", "slots", "behaviors", "keys", "relations", "invariants", "rename", "overrides", "endpoints", "error_responses", "wire_fields", "responses", "preconditions", "idempotency", "cache", "delete_semantics", "async_jobs", "async_status", "downloads", "authorization", "callbacks", "screens", "collection_views", "screen_actions", "visibility_rules", "field_lookups", "screen_routes", "web_hints", "ios_hints", "app_shell", "navigation", "screen_regions", "widget_bindings", "design_tokens", "tables", "columns", "keys", "indexes", "relations", "lifecycle", "generator_defaults"]) {
+  const blockFields = ["fields", "props", "events", "slots", "behaviors", "keys", "relations", "invariants", "rename", "overrides", "endpoints", "error_responses", "wire_fields", "responses", "preconditions", "idempotency", "cache", "delete_semantics", "async_jobs", "async_status", "downloads", "authorization", "callbacks", "commands", "command_options", "command_outputs", "command_effects", "command_examples", "screens", "collection_views", "screen_actions", "visibility_rules", "field_lookups", "screen_routes", "web_hints", "ios_hints", "app_shell", "navigation", "screen_regions", "widget_bindings", "design_tokens", "tables", "columns", "keys", "indexes", "relations", "lifecycle", "generator_defaults"];
+  if (statement.kind === "plan") {
+    blockFields.push("steps");
+  }
+  for (const key of blockFields) {
     ensureSingleValueField(errors, statement, fieldMap, key, ["block"]);
   }
 
@@ -267,6 +281,11 @@ function validateFieldShapes(errors, statement, fieldMap) {
     validateBlockEntryLengths(errors, statement, fieldMap, "downloads", 7);
     validateBlockEntryLengths(errors, statement, fieldMap, "authorization", 3);
     validateBlockEntryLengths(errors, statement, fieldMap, "callbacks", 11);
+    validateBlockEntryLengths(errors, statement, fieldMap, "commands", 2);
+    validateBlockEntryLengths(errors, statement, fieldMap, "command_options", 6);
+    validateBlockEntryLengths(errors, statement, fieldMap, "command_outputs", 4);
+    validateBlockEntryLengths(errors, statement, fieldMap, "command_effects", 4);
+    validateBlockEntryLengths(errors, statement, fieldMap, "command_examples", 4);
     validateBlockEntryLengths(errors, statement, fieldMap, "screens", 4);
     validateBlockEntryLengths(errors, statement, fieldMap, "collection_views", 4);
     validateBlockEntryLengths(errors, statement, fieldMap, "screen_actions", 6);
@@ -416,11 +435,13 @@ function validateReferenceKinds(errors, statement, fieldMap, registry) {
     introduces_decisions: ["decision"],
     satisfies: ["requirement", "acceptance_criterion"],
     acceptance_refs: ["acceptance_criterion"],
+    verification_refs: ["verification"],
     requirement_refs: ["requirement"],
     fixes_bugs: ["bug"],
     blocks: ["task"],
     blocked_by: ["task"],
     claimed_by: ["actor", "role"],
+    task: ["task"],
     violates: ["rule"],
     surfaces_rule: ["rule"],
     introduced_in: ["task", "bug"],

package/src/validator/index.js

@@ -5,6 +5,7 @@ import { validateExpressions } from "./expressions.js";
 import { validateApiHttpProjection } from "./projections/api-http.js";
 import { validateDbProjection } from "./projections/db.js";
 import { validateProjectionGeneratorDefaults } from "./projections/generator-defaults.js";
+import { validateCliProjection } from "./projections/cli.js";
 import { validateUiProjection } from "./projections/ui.js";
 import { buildRegistry } from "./registry.js";
 import {
@@ -17,6 +18,7 @@ import { validatePitch } from "./per-kind/pitch.js";
 import { validateRequirement } from "./per-kind/requirement.js";
 import { validateAcceptanceCriterion } from "./per-kind/acceptance-criterion.js";
 import { validateTask } from "./per-kind/task.js";
+import { validatePlan } from "./per-kind/plan.js";
 import { validateBug } from "./per-kind/bug.js";
 
 export {
@@ -28,17 +30,23 @@ export {
   REQUIREMENT_IDENTIFIER_PATTERN,
   ACCEPTANCE_CRITERION_IDENTIFIER_PATTERN,
   TASK_IDENTIFIER_PATTERN,
+  PLAN_IDENTIFIER_PATTERN,
   BUG_IDENTIFIER_PATTERN,
   DOCUMENT_IDENTIFIER_PATTERN,
   GLOBAL_STATUSES,
   DECISION_STATUSES,
   RULE_SEVERITIES,
   VERIFICATION_METHODS,
+  CLI_COMMAND_EFFECTS,
+  CLI_COMMAND_OPTION_TYPES,
+  CLI_COMMAND_OUTPUT_FORMATS,
   STATUS_SETS_BY_KIND,
   PITCH_STATUSES,
   REQUIREMENT_STATUSES,
   ACCEPTANCE_CRITERION_STATUSES,
   TASK_STATUSES,
+  PLAN_STATUSES,
+  PLAN_STEP_STATUSES,
   BUG_STATUSES,
   PRIORITY_VALUES,
   WORK_TYPES,
@@ -91,6 +99,7 @@ export function validateWorkspace(workspaceAst) {
       validateReferenceRules(errors, statement, fieldMap, registry);
       validateDataModelStatement(errors, statement, fieldMap, registry);
       validateApiHttpProjection(errors, statement, fieldMap, registry);
+      validateCliProjection(errors, statement, fieldMap, registry);
       validateUiProjection(errors, statement, fieldMap, registry);
       validateDbProjection(errors, statement, fieldMap, registry);
       validateProjectionGeneratorDefaults(errors, statement, fieldMap);
@@ -101,6 +110,7 @@ export function validateWorkspace(workspaceAst) {
       validateRequirement(errors, statement, fieldMap, registry);
       validateAcceptanceCriterion(errors, statement, fieldMap, registry);
       validateTask(errors, statement, fieldMap, registry);
+      validatePlan(errors, statement, fieldMap, registry);
       validateBug(errors, statement, fieldMap, registry);
       validateExpressions(errors, statement, fieldMap);
     }

package/src/validator/kinds.d.ts

@@ -6,17 +6,24 @@ export const PITCH_IDENTIFIER_PATTERN: RegExp;
 export const REQUIREMENT_IDENTIFIER_PATTERN: RegExp;
 export const ACCEPTANCE_CRITERION_IDENTIFIER_PATTERN: RegExp;
 export const TASK_IDENTIFIER_PATTERN: RegExp;
+export const PLAN_IDENTIFIER_PATTERN: RegExp;
 export const BUG_IDENTIFIER_PATTERN: RegExp;
 export const DOCUMENT_IDENTIFIER_PATTERN: RegExp;
 export const GLOBAL_STATUSES: Set<string>;
 export const DECISION_STATUSES: Set<string>;
 export const RULE_SEVERITIES: Set<string>;
 export const VERIFICATION_METHODS: Set<string>;
+export const CLI_COMMAND_EFFECTS: Set<string>;
+export const CLI_COMMAND_OPTION_TYPES: Set<string>;
+export const CLI_COMMAND_OUTPUT_FORMATS: Set<string>;
 export const STATUS_SETS_BY_KIND: Record<string, Set<string>>;
 export const PITCH_STATUSES: Set<string>;
 export const REQUIREMENT_STATUSES: Set<string>;
 export const ACCEPTANCE_CRITERION_STATUSES: Set<string>;
 export const TASK_STATUSES: Set<string>;
+export const TASK_DISPOSITIONS: Set<string>;
+export const PLAN_STATUSES: Set<string>;
+export const PLAN_STEP_STATUSES: Set<string>;
 export const BUG_STATUSES: Set<string>;
 export const PRIORITY_VALUES: Set<string>;
 export const WORK_TYPES: Set<string>;

package/src/validator/kinds.js

@@ -20,6 +20,7 @@ export const STATEMENT_KINDS = new Set([
   "requirement",
   "acceptance_criterion",
   "task",
+  "plan",
   "bug"
 ]);
 
@@ -29,6 +30,7 @@ export const PITCH_IDENTIFIER_PATTERN = /^pitch_[a-z][a-z0-9_]*$/;
 export const REQUIREMENT_IDENTIFIER_PATTERN = /^req_[a-z][a-z0-9_]*$/;
 export const ACCEPTANCE_CRITERION_IDENTIFIER_PATTERN = /^ac_[a-z][a-z0-9_]*$/;
 export const TASK_IDENTIFIER_PATTERN = /^task_[a-z][a-z0-9_]*$/;
+export const PLAN_IDENTIFIER_PATTERN = /^plan_[a-z][a-z0-9_]*$/;
 export const BUG_IDENTIFIER_PATTERN = /^bug_[a-z][a-z0-9_]*$/;
 export const DOCUMENT_IDENTIFIER_PATTERN = /^doc_[a-z][a-z0-9_]*$/;
 
@@ -41,7 +43,10 @@ export const PITCH_STATUSES = new Set(["draft", "shaped", "submitted", "approved
 export const REQUIREMENT_STATUSES = new Set(["draft", "in-review", "approved", "superseded"]);
 export const ACCEPTANCE_CRITERION_STATUSES = new Set(["draft", "approved", "superseded"]);
 export const TASK_STATUSES = new Set(["unclaimed", "claimed", "in-progress", "done", "blocked"]);
+export const PLAN_STATUSES = new Set(["draft", "active", "complete", "superseded"]);
+export const PLAN_STEP_STATUSES = new Set(["pending", "in-progress", "blocked", "done", "skipped"]);
 export const BUG_STATUSES = new Set(["open", "in-progress", "fixed", "verified", "wont-fix"]);
+export const TASK_DISPOSITIONS = new Set(["active", "follow_up", "deferred", "backlog", "blocker"]);
 
 export const PRIORITY_VALUES = new Set(["critical", "high", "medium", "low"]);
 export const WORK_TYPES = new Set([
@@ -73,9 +78,13 @@ export const STATUS_SETS_BY_KIND = {
   requirement: REQUIREMENT_STATUSES,
   acceptance_criterion: ACCEPTANCE_CRITERION_STATUSES,
   task: TASK_STATUSES,
+  plan: PLAN_STATUSES,
   bug: BUG_STATUSES
 };
 export const VERIFICATION_METHODS = new Set(["smoke", "runtime", "contract", "journey", "manual"]);
+export const CLI_COMMAND_EFFECTS = new Set(["read_only", "writes_workspace", "writes_app", "network", "package_install", "git", "filesystem"]);
+export const CLI_COMMAND_OPTION_TYPES = new Set(["string", "boolean", "number", "integer", "enum", "path", "list"]);
+export const CLI_COMMAND_OUTPUT_FORMATS = new Set(["json", "human", "file", "exit_code"]);
 
 export {
   UI_APP_SHELL_KINDS,
@@ -114,6 +123,7 @@ export const DOMAIN_TAGGABLE_KINDS = new Set([
   "pitch",
   "requirement",
   "task",
+  "plan",
   "bug"
 ]);
 
@@ -179,6 +189,11 @@ export const FIELD_SPECS = {
       "downloads",
       "authorization",
       "callbacks",
+      "commands",
+      "command_options",
+      "command_outputs",
+      "command_effects",
+      "command_examples",
       "screens",
       "collection_views",
       "screen_actions",
@@ -277,9 +292,11 @@ export const FIELD_SPECS = {
       "status",
       "priority",
       "work_type",
+      "disposition",
       "affects",
       "satisfies",
       "acceptance_refs",
+      "verification_refs",
       "blocks",
       "blocked_by",
       "claimed_by",
@@ -291,6 +308,21 @@ export const FIELD_SPECS = {
       "updated"
     ]
   },
+  plan: {
+    required: ["name", "description", "task", "status", "steps"],
+    allowed: [
+      "name",
+      "description",
+      "task",
+      "status",
+      "priority",
+      "notes",
+      "outcome",
+      "steps",
+      "domain",
+      "updated"
+    ]
+  },
   bug: {
     required: ["name", "description", "status", "severity", "priority"],
     allowed: [

package/src/validator/per-kind/plan.js

@@ -0,0 +1,128 @@
+// @ts-check
+
+import {
+  PLAN_IDENTIFIER_PATTERN,
+  PLAN_STEP_STATUSES,
+  PRIORITY_VALUES
+} from "../kinds.js";
+import {
+  blockEntries,
+  pushError,
+  symbolValue
+} from "../utils.js";
+import { parsePlanStepEntry } from "../../sdlc/plan-steps.js";
+
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement */
+function validatePlanIdentifier(errors, statement) {
+  if (!PLAN_IDENTIFIER_PATTERN.test(statement.id)) {
+    pushError(
+      errors,
+      `Plan identifier '${statement.id}' must match ${PLAN_IDENTIFIER_PATTERN.source}`,
+      statement.loc
+    );
+  }
+}
+
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap */
+function validatePriority(errors, statement, fieldMap) {
+  const field = fieldMap.get("priority")?.[0];
+  if (!field) return;
+  if (field.value.type !== "symbol") {
+    pushError(errors, `Field 'priority' on plan ${statement.id} must be a symbol`, field.loc);
+    return;
+  }
+  if (!PRIORITY_VALUES.has(field.value.value)) {
+    pushError(errors, `Invalid priority '${field.value.value}' on plan ${statement.id}`, field.loc);
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+function validatePlanTask(errors, statement, fieldMap, registry) {
+  const field = fieldMap.get("task")?.[0];
+  if (!field || field.value.type !== "symbol") return;
+  const target = registry.get(field.value.value);
+  if (!target) return;
+  if (target.kind !== "task") {
+    pushError(errors, `Plan ${statement.id} task must reference a task, found ${target.kind} '${target.id}'`, field.loc);
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @returns {void}
+ */
+function validateStepRows(errors, statement, fieldMap) {
+  const field = fieldMap.get("steps")?.[0];
+  if (!field || field.value.type !== "block") return;
+
+  const seen = new Set();
+  const entries = blockEntries(field.value);
+  if (entries.length === 0) {
+    pushError(errors, `Plan ${statement.id} must include at least one step`, field.loc);
+  }
+  for (const entry of entries) {
+    const [kindToken, idToken, ...rest] = entry.items;
+    if (kindToken?.type !== "symbol" || kindToken.value !== "step") {
+      pushError(errors, `Each 'steps' entry on plan ${statement.id} must start with 'step'`, entry.loc);
+      continue;
+    }
+    if (idToken?.type !== "symbol" || !/^[a-z][a-z0-9_]*$/.test(idToken.value)) {
+      pushError(errors, `Plan ${statement.id} step id must be a symbol matching /^[a-z][a-z0-9_]*$/`, idToken?.loc || entry.loc);
+      continue;
+    }
+    if (seen.has(idToken.value)) {
+      pushError(errors, `Plan ${statement.id} has duplicate step '${idToken.value}'`, idToken.loc);
+    }
+    seen.add(idToken.value);
+
+    if (rest.length % 2 !== 0) {
+      pushError(errors, `Plan ${statement.id} step '${idToken.value}' fields must be key/value pairs`, entry.loc);
+    }
+
+    const allowedKeys = new Set(["status", "description", "notes", "outcome"]);
+    for (let index = 0; index < rest.length - 1; index += 2) {
+      const keyToken = rest[index];
+      if (keyToken?.type !== "symbol" || !allowedKeys.has(keyToken.value)) {
+        pushError(errors, `Plan ${statement.id} step '${idToken.value}' has unsupported field '${keyToken?.value || "unknown"}'`, keyToken?.loc || entry.loc);
+      }
+    }
+
+    const parsed = parsePlanStepEntry(entry);
+    if (!parsed.status) {
+      pushError(errors, `Plan ${statement.id} step '${idToken.value}' requires status`, entry.loc);
+    } else if (!PLAN_STEP_STATUSES.has(parsed.status)) {
+      pushError(errors, `Invalid step status '${parsed.status}' on plan ${statement.id} step '${idToken.value}'`, entry.loc);
+    }
+    if (!parsed.description) {
+      pushError(errors, `Plan ${statement.id} step '${idToken.value}' requires description`, entry.loc);
+    }
+  }
+}
+
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
+export function validatePlan(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "plan") {
+    return;
+  }
+  validatePlanIdentifier(errors, statement);
+  validatePriority(errors, statement, fieldMap);
+  validatePlanTask(errors, statement, fieldMap, registry);
+  validateStepRows(errors, statement, fieldMap);
+
+  const status = symbolValue(fieldMap.get("status")?.[0]?.value);
+  if (status === "complete") {
+    const steps = blockEntries(fieldMap.get("steps")?.[0]?.value).map((entry) => parsePlanStepEntry(entry));
+    const incomplete = steps.filter((step) => step.status !== "done" && step.status !== "skipped");
+    if (incomplete.length > 0) {
+      pushError(errors, `Plan ${statement.id} status 'complete' requires all steps to be done or skipped`, fieldMap.get("status")?.[0]?.loc || statement.loc);
+    }
+  }
+}