@topogram/cli 0.3.71 → 0.3.73

package/src/cli/commands/import/help.js

@@ -31,6 +31,7 @@ export function printImportHelp() {
   console.log("Examples:");
   console.log("  topogram import ./existing-app --out ./imported-topogram");
   console.log("  topogram import ./existing-app --out ./imported-topogram --from db,api,ui");
+  console.log("  topogram import ./existing-cli --out ./imported-topogram --from cli");
   console.log("  topogram import diff ./imported-topogram");
   console.log("  topogram import refresh ./imported-topogram --from ./existing-app --dry-run");
   console.log("  topogram import refresh ./imported-topogram --from ./existing-app");

package/src/cli/commands/import/plan.js

@@ -40,6 +40,15 @@ export const BROWNFIELD_BROAD_ADOPT_SELECTORS = [
   },
   { selector: "workflows", kind: "track", label: "workflows", matches: (/** @type {AnyRecord} */ item) => item.track === "workflows" || item.kind === "decision" },
   { selector: "verification", kind: "kind", label: "verification", matches: (/** @type {AnyRecord} */ item) => item.kind === "verification" },
+  {
+    selector: "cli",
+    kind: "track",
+    label: "CLI surfaces",
+    matches: (/** @type {AnyRecord} */ item) =>
+      item.bundle === "cli" ||
+      item.track === "cli" ||
+      item.suggested_action === "promote_cli_surface"
+  },
   {
     selector: "ui",
     kind: "track",

package/src/cli/commands/import/workspace.js

@@ -116,6 +116,9 @@ export function importCandidateCounts(summary) {
     uiRoutes: candidates.ui?.routes?.length || 0,
     uiWidgets: candidates.ui?.widgets?.length || candidates.ui?.components?.length || 0,
     uiShapes: candidates.ui?.shapes?.length || 0,
+    cliCommands: candidates.cli?.commands?.length || 0,
+    cliCapabilities: candidates.cli?.capabilities?.length || 0,
+    cliSurfaces: candidates.cli?.surfaces?.length || 0,
     workflows: candidates.workflows?.workflows?.length || 0,
     verifications: candidates.verification?.verifications?.length || 0
   };

package/src/cli/commands/query/definitions.js

@@ -32,21 +32,22 @@
  * @returns {QueryDefinition[]}
  */
 export function queryDefinitions() {
+  const contextSelectors = ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "domain", "pitch", "requirement", "acceptance", "task", "plan", "bug", "document", "from-topogram"];
   return [
     {
       name: "slice",
       purpose: "Give an agent the smallest graph slice needed to reason about one selected semantic surface.",
       description: "Return a focused semantic context slice for one selected surface.",
-      selectors: ["capability", "workflow", "projection", "widget", "entity", "journey", "domain"],
+      selectors: ["capability", "workflow", "projection", "widget", "entity", "journey", "domain", "pitch", "requirement", "acceptance", "task", "plan", "bug", "document"],
       args: ["[path]", "[selectors]", "[--json]"],
       output: "context_slice",
-      example: "topogram query slice ./topo --widget widget_data_grid"
+      example: "topogram query slice ./topo --task task_implement_audit_writer"
     },
     {
       name: "verification-targets",
       purpose: "Map a selected change or mode to the smallest verification set worth running.",
       description: "Return the smallest verification target set for a mode, selector, or diff.",
-      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "from-topogram"],
+      selectors: contextSelectors.filter((selector) => selector !== "surface" && selector !== "domain" && selector !== "pitch" && selector !== "requirement" && selector !== "acceptance" && selector !== "plan" && selector !== "bug" && selector !== "document"),
       args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "verification_targets",
       example: "topogram query verification-targets ./topo --widget widget_data_grid"
@@ -64,7 +65,7 @@ export function queryDefinitions() {
       name: "change-plan",
       purpose: "Summarize what a selected change affects before code or Topogram edits start.",
       description: "Return the semantic change plan, generator targets, risk, and alignment recommendations.",
-      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
+      selectors: contextSelectors,
       args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "change_plan_query",
       example: "topogram query change-plan ./topo --widget widget_data_grid"
@@ -73,7 +74,7 @@ export function queryDefinitions() {
       name: "review-packet",
       purpose: "Bundle the context a human or agent needs to review a selected semantic change.",
       description: "Return the review packet for a selected change or diff.",
-      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
+      selectors: contextSelectors,
       args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "review_packet_query",
       example: "topogram query review-packet ./topo --widget widget_data_grid"
@@ -82,7 +83,7 @@ export function queryDefinitions() {
       name: "resolved-workflow-context",
       purpose: "Resolve workflow guidance and artifact load order for a selected mode or change.",
       description: "Return resolved workflow guidance, artifact load order, preset policy, and recommended artifact queries.",
-      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "provider", "preset", "from-topogram"],
+      selectors: [...contextSelectors.filter((selector) => selector !== "document"), "provider", "preset"],
       args: ["[path]", "[--mode <id>]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "resolved_workflow_context_query",
       example: "topogram query resolved-workflow-context ./topo --mode modeling --widget widget_data_grid --json"
@@ -91,7 +92,7 @@ export function queryDefinitions() {
       name: "single-agent-plan",
       purpose: "Give one coding agent a bounded plan, artifact set, and write guidance.",
       description: "Return a single-agent operating plan for a mode and optional selector.",
-      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
+      selectors: contextSelectors.filter((selector) => selector !== "document"),
       args: ["[path]", "[--mode <id>]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "single_agent_plan_query",
       example: "topogram query single-agent-plan ./topo --mode modeling --widget widget_data_grid --json"
@@ -100,7 +101,7 @@ export function queryDefinitions() {
       name: "risk-summary",
       purpose: "Surface behavioral, ownership, and verification risks for a selected change.",
       description: "Return the risk summary for a selected change, mode, or diff.",
-      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
+      selectors: contextSelectors,
       args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "risk_summary_query",
       example: "topogram query risk-summary ./topo --widget widget_data_grid"
@@ -109,7 +110,7 @@ export function queryDefinitions() {
       name: "proceed-decision",
       purpose: "Tell a human or agent whether enough context and proof exist to proceed.",
       description: "Return a proceed/no-go decision for the current selected work.",
-      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
+      selectors: contextSelectors,
       args: ["[path]", "[--mode <id>]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "proceed_decision_query",
       example: "topogram query proceed-decision ./topo --mode verification"
@@ -118,7 +119,7 @@ export function queryDefinitions() {
       name: "write-scope",
       purpose: "Define where an agent may edit for a selected semantic surface.",
       description: "Return safe edit boundaries for a selected mode or semantic surface.",
-      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "from-topogram"],
+      selectors: contextSelectors.filter((selector) => selector !== "surface" && selector !== "document"),
       args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "write_scope_query",
       example: "topogram query write-scope ./topo --widget widget_data_grid"

package/src/cli/commands/query/workspace.js

@@ -74,6 +74,13 @@ export function importAdoptOnlyRequested(options = {}) {
     options.journeyId ||
     options.surfaceId ||
     options.domainId ||
+    options.pitchId ||
+    options.requirementId ||
+    options.acceptanceId ||
+    options.taskId ||
+    options.planId ||
+    options.bugId ||
+    options.documentId ||
     options.fromTopogramPath
   );
 }
@@ -202,7 +209,14 @@ export function hasSelectors(options) {
     options.entityId ||
     options.journeyId ||
     options.surfaceId ||
-    options.domainId
+    options.domainId ||
+    options.pitchId ||
+    options.requirementId ||
+    options.acceptanceId ||
+    options.taskId ||
+    options.planId ||
+    options.bugId ||
+    options.documentId
   );
 }
 
@@ -228,7 +242,14 @@ export function selectorOptions(options) {
     entityId: options.entityId,
     journeyId: options.journeyId,
     surfaceId: options.surfaceId,
-    domainId: options.domainId
+    domainId: options.domainId,
+    pitchId: options.pitchId,
+    requirementId: options.requirementId,
+    acceptanceId: options.acceptanceId,
+    taskId: options.taskId,
+    planId: options.planId,
+    bugId: options.bugId,
+    documentId: options.documentId
   };
 }
 

package/src/cli/commands/sdlc.js

@@ -6,6 +6,7 @@ import { stableStringify } from "../../format.js";
 import { parsePath } from "../../parser.js";
 import { resolveWorkspace } from "../../resolver.js";
 import { formatValidationErrors } from "../../validator.js";
+import { resolveTopoRoot } from "../../workspace-paths.js";
 
 /**
  * @typedef {Record<string, any>} AnyRecord
@@ -21,6 +22,23 @@ function flagValue(args, flag) {
   return index >= 0 ? args[index + 1] || null : null;
 }
 
+/**
+ * @param {string[]} args
+ * @param {string} flag
+ * @returns {string[]}
+ */
+function flagValues(args, flag) {
+  /** @type {string[]} */
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === flag && args[index + 1] && !args[index + 1].startsWith("-")) {
+      values.push(args[index + 1]);
+      index += 1;
+    }
+  }
+  return values;
+}
+
 /**
  * @param {string[]} args
  * @returns {boolean}
@@ -29,6 +47,65 @@ function includeHistory(args) {
   return args.includes("--history") || args.includes("--include-history");
 }
 
+/**
+ * @param {Record<string, any>} payload
+ * @returns {void}
+ */
+function printPolicyExplain(payload) {
+  console.log("Topogram SDLC policy");
+  console.log(`Status: ${payload.policy?.status || "not_adopted"}`);
+  console.log(`Mode: ${payload.policy?.mode || "none"}`);
+  console.log(`Policy: ${payload.policy?.path || "missing"}`);
+  console.log(payload.enforcement || "Project has not adopted enforced SDLC.");
+  if ((payload.policy?.protectedPaths || []).length > 0) {
+    console.log("Protected paths:");
+    for (const item of payload.policy.protectedPaths) {
+      console.log(`  - ${item}`);
+    }
+  }
+  if ((payload.nextCommands || []).length > 0) {
+    console.log("Next commands:");
+    for (const command of payload.nextCommands) {
+      console.log(`  - ${command}`);
+    }
+  }
+}
+
+/**
+ * @param {Record<string, any>} payload
+ * @returns {void}
+ */
+function printCommitPrep(payload) {
+  console.log("Topogram SDLC commit prep");
+  console.log(`Status: ${payload.ok ? "ready" : "needs attention"}`);
+  console.log(`Changed task files: ${(payload.taskFiles || []).length}`);
+  if ((payload.openTasks || []).length > 0) {
+    console.log("Open changed tasks:");
+    for (const task of payload.openTasks) {
+      console.log(`  - ${task.id} (${task.status}, ${task.disposition || "unclassified"})`);
+      console.log(`    file: ${task.file}`);
+    }
+  }
+  if ((payload.errors || []).length > 0) {
+    console.log("Errors:");
+    for (const error of payload.errors) {
+      console.log(`  - ${error}`);
+    }
+  }
+  if ((payload.warnings || []).length > 0) {
+    console.log("Warnings:");
+    for (const warning of payload.warnings) {
+      console.log(`  - ${warning}`);
+    }
+  }
+  if ((payload.nextCommands || []).length > 0) {
+    console.log("Next commands:");
+    for (const command of payload.nextCommands) {
+      console.log(`  - ${command}`);
+    }
+  }
+}
+
 /**
  * @param {string} sdlcRoot
  * @returns {AnyRecord|null}
@@ -56,15 +133,144 @@ function resolveSdlcWorkspace(sdlcRoot) {
  */
 export async function runSdlcCommand(context) {
   const { commandArgs, args } = context;
-  const sdlcRoot = path.resolve(context.inputPath || ".");
+  const sdlcRoot = resolveTopoRoot(context.inputPath || ".");
   const actor = flagValue(args, "--actor");
   const note = flagValue(args, "--note");
   const status = flagValue(args, "--status");
+  const id = flagValue(args, "--id");
   const before = flagValue(args, "--before");
   const appVersion = flagValue(args, "--app-version");
   const sinceTag = flagValue(args, "--since-tag");
+  const base = flagValue(args, "--base");
+  const head = flagValue(args, "--head");
+  const exemption = flagValue(args, "--exemption");
+  const verification = flagValue(args, "--verification");
   const dryRun = args.includes("--dry-run");
   const strict = args.includes("--strict");
+  const json = args.includes("--json");
+
+  if (String(commandArgs.sdlcCommand || "").startsWith("policy:")) {
+    const {
+      explainSdlcPolicy,
+      loadSdlcPolicy,
+      policyProjectRoot,
+      writeDefaultSdlcPolicy
+    } = await import("../../sdlc/policy.js");
+    const projectRoot = policyProjectRoot(context.inputPath || ".");
+    if (commandArgs.sdlcCommand === "policy:init") {
+      const result = writeDefaultSdlcPolicy(projectRoot);
+      console.log(stableStringify(result));
+      return result.ok ? 0 : 1;
+    }
+    if (commandArgs.sdlcCommand === "policy:check") {
+      const info = loadSdlcPolicy(projectRoot);
+      const result = {
+        type: "sdlc_policy_check",
+        ok: info.exists && info.diagnostics.every((diagnostic) => diagnostic.severity !== "error"),
+        exists: info.exists,
+        path: info.path,
+        status: info.status,
+        mode: info.mode,
+        diagnostics: info.diagnostics
+      };
+      if (json) {
+        console.log(stableStringify(result));
+      } else if (result.ok) {
+        console.log(`SDLC policy is valid: ${result.path}`);
+      } else {
+        console.error(stableStringify(result));
+      }
+      return result.ok ? 0 : 1;
+    }
+    if (commandArgs.sdlcCommand === "policy:explain") {
+      const result = explainSdlcPolicy(projectRoot);
+      if (json) {
+        console.log(stableStringify(result));
+      } else {
+        printPolicyExplain(result);
+      }
+      return result.ok ? 0 : 1;
+    }
+  }
+
+  if (commandArgs.sdlcCommand === "gate") {
+    const { runSdlcGate } = await import("../../sdlc/gate.js");
+    const result = await runSdlcGate(context.inputPath || ".", {
+      base,
+      head,
+      sdlcIds: flagValues(args, "--sdlc-id"),
+      exemption,
+      requireAdopted: args.includes("--require-adopted")
+    });
+    console.log(stableStringify(result));
+    return result.ok ? 0 : 1;
+  }
+
+  if (commandArgs.sdlcCommand === "prep:commit") {
+    const { runSdlcCommitPrep } = await import("../../sdlc/prep.js");
+    const result = runSdlcCommitPrep(context.inputPath || ".", {
+      base,
+      head
+    });
+    if (json) {
+      console.log(stableStringify(result));
+    } else {
+      printCommitPrep(result);
+    }
+    return result.ok ? 0 : 1;
+  }
+
+  if (commandArgs.sdlcCommand === "link") {
+    const { linkSdlcRecord } = await import("../../sdlc/link.js");
+    const result = linkSdlcRecord(sdlcRoot, commandArgs.sdlcFromId, commandArgs.sdlcToId, {
+      write: args.includes("--write")
+    });
+    console.log(stableStringify(result));
+    return result.ok ? 0 : 1;
+  }
+
+  if (commandArgs.sdlcCommand === "complete") {
+    const { completeTask } = await import("../../sdlc/complete.js");
+    const result = completeTask(sdlcRoot, commandArgs.sdlcId, verification || "", {
+      write: args.includes("--write") && !dryRun,
+      actor,
+      note
+    });
+    console.log(stableStringify(result));
+    return result.ok ? 0 : 1;
+  }
+
+  if (commandArgs.sdlcCommand === "plan:create") {
+    const { createPlan } = await import("../../sdlc/plan.js");
+    const result = createPlan(sdlcRoot, commandArgs.sdlcId, commandArgs.sdlcSlug, {
+      write: args.includes("--write") && !dryRun
+    });
+    console.log(stableStringify(result));
+    return result.ok ? 0 : 1;
+  }
+
+  if (commandArgs.sdlcCommand === "plan:explain") {
+    const { explainPlan } = await import("../../sdlc/plan.js");
+    const result = explainPlan(sdlcRoot, commandArgs.sdlcId);
+    console.log(stableStringify(result));
+    return result.ok ? 0 : 1;
+  }
+
+  if (String(commandArgs.sdlcCommand || "").startsWith("plan:step:")) {
+    const { transitionPlanStep } = await import("../../sdlc/plan.js");
+    if (commandArgs.sdlcCommand === "plan:step:skip" && !note) {
+      console.log(stableStringify({ ok: false, error: "sdlc plan step skip requires --note <reason>" }));
+      return 1;
+    }
+    const result = transitionPlanStep(sdlcRoot, commandArgs.sdlcId, commandArgs.sdlcStepId, commandArgs.sdlcTargetStatus, {
+      write: args.includes("--write") && !dryRun,
+      dryRun,
+      actor,
+      note
+    });
+    console.log(stableStringify(result));
+    return result.ok ? 0 : 1;
+  }
 
   if (commandArgs.sdlcCommand === "transition") {
     const { transitionStatement } = await import("../../sdlc/transition.js");
@@ -115,10 +321,12 @@ export async function runSdlcCommand(context) {
     if (!resolved) {
       return 1;
     }
-    const ids = archiveEligibleStatements(resolved, {
-      before,
-      statuses: status ? status.split(",") : null
-    });
+    const ids = id
+      ? [id]
+      : archiveEligibleStatements(resolved, {
+          before,
+          statuses: status ? status.split(",") : null
+        });
     const result = archiveBatch(sdlcRoot, ids, { dryRun, by: actor, reason: note });
     console.log(stableStringify({ candidates: ids, ...result }));
     return result.ok ? 0 : 1;

package/src/cli/dispatcher.js

@@ -10,7 +10,6 @@ import { runGenerateAppCommand } from "./commands/generate.js";
 import { runGeneratorCommand } from "./commands/generator.js";
 import { runGeneratorPolicyCommand } from "./commands/generator-policy.js";
 import { runImportCommand } from "./commands/import-runner.js";
-import { runMigrateCommand } from "./commands/migrate.js";
 import { runNewProjectCommand } from "./commands/new.js";
 import { runPackageCommand } from "./commands/package.js";
 import { runParseCommand, runResolveCommand } from "./commands/inspect.js";
@@ -110,6 +109,7 @@ export async function runCliDispatch(context) {
     domainId,
     seamId,
     taskId,
+    planId,
     pitchId,
     requirementId,
     acceptanceId,
@@ -242,10 +242,6 @@ export async function runCliDispatch(context) {
     return runPackageCommand({ commandArgs, inputPath, json: emitJson });
   }
 
-  if (commandArgs?.migrateCommand) {
-    return runMigrateCommand(inputPath, { write: shouldWrite, json: emitJson });
-  }
-
   if (commandArgs?.importCommand) {
     return runImportCommand({
       commandArgs,
@@ -301,6 +297,13 @@ export async function runCliDispatch(context) {
       journeyId,
       surfaceId,
       domainId,
+      pitchId,
+      requirementId,
+      acceptanceId,
+      taskId,
+      planId,
+      bugId,
+      documentId,
       seamId,
       modeId,
       providerId,

package/src/cli/help.js

@@ -16,6 +16,14 @@ export function printUsage(options = {}) {
   console.log("   or: topogram widget check [path] [--projection <id>] [--widget <id>] [--json]");
   console.log("   or: topogram widget behavior [path] [--projection <id>] [--widget <id>] [--json]");
   console.log("   or: topogram agent brief [path] [--json]");
+  console.log("   or: topogram sdlc policy init|check|explain [path] [--json]");
+  console.log("   or: topogram sdlc gate [path] --base <ref> --head <ref> [--sdlc-id <id>] [--exemption <text>] [--require-adopted] [--json]");
+  console.log("   or: topogram sdlc prep commit [path] [--base <ref> --head <ref>] [--json]");
+  console.log("   or: topogram sdlc link <from-id> <to-id> [path] [--write]");
+  console.log("   or: topogram sdlc complete <task-id> [path] --verification <verification-id> [--dry-run|--write]");
+  console.log("   or: topogram sdlc plan create <task-id> <slug> [path] [--write]");
+  console.log("   or: topogram sdlc plan explain <plan-id> [path] [--json]");
+  console.log("   or: topogram sdlc plan step complete <plan-id> <step-id> [path] --actor <actor> [--write]");
   console.log("   or: topogram generate [path] [--out <path>]");
   console.log("   or: topogram emit <target> [path] [--json|--write --out-dir <path>]");
   console.log("   or: topogram query list [--json]");
@@ -28,7 +36,6 @@ export function printUsage(options = {}) {
   console.log("   or: topogram catalog doctor [--json] [--catalog <path-or-source>]");
   console.log("   or: topogram catalog check <path-or-url> [--json]");
   console.log("   or: topogram catalog copy <id> <target> [--version <version>] [--json] [--catalog <path-or-source>]");
-  console.log("   or: topogram migrate workspace-folder [path] [--dry-run|--write] [--json]");
   console.log("   or: topogram package update-cli <version|--latest> [--json]");
   console.log("   or: topogram import <app-path> --out <target> [--from <track[,track]>] [--json]");
   console.log("   or: topogram import refresh [path] [--from <app-path>] [--dry-run] [--json]");
@@ -78,6 +85,10 @@ export function printUsage(options = {}) {
   console.log("  topogram widget behavior --projection proj_web_surface");
   console.log("  topogram agent brief");
   console.log("  topogram agent brief --json");
+  console.log("  topogram sdlc policy explain");
+  console.log("  topogram sdlc prep commit . --base origin/main --head HEAD");
+  console.log("  topogram sdlc gate . --require-adopted");
+  console.log("  topogram sdlc plan explain plan_example --json");
   console.log("  topogram query list");
   console.log("  topogram query show widget-behavior");
   console.log("  topogram query widget-behavior ./topo --projection proj_web_surface --json");
@@ -165,7 +176,7 @@ export function printUsage(options = {}) {
   console.log("   or: node ./src/cli.js query maintained-drift <path> --from-topogram <path>");
   console.log("   or: node ./src/cli.js query seam-check <path> [--seam <id>] [--from-topogram <path>]");
   console.log("   or: node ./src/cli.js query diff <path> --from-topogram <path>");
-  console.log("   or: node ./src/cli.js query slice <path> [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--domain <id>]");
+  console.log("   or: node ./src/cli.js query slice <path> [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--domain <id>] [--task <id>] [--plan <id>] [--bug <id>]");
   console.log("   or: node ./src/cli.js query domain-list <path>");
   console.log("   or: node ./src/cli.js query domain-coverage <path> --domain <id>");
   console.log("   or: node ./src/cli.js query review-boundary <path> [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>]");
@@ -179,7 +190,7 @@ export function printUsage(options = {}) {
   console.log("   or: node ./src/cli.js query proceed-decision <path> [--mode <id>] [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--surface <id>] [--from-topogram <path>]");
   console.log("   or: node ./src/cli.js query review-packet <path> [--mode <id>] [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--surface <id>] [--from-topogram <path>]");
   console.log("   or: node ./src/cli.js query next-action <path> [--mode <id>] [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--from-topogram <path>]");
-  console.log("   or: node ./src/cli.js query single-agent-plan <path> --mode <id> [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--surface <id>] [--from-topogram <path>]");
+  console.log("   or: node ./src/cli.js query single-agent-plan <path> --mode <id> [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--surface <id>] [--task <id>] [--plan <id>] [--bug <id>] [--from-topogram <path>]");
   console.log("   or: node ./src/cli.js query multi-agent-plan <path> --mode import-adopt");
   console.log("   or: node ./src/cli.js query resolved-workflow-context <path> --mode <id> [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--surface <id>] [--provider <id>] [--preset <id>] [--from-topogram <path>]");
   console.log("   or: node ./src/cli.js query workflow-preset-activation <path> --mode <id> [--provider <id>] [--preset <id>] [--from-topogram <path>]");

package/src/cli/migration-guidance.js

@@ -30,6 +30,9 @@ export function cliMigrationError(args) {
   if (args[0] === "component") {
     return "Command 'topogram component' was renamed to 'topogram widget'.";
   }
+  if (args[0] === "migrate") {
+    return "Command 'topogram migrate workspace-folder' was removed. Use topo/ workspaces or configure topogram.project.json workspace to a non-legacy relative path.";
+  }
   for (const [oldArg, newArg] of RENAMED_CLI_ARGS) {
     if (args.includes(oldArg)) {
       return `CLI flag '${oldArg}' was renamed to '${newArg}'.`;

package/src/cli/options.js

@@ -81,6 +81,7 @@ export function parseCliOptions(args, commandArgs) {
       domainId: optionValue(args, "--domain"),
       seamId: optionValue(args, "--seam"),
       taskId: optionValue(args, "--task"),
+      planId: optionValue(args, "--plan"),
       pitchId: optionValue(args, "--pitch"),
       requirementId: optionValue(args, "--requirement"),
       acceptanceId: optionValue(args, "--acceptance"),

package/src/generator/context/shared/domain-sdlc.js

@@ -135,6 +135,14 @@ export function acceptanceCriterionById(graph, id) {
 export function taskById(graph, id) {
   return (graph?.byKind?.task || []).find(/** @param {any} s */ (s) => s.id === id) || null;
 }
+/**
+ * @param {import("./types.d.ts").ContextGraph} graph
+ * @param {string} id
+ * @returns {any}
+ */
+export function planById(graph, id) {
+  return (graph?.byKind?.plan || []).find(/** @param {any} s */ (s) => s.id === id) || null;
+}
 /**
  * @param {import("./types.d.ts").ContextGraph} graph
  * @param {string} id
@@ -207,10 +215,29 @@ export function summarizeTask(task) {
     status: task.status,
     priority: task.priority,
     work_type: task.workType,
+    disposition: task.disposition || null,
     claimed_by: (task.claimedBy || []).map(/** @param {any} r */ (r) => (typeof r === "string" ? r : r?.id)).filter(Boolean),
     domain: task.resolvedDomain ? task.resolvedDomain.id : null
   };
 }
+/**
+ * @param {any} plan
+ * @returns {any}
+ */
+export function summarizePlan(plan) {
+  if (!plan) return null;
+  const steps = plan.steps || [];
+  return {
+    id: plan.id,
+    name: plan.name,
+    status: plan.status,
+    priority: plan.priority,
+    task: plan.task?.id || null,
+    step_count: steps.length,
+    incomplete_steps: steps.filter(/** @param {any} step */ (step) => step.status !== "done" && step.status !== "skipped").map(/** @param {any} step */ (step) => step.id),
+    domain: plan.resolvedDomain ? plan.resolvedDomain.id : null
+  };
+}
 /**
  * @param {any} bug
  * @returns {any}

package/src/generator/context/shared/relationships.js

@@ -436,13 +436,14 @@ export function ensureContextSelection(options = {}) {
     options.requirementId ? ["requirement", options.requirementId] : null,
     options.acceptanceId ? ["acceptance_criterion", options.acceptanceId] : null,
     options.taskId ? ["task", options.taskId] : null,
+    options.planId ? ["plan", options.planId] : null,
     options.bugId ? ["bug", options.bugId] : null,
     options.documentId ? ["document", options.documentId] : null
   ].filter(Boolean));
 
   if (selectors.length !== 1) {
     throw new Error(
-      "Context selection requires exactly one of --capability, --workflow, --projection, --widget, --entity, --journey, --surface, --domain, --pitch, --requirement, --acceptance, --task, --bug, or --document"
+      "Context selection requires exactly one of --capability, --workflow, --projection, --widget, --entity, --journey, --surface, --domain, --pitch, --requirement, --acceptance, --task, --plan, --bug, or --document"
     );
   }
 

package/src/generator/context/shared/types.d.ts

@@ -143,6 +143,7 @@ export type ContextSelectionOptions = {
   requirementId?: string | null;
   acceptanceId?: string | null;
   taskId?: string | null;
+  planId?: string | null;
   bugId?: string | null;
   documentId?: string | null;
   [key: string]: any;

package/src/generator/context/shared.d.ts

@@ -9,6 +9,7 @@ export function getJourneyDoc(...args: any[]): any;
 export function getStatement(...args: any[]): any;
 export function getWorkflowDoc(...args: any[]): any;
 export function pitchById(...args: any[]): any;
+export function planById(...args: any[]): any;
 export function relatedCapabilitiesForEntity(...args: any[]): any;
 export function relatedCapabilitiesForProjection(...args: any[]): any;
 export function relatedEntitiesForDomain(...args: any[]): any;
@@ -34,6 +35,7 @@ export function summarizeDocsByIds(...args: any[]): any;
 export function summarizeDocument(...args: any[]): any;
 export function summarizeDomain(...args: any[]): any;
 export function summarizePitch(...args: any[]): any;
+export function summarizePlan(...args: any[]): any;
 export function summarizeProjection(...args: any[]): any;
 export function summarizeRequirement(...args: any[]): any;
 export function summarizeStatementsByIds(...args: any[]): any;

package/src/generator/context/shared.js

@@ -55,12 +55,14 @@ export {
   requirementById,
   acceptanceCriterionById,
   taskById,
+  planById,
   bugById,
   documentById,
   summarizePitch,
   summarizeRequirement,
   summarizeAcceptanceCriterion,
   summarizeTask,
+  summarizePlan,
   summarizeBug,
   summarizeDocument,
   getWorkflowDoc,