@topogram/cli 0.3.72 → 0.3.73

package/src/generator/context/slice/sdlc.js

@@ -8,6 +8,7 @@ import {
   domainById,
   getJourneyDoc,
   pitchById,
+  planById,
   recommendedVerificationTargets,
   relatedEntitiesForDomain,
   relatedProjectionsForDomain,
@@ -21,6 +22,7 @@ import {
   summarizeDocument,
   summarizeDomain,
   summarizePitch,
+  summarizePlan,
   summarizeRequirement,
   summarizeStatementsByIds,
   summarizeTask,
@@ -297,10 +299,12 @@ export function taskSlice(graph, taskId) {
 
   const satisfies = (task.satisfies || []).map(/** @param {any} r */ (r) => (typeof r === "string" ? r : r?.id)).filter(Boolean).sort();
   const acRefs = (task.acceptanceRefs || []).map(/** @param {any} r */ (r) => (typeof r === "string" ? r : r?.id)).filter(Boolean).sort();
+  const verificationRefs = (task.verificationRefs || []).map(/** @param {any} r */ (r) => (typeof r === "string" ? r : r?.id)).filter(Boolean).sort();
   const blockedBy = (task.blockedBy || []).map(/** @param {any} r */ (r) => (typeof r === "string" ? r : r?.id)).filter(Boolean).sort();
   const blocks = (task.blocks || []).map(/** @param {any} r */ (r) => (typeof r === "string" ? r : r?.id)).filter(Boolean).sort();
   const affects = (task.affects || []).map(/** @param {any} a */ (a) => (typeof a === "string" ? a : a?.id)).filter(Boolean).sort();
-  const verifications = verificationIdsForTarget(graph, [taskId, ...affects, ...acRefs]);
+  const plans = (task.plans || []).slice().sort();
+  const verifications = [...new Set([...verificationRefs, ...verificationIdsForTarget(graph, [taskId, ...affects, ...acRefs])])].sort();
 
   return {
     type: "context_slice",
@@ -310,15 +314,19 @@ export function taskSlice(graph, taskId) {
     depends_on: {
       satisfies,
       acceptance_refs: acRefs,
+      verification_refs: verificationRefs,
       blocked_by: blockedBy,
       blocks,
+      plans,
       affects,
       verifications
     },
     related: {
       satisfies: summarizeStatementsByIds(graph, satisfies),
       acceptance_refs: summarizeStatementsByIds(graph, acRefs),
+      verification_refs: summarizeStatementsByIds(graph, verificationRefs),
       blocked_by: summarizeStatementsByIds(graph, blockedBy),
+      plans: summarizeStatementsByIds(graph, plans),
       affects: summarizeStatementsByIds(graph, affects)
     },
     verification: summarizeStatementsByIds(graph, verifications),
@@ -331,6 +339,54 @@ export function taskSlice(graph, taskId) {
   };
 }
 
+/**
+ * @param {import("../shared/types.d.ts").ContextGraph} graph
+ * @param {string} planId
+ * @returns {any}
+ */
+export function planSlice(graph, planId) {
+  const plan = planById(graph, planId);
+  if (!plan) throw new Error(`No plan found with id '${planId}'`);
+
+  const taskId = plan.task?.id || null;
+  const task = taskId ? taskById(graph, taskId) : null;
+  const satisfies = task ? (task.satisfies || []).map(/** @param {any} r */ (r) => (typeof r === "string" ? r : r?.id)).filter(Boolean).sort() : [];
+  const acRefs = task ? (task.acceptanceRefs || []).map(/** @param {any} r */ (r) => (typeof r === "string" ? r : r?.id)).filter(Boolean).sort() : [];
+  const verificationRefs = task ? (task.verificationRefs || []).map(/** @param {any} r */ (r) => (typeof r === "string" ? r : r?.id)).filter(Boolean).sort() : [];
+  const affects = task ? (task.affects || []).map(/** @param {any} a */ (a) => (typeof a === "string" ? a : a?.id)).filter(Boolean).sort() : [];
+  const verifications = [...new Set([...verificationRefs, ...verificationIdsForTarget(graph, [planId, ...(taskId ? [taskId] : []), ...affects, ...acRefs])])].sort();
+
+  return {
+    type: "context_slice",
+    version: 1,
+    focus: { kind: "plan", id: planId },
+    summary: summarizePlan(plan),
+    depends_on: {
+      task: taskId,
+      satisfies,
+      acceptance_refs: acRefs,
+      verification_refs: verificationRefs,
+      affects,
+      verifications
+    },
+    related: {
+      task: task ? [summarizeTask(task)] : [],
+      satisfies: summarizeStatementsByIds(graph, satisfies),
+      acceptance_refs: summarizeStatementsByIds(graph, acRefs),
+      verification_refs: summarizeStatementsByIds(graph, verificationRefs),
+      affects: summarizeStatementsByIds(graph, affects)
+    },
+    steps: plan.steps || [],
+    verification: summarizeStatementsByIds(graph, verifications),
+    verification_targets: recommendedVerificationTargets(graph, [planId, ...(taskId ? [taskId] : []), ...affects, ...acRefs], {
+      rationale: "Plan slice points at verification for the owning task and affected surfaces."
+    }),
+    write_scope: buildDefaultWriteScope(),
+    review_boundary: reviewBoundaryForTask(),
+    ownership_boundary: defaultOwnershipBoundary()
+  };
+}
+
 /**
  * @param {import("../shared/types.d.ts").ContextGraph} graph
  * @param {string} bugId
@@ -414,4 +470,3 @@ export function documentSlice(graph, documentId) {
     ownership_boundary: defaultOwnershipBoundary()
   };
 }
-

package/src/generator/context/task-mode.js

@@ -234,6 +234,13 @@ function selectedSurface(options = {}) {
   if (options.entityId) return { kind: "entity", id: options.entityId };
   if (options.journeyId) return { kind: "journey", id: options.journeyId };
   if (options.surfaceId) return { kind: "surface", id: options.surfaceId };
+  if (options.pitchId) return { kind: "pitch", id: options.pitchId };
+  if (options.requirementId) return { kind: "requirement", id: options.requirementId };
+  if (options.acceptanceId) return { kind: "acceptance_criterion", id: options.acceptanceId };
+  if (options.taskId) return { kind: "task", id: options.taskId };
+  if (options.planId) return { kind: "plan", id: options.planId };
+  if (options.bugId) return { kind: "bug", id: options.bugId };
+  if (options.documentId) return { kind: "document", id: options.documentId };
   return null;
 }
 

package/src/generator/sdlc/board.js

@@ -7,6 +7,7 @@
 
 import {
   summarizeBug,
+  summarizePlan,
   summarizePitch,
   summarizeRequirement,
   summarizeTask
@@ -20,6 +21,7 @@ const SUMMARIZERS = {
   pitch: summarizePitch,
   requirement: summarizeRequirement,
   task: summarizeTask,
+  plan: summarizePlan,
   bug: summarizeBug
 };
 

package/src/generator/sdlc/traceability-matrix.js

@@ -19,7 +19,11 @@ export function generateSdlcTraceabilityMatrix(graph, options = {}) {
     const pitch = pitchId ? pitchesById.get(pitchId) : null;
 
     const taskIds = (ac.tasks || []).slice().sort();
-    const verificationIds = (ac.verifications || []).slice().sort();
+    const taskVerificationIds = taskIds.flatMap((id) => {
+      const task = tasksById.get(id);
+      return (task?.verificationRefs || []).map((ref) => typeof ref === "string" ? ref : ref?.id).filter(Boolean);
+    });
+    const verificationIds = [...new Set([...(ac.verifications || []), ...taskVerificationIds])].sort();
 
     const linkedBugIds = [];
     for (const bug of bugsById.values()) {

package/src/import/core/context.js

@@ -20,7 +20,7 @@ export function findNearestGitRoot(startDir) {
 }
 
 export function normalizeWorkspacePaths(inputPath) {
-  const context = resolveWorkspaceContext(inputPath);
+  const context = resolveWorkspaceContext(inputPath, { ignoreAncestorConfig: true });
   const absolute = path.resolve(inputPath);
   const topogramRoot = context.topoRoot;
   const workspaceRoot = context.projectRoot;

package/src/import/core/contracts.js

@@ -1,17 +1,17 @@
-export const IMPORT_TRACKS = new Set(["db", "api", "ui", "workflows", "verification"]);
+export const IMPORT_TRACKS = new Set(["db", "api", "ui", "cli", "workflows", "verification"]);
 
 /**
  * @typedef {{score:number, reasons:string[]}} DetectionResult
  * @typedef {{findings:any[], candidates:any}} ExtractResult
  * @typedef {{
  *   id:string,
- *   track:"db"|"api"|"ui"|"workflows"|"verification",
+ *   track:"db"|"api"|"ui"|"cli"|"workflows"|"verification",
  *   detect:(context:any)=>DetectionResult,
  *   extract:(context:any)=>ExtractResult
  * }} ImportExtractor
  * @typedef {{
  *   id:string,
- *   track:"db"|"api"|"ui"|"workflows"|"verification"|"docs",
+ *   track:"db"|"api"|"ui"|"cli"|"workflows"|"verification"|"docs",
  *   applies:(context:any, candidates:any)=>boolean|number,
  *   enrich:(context:any, candidates:any)=>any
  * }} ImportEnricher

package/src/import/core/registry.js

@@ -47,6 +47,7 @@ import { reactNativeScreensExtractor } from "../extractors/ui/react-native-scree
 import { reactRouterUiExtractor } from "../extractors/ui/react-router.js";
 import { svelteKitUiExtractor } from "../extractors/ui/sveltekit.js";
 import { backendOnlyUiExtractor } from "../extractors/ui/backend-only.js";
+import { genericCliExtractor } from "../extractors/cli/generic.js";
 import { genericWorkflowExtractor } from "../extractors/workflows/generic.js";
 import { genericVerificationExtractor } from "../extractors/verification/generic.js";
 import { authSessionEnricher } from "../enrichers/auth-session.js";
@@ -60,6 +61,7 @@ export const extractorRegistry = {
   db: [prismaExtractor, djangoModelsExtractor, efCoreExtractor, roomExtractor, swiftDataExtractor, dotnetModelsExtractor, flutterEntitiesExtractor, reactNativeEntitiesExtractor, railsSchemaExtractor, liquibaseExtractor, myBatisXmlExtractor, jpaExtractor, drizzleExtractor, sqlExtractor, snapshotExtractor],
   api: [openApiExtractor, openApiCodeExtractor, graphQlSdlExtractor, graphQlCodeFirstExtractor, trpcExtractor, aspNetCoreExtractor, retrofitExtractor, swiftWebApiExtractor, flutterDioExtractor, reactNativeRepositoryExtractor, fastifyExtractor, expressExtractor, djangoRoutesExtractor, railsRoutesExtractor, micronautExtractor, jaxRsExtractor, springWebExtractor, nextRouteExtractor, genericRouteFallbackExtractor, nextServerActionExtractor, nextAuthExtractor],
   ui: [nextAppRouterUiExtractor, nextPagesRouterUiExtractor, androidComposeUiExtractor, blazorUiExtractor, razorPagesUiExtractor, swiftUiExtractor, uiKitExtractor, mauiXamlUiExtractor, flutterScreensUiExtractor, reactNativeScreensExtractor, reactRouterUiExtractor, svelteKitUiExtractor, backendOnlyUiExtractor],
+  cli: [genericCliExtractor],
   workflows: [genericWorkflowExtractor],
   verification: [genericVerificationExtractor]
 };
@@ -68,6 +70,7 @@ export const enricherRegistry = {
   db: [railsModelEnricher],
   api: [djangoRestEnricher, railsControllerEnricher, authSessionEnricher],
   ui: [],
+  cli: [],
   workflows: [workflowTargetStateEnricher, docLinkingEnricher],
   verification: []
 };

package/src/import/core/runner/candidates.js

@@ -288,6 +288,13 @@ export function normalizeCandidatesForTrack(track, candidates) {
       stacks: [...new Set(candidates.stacks || [])].sort()
     };
   }
+  if (track === "cli") {
+    return {
+      commands: dedupeCandidateRecords(candidates.commands || [], (/** @type {any} */ record) => record.command_id || record.id_hint),
+      capabilities: dedupeCandidateRecords(candidates.capabilities || [], idHint),
+      surfaces: dedupeCandidateRecords(candidates.surfaces || [], idHint)
+    };
+  }
   if (track === "verification") {
     return {
       verifications: dedupeCandidateRecords(candidates.verifications || [], idHint),

package/src/import/core/runner/reports.js

@@ -29,6 +29,14 @@ export function reportMarkdown(track, candidates) {
       `# UI Import Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Widgets: ${widgets.length}\n- Event payload shapes: ${shapes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n\n## Widget Candidates\n\n${widgetLines.length ? widgetLines.join("\n") : "- none"}\n\n## Next Validation\n\n- Review candidates under \`topo/candidates/app/ui/drafts/widgets/**\`.\n- Run \`topogram import plan <path>\` before adoption.\n- After adoption, run \`topogram check <path>\`, \`topogram widget check <path>\`, and \`topogram widget behavior <path>\`.\n`
     );
   }
+  if (track === "cli") {
+    const commandLines = (candidates.commands || []).map((/** @type {any} */ command) =>
+      `- \`${command.command_id || command.id_hint}\` usage \`${command.usage || "unknown"}\` effects ${(command.effects || []).map((/** @type {any} */ effect) => `\`${effect}\``).join(", ") || "_none_"}`
+    );
+    return ensureTrailingNewline(
+      `# CLI Import Report\n\n- Commands: ${candidates.commands.length}\n- Capabilities: ${candidates.capabilities.length}\n- CLI surfaces: ${candidates.surfaces.length}\n\n## Command Candidates\n\n${commandLines.length ? commandLines.join("\n") : "- none"}\n`
+    );
+  }
   if (track === "verification") {
     return ensureTrailingNewline(
       `# Verification Import Report\n\n- Verifications: ${candidates.verifications.length}\n- Scenarios: ${candidates.scenarios.length}\n- Frameworks: ${candidates.frameworks.length ? candidates.frameworks.join(", ") : "none"}\n- Scripts: ${candidates.scripts.length}\n`
@@ -46,6 +54,6 @@ export function reportMarkdown(track, candidates) {
  */
 export function appReportMarkdown(candidates, tracks) {
   return ensureTrailingNewline(
-    `# App Import Report\n\nTracks: ${tracks.join(", ")}\n\n## DB\n\n- Entities: ${candidates.db?.entities?.length || 0}\n- Enums: ${candidates.db?.enums?.length || 0}\n- Relations: ${candidates.db?.relations?.length || 0}\n\n## API\n\n- Capabilities: ${candidates.api?.capabilities?.length || 0}\n- Routes: ${candidates.api?.routes?.length || 0}\n- Stacks: ${candidates.api?.stacks?.length ? candidates.api.stacks.join(", ") : "none"}\n\n## UI\n\n- Screens: ${candidates.ui?.screens?.length || 0}\n- Routes: ${candidates.ui?.routes?.length || 0}\n- Actions: ${candidates.ui?.actions?.length || 0}\n- Widgets: ${uiWidgetCandidates(candidates.ui).length}\n- Event payload shapes: ${candidates.ui?.shapes?.length || 0}\n- Stacks: ${candidates.ui?.stacks?.length ? candidates.ui.stacks.join(", ") : "none"}\n\n## Workflows\n\n- Workflows: ${candidates.workflows?.workflows?.length || 0}\n- States: ${candidates.workflows?.workflow_states?.length || 0}\n- Transitions: ${candidates.workflows?.workflow_transitions?.length || 0}\n\n## Verification\n\n- Verifications: ${candidates.verification?.verifications?.length || 0}\n- Scenarios: ${candidates.verification?.scenarios?.length || 0}\n- Frameworks: ${candidates.verification?.frameworks?.length ? candidates.verification.frameworks.join(", ") : "none"}\n- Scripts: ${candidates.verification?.scripts?.length || 0}\n`
+    `# App Import Report\n\nTracks: ${tracks.join(", ")}\n\n## DB\n\n- Entities: ${candidates.db?.entities?.length || 0}\n- Enums: ${candidates.db?.enums?.length || 0}\n- Relations: ${candidates.db?.relations?.length || 0}\n\n## API\n\n- Capabilities: ${candidates.api?.capabilities?.length || 0}\n- Routes: ${candidates.api?.routes?.length || 0}\n- Stacks: ${candidates.api?.stacks?.length ? candidates.api.stacks.join(", ") : "none"}\n\n## UI\n\n- Screens: ${candidates.ui?.screens?.length || 0}\n- Routes: ${candidates.ui?.routes?.length || 0}\n- Actions: ${candidates.ui?.actions?.length || 0}\n- Widgets: ${uiWidgetCandidates(candidates.ui).length}\n- Event payload shapes: ${candidates.ui?.shapes?.length || 0}\n- Stacks: ${candidates.ui?.stacks?.length ? candidates.ui.stacks.join(", ") : "none"}\n\n## CLI\n\n- Commands: ${candidates.cli?.commands?.length || 0}\n- Capabilities: ${candidates.cli?.capabilities?.length || 0}\n- CLI surfaces: ${candidates.cli?.surfaces?.length || 0}\n\n## Workflows\n\n- Workflows: ${candidates.workflows?.workflows?.length || 0}\n- States: ${candidates.workflows?.workflow_states?.length || 0}\n- Transitions: ${candidates.workflows?.workflow_transitions?.length || 0}\n\n## Verification\n\n- Verifications: ${candidates.verification?.verifications?.length || 0}\n- Scenarios: ${candidates.verification?.scenarios?.length || 0}\n- Frameworks: ${candidates.verification?.frameworks?.length ? candidates.verification.frameworks.join(", ") : "none"}\n- Scripts: ${candidates.verification?.scripts?.length || 0}\n`
   );
 }

package/src/import/core/runner/tracks.js

@@ -104,6 +104,9 @@ function initialCandidatesForTrack(track) {
   if (track === "ui") {
     return { screens: [], routes: [], actions: [], stacks: [] };
   }
+  if (track === "cli") {
+    return { commands: [], capabilities: [], surfaces: [] };
+  }
   if (track === "verification") {
     return { verifications: [], scenarios: [], frameworks: [], scripts: [] };
   }

package/src/import/extractors/cli/generic.js

@@ -0,0 +1,340 @@
+// @ts-check
+
+import {
+  findImportFiles,
+  idHintify,
+  makeCandidateRecord,
+  normalizeImportRelativePath,
+  readJsonIfExists,
+  readTextIfExists,
+  titleCase
+} from "../../core/shared.js";
+
+const CLI_SOURCE_PATTERN = /(^|\/)(bin|cli|command|commands|parser|help)(\/|[-_.A-Za-z0-9]*\.(?:js|mjs|cjs|ts))$/i;
+const JS_SOURCE_PATTERN = /\.(?:js|mjs|cjs|ts)$/i;
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function normalizePath(value) {
+  return value.replaceAll("\\", "/");
+}
+
+/**
+ * @param {string} commandId
+ * @returns {string}
+ */
+function capabilityIdForCommand(commandId) {
+  return `cap_${idHintify(commandId)}`;
+}
+
+/**
+ * @param {string} text
+ * @returns {string[]}
+ */
+function extractUsageLines(text) {
+  const lines = [];
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine
+      .replace(/^\s*(?:console\.log\(|print\(|echo\s+)?["'`]*/, "")
+      .replace(/["'`),;]*\s*$/, "")
+      .trim();
+    if (!line) continue;
+    const usageMatch = line.match(/(?:^|\b)Usage:\s*(.+)$/i);
+    if (usageMatch?.[1]) {
+      lines.push(usageMatch[1].trim());
+      continue;
+    }
+    if (/^[a-zA-Z][\w.-]+(?:\s+[a-zA-Z][\w:-]+)+(?:\s|$)/.test(line) && /(?:--[a-zA-Z][\w:-]*|<[^>]+>|\[[^\]]+\])/.test(line)) {
+      lines.push(line);
+    }
+  }
+  return [...new Set(lines)].sort();
+}
+
+/**
+ * @param {string} usage
+ * @param {Set<string>} binNames
+ * @returns {{ id: string, commandPath: string[] } | null}
+ */
+function commandIdFromUsage(usage, binNames) {
+  const tokens = usage.split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) {
+    return null;
+  }
+  const firstCommandToken = binNames.has(tokens[0]) ? 1 : 0;
+  const commandPath = [];
+  for (let index = firstCommandToken; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (!token || token.startsWith("-") || token.startsWith("[") || token.startsWith("<")) {
+      break;
+    }
+    commandPath.push(token.replace(/[^a-zA-Z0-9:_-]/g, ""));
+  }
+  if (commandPath.length === 0) {
+    return null;
+  }
+  return {
+    id: idHintify(commandPath.join("_")),
+    commandPath
+  };
+}
+
+/**
+ * @param {string} usage
+ * @param {string} commandId
+ * @returns {any[]}
+ */
+function optionsFromUsage(usage, commandId) {
+  const options = [];
+  const optionPattern = /--([a-zA-Z][\w:-]*)(?:\s+(<[^>]+>|\[[^\]]+\]))?/g;
+  for (const match of usage.matchAll(optionPattern)) {
+    const optionName = idHintify(match[1]);
+    options.push({
+      command_id: commandId,
+      name: optionName,
+      flag: `--${match[1]}`,
+      type: match[2] ? "string" : "boolean",
+      required: false,
+      values: [],
+      description: null
+    });
+  }
+  return options;
+}
+
+/**
+ * @param {string} commandId
+ * @param {string} usage
+ * @param {string} sourceText
+ * @returns {string[]}
+ */
+function effectsForCommand(commandId, usage, sourceText) {
+  const text = `${commandId} ${usage}`.toLowerCase();
+  const effects = new Set();
+  if (/\b(check|list|show|help|doctor|status|brief|explain|query|emit)\b/.test(text)) {
+    effects.add("read_only");
+  }
+  if (/\b(import|adopt|new|generate|refresh|update|write|create|copy)\b/.test(text)) {
+    effects.add("writes_workspace");
+    effects.add("filesystem");
+  }
+  if (/\b(fetch|https?:\/\/|github|gh_token|github_token|network|catalog)\b/.test(text)) {
+    effects.add("network");
+  }
+  if (/\b(npm|package|install|publish|pack)\b/.test(text)) {
+    effects.add("package_install");
+  }
+  if (/\b(git|worktree|commit|push|pull|checkout|branch)\b/.test(text)) {
+    effects.add("git");
+  }
+  if (effects.size === 0) {
+    effects.add("read_only");
+  }
+  return [...effects].sort();
+}
+
+/**
+ * @param {string} commandId
+ * @param {any[]} options
+ * @returns {any[]}
+ */
+function outputsForCommand(commandId, options) {
+  const hasJson = options.some((option) => option.command_id === commandId && option.name === "json");
+  return [
+    ...(hasJson ? [{ command_id: commandId, format: "json", schema_id: null, description: "Machine-readable JSON output" }] : []),
+    { command_id: commandId, format: "human", schema_id: null, description: "Human-readable terminal output" }
+  ];
+}
+
+/**
+ * @param {any[]} records
+ * @param {(record: any) => string} keyFn
+ * @returns {any[]}
+ */
+function dedupeRecords(records, keyFn) {
+  const seen = new Set();
+  const deduped = [];
+  for (const record of records) {
+    const key = keyFn(record);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(record);
+  }
+  return deduped;
+}
+
+/**
+ * @param {any} context
+ * @returns {{ packageFiles: string[], sourceFiles: string[] }}
+ */
+function discoverCliSources(context) {
+  const packageFiles = findImportFiles(context.paths, (/** @type {string} */ filePath) => /package\.json$/i.test(filePath));
+  const sourceFiles = findImportFiles(context.paths, (/** @type {string} */ filePath) => {
+    const normalized = normalizePath(filePath);
+    return JS_SOURCE_PATTERN.test(normalized) && (
+      CLI_SOURCE_PATTERN.test(normalized) ||
+      normalized.includes("/src/cli/") ||
+      normalized.includes("/commands/")
+    );
+  });
+  return { packageFiles, sourceFiles };
+}
+
+export const genericCliExtractor = {
+  id: "cli.generic",
+  track: "cli",
+  /** @param {any} context */
+  detect(context) {
+    const { packageFiles, sourceFiles } = discoverCliSources(context);
+    const hasBin = packageFiles.some((filePath) => {
+      const pkg = readJsonIfExists(filePath);
+      return Boolean(pkg?.bin);
+    });
+    const score = (hasBin ? 70 : 0) + Math.min(30, sourceFiles.length * 5);
+    return {
+      score,
+      reasons: [
+        hasBin ? "package.json declares a CLI bin" : null,
+        sourceFiles.length ? `${sourceFiles.length} CLI-like source files found` : null
+      ].filter(Boolean)
+    };
+  },
+  /** @param {any} context */
+  extract(context) {
+    const { packageFiles, sourceFiles } = discoverCliSources(context);
+    const findings = [];
+    const commands = [];
+    const options = [];
+    const outputs = [];
+    const effects = [];
+    const examples = [];
+    const capabilities = [];
+    const binNames = new Set();
+    const provenance = [];
+
+    for (const packagePath of packageFiles) {
+      const pkg = readJsonIfExists(packagePath);
+      if (!pkg) continue;
+      const relPath = normalizeImportRelativePath(context.paths, packagePath);
+      const bin = pkg.bin;
+      if (typeof bin === "string") {
+        binNames.add(pkg.name ? String(pkg.name).split("/").pop() : "cli");
+      } else if (bin && typeof bin === "object") {
+        for (const name of Object.keys(bin)) {
+          binNames.add(name);
+        }
+      }
+      for (const [name, command] of Object.entries(pkg.scripts || {})) {
+        if (/^(cli|bin|start|check|test|verify)(:|$)/.test(name) || /\b(node|tsx|ts-node)\b.+\b(cli|bin)\b/i.test(String(command))) {
+          findings.push({
+            kind: "cli_script",
+            name,
+            command,
+            source: relPath
+          });
+        }
+      }
+      provenance.push(`${relPath}#bin`);
+    }
+
+    for (const sourcePath of sourceFiles) {
+      const sourceText = readTextIfExists(sourcePath) || "";
+      const relPath = normalizeImportRelativePath(context.paths, sourcePath);
+      const usageLines = extractUsageLines(sourceText);
+      if (usageLines.length === 0) {
+        continue;
+      }
+      findings.push({
+        kind: "cli_usage",
+        source: relPath,
+        usages: usageLines
+      });
+      for (const usage of usageLines) {
+        const command = commandIdFromUsage(usage, binNames);
+        if (!command) continue;
+        const commandOptions = optionsFromUsage(usage, command.id);
+        const commandEffects = effectsForCommand(command.id, usage, sourceText);
+        const capabilityId = capabilityIdForCommand(command.id);
+        const commandProvenance = [`${relPath}#${usage}`];
+        commands.push(makeCandidateRecord({
+          kind: "cli_command",
+          idHint: `cmd_${command.id}`,
+          label: titleCase(command.commandPath.join(" ")),
+          confidence: "medium",
+          sourceKind: "cli_usage",
+          sourceOfTruth: "candidate",
+          provenance: commandProvenance,
+          track: "cli",
+          command_id: command.id,
+          command_path: command.commandPath,
+          capability_id: capabilityId,
+          usage,
+          mode: commandEffects.includes("writes_workspace") ? "writes_workspace" : commandEffects[0],
+          options: commandOptions.map((option) => option.name),
+          effects: commandEffects
+        }));
+        capabilities.push(makeCandidateRecord({
+          kind: "capability",
+          idHint: capabilityId,
+          label: titleCase(command.commandPath.join(" ")),
+          confidence: "medium",
+          sourceKind: "cli_command",
+          sourceOfTruth: "candidate",
+          provenance: commandProvenance,
+          track: "cli",
+          command_id: command.id
+        }));
+        options.push(...commandOptions.map((option) => ({
+          ...option,
+          provenance: commandProvenance
+        })));
+        outputs.push(...outputsForCommand(command.id, commandOptions).map((output) => ({
+          ...output,
+          provenance: commandProvenance
+        })));
+        effects.push(...commandEffects.map((effect) => ({
+          command_id: command.id,
+          effect,
+          target: effect === "read_only" ? "workspace" : null,
+          provenance: commandProvenance
+        })));
+        examples.push({
+          command_id: command.id,
+          example: usage,
+          provenance: commandProvenance
+        });
+      }
+    }
+
+    const surfaceCommands = dedupeRecords(commands, (record) => record.command_id);
+    const surfaces = surfaceCommands.length > 0
+      ? [makeCandidateRecord({
+          kind: "cli_surface",
+          idHint: "proj_cli_surface",
+          label: "CLI Surface",
+          confidence: "medium",
+          sourceKind: "cli_usage",
+          sourceOfTruth: "candidate",
+          provenance,
+          track: "cli",
+          commands: surfaceCommands.map((record) => record.command_id),
+          command_records: surfaceCommands,
+          options: dedupeRecords(options, (record) => `${record.command_id}:${record.name}`),
+          outputs: dedupeRecords(outputs, (record) => `${record.command_id}:${record.format}`),
+          effects: dedupeRecords(effects, (record) => `${record.command_id}:${record.effect}`),
+          examples: dedupeRecords(examples, (record) => `${record.command_id}:${record.example}`)
+        })]
+      : [];
+
+    return {
+      findings,
+      candidates: {
+        commands: surfaceCommands,
+        capabilities: dedupeRecords(capabilities, (record) => record.id_hint),
+        surfaces
+      }
+    };
+  }
+};

package/src/new-project/project-files.js

@@ -285,9 +285,10 @@ Start here before editing this Topogram project.
 1. \`AGENTS.md\`
 2. \`README.md\`
 3. \`topogram.project.json\`
-4. \`topogram.template-policy.json\`
-5. \`topogram.generator-policy.json\`
-${hasImplementation ? "6. `.topogram-template-trust.json`\n7. `implementation/`\n8. Focused `topogram query ...` output\n" : "6. Focused `topogram query ...` output\n"}
+4. \`topogram.sdlc-policy.json\`, if this project has adopted SDLC enforcement
+5. \`topogram.template-policy.json\`
+6. \`topogram.generator-policy.json\`
+${hasImplementation ? "7. `.topogram-template-trust.json`\n8. `implementation/`\n9. Focused `topogram query ...` output\n" : "7. Focused `topogram query ...` output\n"}
 Machine-readable source:
 
 \`\`\`bash
@@ -310,6 +311,8 @@ npm run doctor
 npm run source:status
 npm run template:explain
 npm run generator:policy:check
+topogram sdlc policy explain --json
+topogram sdlc explain <task-or-bug-id> --json
 ${hasImplementation ? "npm run trust:status\n" : ""}npm run check
 npm run query:list
 npm run query:show -- widget-behavior
@@ -318,6 +321,10 @@ npm run query:show -- widget-behavior
 ## Edit Rules
 
 - Edit \`topo/**\` and \`topogram.project.json\` first.
+- If \`topogram.sdlc-policy.json\` exists, protected changes need an SDLC item, a \`topo/sdlc/**\` SDLC record update, or an allowed exemption.
+- Adopted SDLC records default to \`topo/sdlc/**\`; custom folders can still validate, but agents should look there first.
+- Status, history, archives, trust hashes, provenance, generated sentinels, and release/rollout state are command-owned. Use Topogram commands instead of hand-editing those sidecars.
+- Plans are optional support records. Agents may edit plan text directly, but should use \`topogram sdlc plan step ... --write\` for step status changes.
 - Review policy files before editing \`topogram.template-policy.json\` or \`topogram.generator-policy.json\`.
 - Do not make lasting edits under generated-owned \`app/**\`; use \`npm run generate\` to replace generated output.
 - If an output is changed to maintained ownership, agents may edit that app code directly after reading focused query packets.

package/src/resolver/enrich/task.js

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