@topogram/cli 0.3.81 → 0.3.83

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.81",
+  "version": "0.3.83",
   "description": "Topogram CLI for checking Topogram workspaces and generating app bundles.",
   "license": "Apache-2.0",
   "repository": {

package/src/agent-ops/query-builders/change-risk/extract-plan.js

@@ -2,7 +2,7 @@ import { buildImportMaintainedRisk } from "../maintained-risk.js";
 import { buildImportPlanNextAction } from "../workflow-presets-core.js";
 import { buildPresetGuidanceSummary } from "./risk.js";
 
-export function buildImportPlanPayload(adoptionPlan, taskModeArtifact, maintainedBoundaryArtifact = null, workflowPresetState = null) {
+export function buildImportPlanPayload(adoptionPlan, taskModeArtifact, maintainedBoundaryArtifact = null, workflowPresetState = null, extractionContext = null) {
   const importMaintained = buildImportMaintainedRisk(adoptionPlan.imported_proposal_surfaces || [], maintainedBoundaryArtifact);
   const importNextAction = buildImportPlanNextAction(taskModeArtifact.next_action || null, workflowPresetState);
   const presetGuidanceSummary = buildPresetGuidanceSummary(workflowPresetState, null);
@@ -13,6 +13,7 @@ export function buildImportPlanPayload(adoptionPlan, taskModeArtifact, maintaine
     next_action: importNextAction,
     write_scope: taskModeArtifact.write_scope || null,
     verification_targets: taskModeArtifact.verification_targets || null,
+    extraction_context: extractionContext,
     review_groups: adoptionPlan.approved_review_groups || [],
     staged_items: adoptionPlan.staged_items || [],
     accepted_items: adoptionPlan.accepted_items || [],

package/src/agent-ops/query-builders/common.js

@@ -15,6 +15,8 @@ export function summarizeDiffArtifact(diffArtifact) {
     review_boundary_change_count: (diffArtifact.review_boundary_changes || []).length,
     maintained_file_count: (diffArtifact.affected_maintained_surfaces?.maintained_files_in_scope || []).length,
     affected_verification_count: (diffArtifact.affected_verifications || []).length,
+    widget_migration_count: (diffArtifact.widget_contract_migration_plan?.widgets || []).length,
+    widget_migration_projection_count: (diffArtifact.widget_contract_migration_plan?.affected_projection_ids || []).length,
     affected_output_count: maintainedOutputs.length,
     affected_seam_count: maintainedSeams.length,
     highest_maintained_severity: highestMaintainedSeverity

package/src/agent-ops/query-builders/multi-agent.js

@@ -496,6 +496,7 @@ export function buildMultiAgentPlanPayload({
   importPlan,
   report,
   adoptionStatus,
+  extractionContext = null,
   resolvedWorkflowContext = null
 }) {
   const presetGuidanceSummary = buildPresetGuidanceSummary(importPlan?.workflow_presets || null, resolvedWorkflowContext || singleAgentPlan?.resolved_workflow_context || null);
@@ -530,6 +531,7 @@ export function buildMultiAgentPlanPayload({
     active_preset_ids: presetGuidanceSummary.active_preset_ids,
     preset_blockers: presetGuidanceSummary.preset_blockers,
     recommended_preset_action: presetGuidanceSummary.recommended_preset_action,
+    extraction_context: extractionContext || singleAgentPlan?.extraction_context || resolvedWorkflowContext?.extraction_context || null,
     resolved_workflow_context: resolvedWorkflowContext || singleAgentPlan?.resolved_workflow_context || null,
     lanes,
     parallel_workstreams: parallelWorkstreams,

package/src/agent-ops/query-builders/work-packets.js

@@ -147,6 +147,7 @@ export function buildWorkPacketPayload({
   const publishedHandoffPacket = (multiAgentPlan?.handoff_packets || []).find((packet) => packet.from_lane === laneId)
     || handoffTemplateFromLane(lane, multiAgentPlan?.mode || null);
   const resolvedWorkflowContext = multiAgentPlan?.resolved_workflow_context || null;
+  const extractionContext = multiAgentPlan?.extraction_context || resolvedWorkflowContext?.extraction_context || null;
   const presetGuidanceSummary = multiAgentPlan?.preset_guidance_summary || buildPresetGuidanceSummary(null, resolvedWorkflowContext);
   const effectiveWriteScope = lane.workflow_context_overrides?.effective_write_scope || lane.write_scope || resolvedWorkflowContext?.effective_write_scope || null;
   const effectiveVerificationPolicy = lane.workflow_context_overrides?.effective_verification_policy || {
@@ -172,6 +173,7 @@ export function buildWorkPacketPayload({
     preset_guidance_summary: presetGuidanceSummary,
     active_preset_ids: presetGuidanceSummary.active_preset_ids,
     recommended_preset_action: presetGuidanceSummary.recommended_preset_action,
+    extraction_context: extractionContext,
     write_scope: lane.write_scope || null,
     effective_write_scope: effectiveWriteScope,
     owned_targets: lane.owned_targets || null,

package/src/agent-ops/query-builders/workflow-context.js

@@ -154,6 +154,7 @@ export function buildResolvedWorkflowContextPayload({
   reviewBoundary = null,
   maintainedBoundary = null,
   generatorTargets = [],
+  extractionContext = null,
   providerPresets = null,
   teamPresets = null,
   providerManifests = null,
@@ -326,6 +327,7 @@ export function buildResolvedWorkflowContextPayload({
     preferred_queries: preferredQueries,
     artifact_load_order: artifactLoadOrder,
     recommended_artifact_queries: recommendedArtifactQueries,
+    extraction_context: extractionContext,
     effective_write_scope: taskModeArtifact?.write_scope || null,
     effective_review_policy: {
       block_on: reviewBlockers,
@@ -362,6 +364,7 @@ export function buildSingleAgentPlanPayload({
   workspace,
   taskModeArtifact,
   importPlan = null,
+  extractionContext = null,
   resolvedWorkflowContext = null
 }) {
   const primaryArtifacts = stableOrderedUnion([
@@ -377,6 +380,7 @@ export function buildSingleAgentPlanPayload({
     current_focus: currentFocusFromTaskMode(taskModeArtifact),
     next_action: taskModeArtifact?.next_action || null,
     write_scope: taskModeArtifact?.write_scope || null,
+    extraction_context: extractionContext || resolvedWorkflowContext?.extraction_context || null,
     review_boundaries: buildReviewBoundaries(taskModeArtifact, importPlan),
     proof_targets: taskModeArtifact?.verification_targets || null,
     operator_loop: buildOperatorLoopSummary({

package/src/cli/command-parsers/sdlc.js

@@ -19,6 +19,9 @@ export function parseSdlcCommandArgs(args) {
   if (args[0] === "sdlc" && args[1] === "prep" && args[2] === "commit") {
     return { sdlcCommand: "prep:commit", inputPath: commandPath(args, 3, ".") };
   }
+  if (args[0] === "sdlc" && args[1] === "audit") {
+    return { sdlcCommand: "audit", inputPath: commandPath(args, 2, ".") };
+  }
   if (args[0] === "sdlc" && args[1] === "link") {
     return {
       sdlcCommand: "link",

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

@@ -97,6 +97,51 @@ export function queryDefinitions() {
       output: "single_agent_plan_query",
       example: "topogram query single-agent-plan ./topo --mode modeling --widget widget_data_grid --json"
     },
+    {
+      name: "extract-plan",
+      purpose: "Summarize brownfield extraction candidates, package extractor context, and adoption review state.",
+      description: "Return the extract/adopt plan for an extracted workspace, including trusted extraction provenance and next review commands.",
+      selectors: ["provider", "preset"],
+      args: ["[path]", "[--json]"],
+      output: "extract_plan_query",
+      example: "topogram query extract-plan ./extracted-topogram --json"
+    },
+    {
+      name: "multi-agent-plan",
+      purpose: "Split extract/adopt review into serialized and parallel agent lanes.",
+      description: "Return lane ownership, handoff packets, overlap rules, and package extractor context for extract/adopt mode.",
+      selectors: ["mode", "provider", "preset"],
+      args: ["[path]", "--mode extract-adopt", "[--json]"],
+      output: "multi_agent_plan",
+      example: "topogram query multi-agent-plan ./extracted-topogram --mode extract-adopt --json"
+    },
+    {
+      name: "work-packet",
+      purpose: "Give one extract/adopt lane its allowed inputs, write scope, blockers, and handoff packet.",
+      description: "Return a lane-scoped work packet for extract/adopt mode.",
+      selectors: ["mode", "lane"],
+      args: ["[path]", "--mode extract-adopt", "--lane <id>", "[--json]"],
+      output: "work_packet",
+      example: "topogram query work-packet ./extracted-topogram --mode extract-adopt --lane adoption_operator --json"
+    },
+    {
+      name: "lane-status",
+      purpose: "Show which extract/adopt lanes are ready, blocked, or complete.",
+      description: "Return artifact-derived lane status for extract/adopt mode.",
+      selectors: ["mode"],
+      args: ["[path]", "--mode extract-adopt", "[--json]"],
+      output: "lane_status_query",
+      example: "topogram query lane-status ./extracted-topogram --mode extract-adopt --json"
+    },
+    {
+      name: "handoff-status",
+      purpose: "Show extract/adopt handoff packet status across lanes.",
+      description: "Return handoff readiness and blockers for extract/adopt mode.",
+      selectors: ["mode"],
+      args: ["[path]", "--mode extract-adopt", "[--json]"],
+      output: "handoff_status_query",
+      example: "topogram query handoff-status ./extracted-topogram --mode extract-adopt --json"
+    },
     {
       name: "risk-summary",
       purpose: "Surface behavioral, ownership, and verification risks for a selected change.",

package/src/cli/commands/query/extract-adopt.js

@@ -16,6 +16,7 @@ import {
   buildTaskMode,
   normalizeTopogramPath,
   readJson,
+  readExtractionContext,
   requireReconcileArtifacts,
   resultOk,
   workflowPresetSelectors
@@ -50,6 +51,7 @@ export function buildImportPlanForContext(context, queryFamily) {
     workspace: topogramRoot,
     selectors: workflowPresetSelectors(taskModeResult.artifact, context.providerId, context.presetId, queryFamily)
   });
+  const extractionContext = readExtractionContext(topogramRoot);
   return {
     ok: true,
     topogramRoot,
@@ -60,7 +62,8 @@ export function buildImportPlanForContext(context, queryFamily) {
       adoptionPlan,
       taskModeResult.artifact,
       maintainedBundleResult.artifact.maintained_boundary || null,
-      workflowPresets
+      workflowPresets,
+      extractionContext
     )
   };
 }
@@ -85,17 +88,20 @@ export function buildImportAdoptAgentContext(context, queryFamily) {
     workspace: topogramRoot,
     selectors: workflowPresetSelectors(taskModeResult.artifact, context.providerId, context.presetId, queryFamily)
   });
-  const importPlan = buildImportPlanPayload(adoptionPlanArtifact, taskModeResult.artifact, null, workflowPresets);
+  const extractionContext = readExtractionContext(topogramRoot);
+  const importPlan = buildImportPlanPayload(adoptionPlanArtifact, taskModeResult.artifact, null, workflowPresets, extractionContext);
   const resolvedWorkflowContext = buildResolvedWorkflowContextPayload({
     workspace: topogramRoot,
     taskModeArtifact: taskModeResult.artifact,
     importPlan,
+    extractionContext,
     selectors: workflowPresetSelectors(taskModeResult.artifact, context.providerId, context.presetId, queryFamily)
   });
   const singleAgentPlan = buildSingleAgentPlanPayload({
     workspace: topogramRoot,
     taskModeArtifact: taskModeResult.artifact,
     importPlan,
+    extractionContext,
     resolvedWorkflowContext
   });
   const multiAgentPlan = buildMultiAgentPlanPayload({
@@ -104,6 +110,7 @@ export function buildImportAdoptAgentContext(context, queryFamily) {
     importPlan,
     report: reconcileReport,
     adoptionStatus,
+    extractionContext,
     resolvedWorkflowContext
   });
   return {

package/src/cli/commands/query/runner/workflow.js

@@ -26,6 +26,7 @@ import {
   normalizeTopogramPath,
   printValidationFailure,
   readJson,
+  readExtractionContext,
   resultOk,
   selectorOptions,
   workflowPresetSelectors
@@ -83,7 +84,7 @@ export function runWorkflowQuery(context) {
         workspace: topogramRoot,
         selectors: workflowPresetSelectors(taskModeResult.artifact, context.providerId, context.presetId, "workflow-preset-activation")
       });
-      importPlan = buildImportPlanPayload(readJson(adoptionPlanPath(topogramRoot)), taskModeResult.artifact, null, workflowPresets);
+      importPlan = buildImportPlanPayload(readJson(adoptionPlanPath(topogramRoot)), taskModeResult.artifact, null, workflowPresets, readExtractionContext(topogramRoot));
     }
     return printJson(buildWorkflowPresetActivationPayload({
       workspace: topogramRoot,
@@ -134,24 +135,28 @@ function runSingleAgentPlan(context, selectors) {
   });
   const topogramRoot = normalizeTopogramPath(context.inputPath);
   let importPlan = null;
+  let extractionContext = null;
   if (context.modeId === "extract-adopt" && fs.existsSync(adoptionPlanPath(topogramRoot))) {
+    extractionContext = readExtractionContext(topogramRoot);
     const workflowPresets = buildWorkflowPresetState({
       workspace: topogramRoot,
       selectors: workflowPresetSelectors(result.artifact, context.providerId, context.presetId, "single-agent-plan")
     });
-    importPlan = buildImportPlanPayload(readJson(adoptionPlanPath(topogramRoot)), result.artifact, null, workflowPresets);
+    importPlan = buildImportPlanPayload(readJson(adoptionPlanPath(topogramRoot)), result.artifact, null, workflowPresets, extractionContext);
   }
   const resolvedWorkflowContext = buildResolvedWorkflowContextPayload({
     workspace: topogramRoot,
     taskModeArtifact: result.artifact,
     generatorTargets,
     selectors: workflowPresetSelectors(result.artifact, context.providerId, context.presetId, "single-agent-plan"),
+    extractionContext,
     importPlan
   });
   return printJson(buildSingleAgentPlanPayload({
     workspace: topogramRoot,
     taskModeArtifact: result.artifact,
     importPlan,
+    extractionContext,
     resolvedWorkflowContext
   }));
 }
@@ -186,7 +191,9 @@ function runResolvedWorkflowContext(context, selectors) {
     maintainedBoundaryArtifact: maintainedBundleResult?.artifact?.maintained_boundary || null
   });
   let importPlan = null;
+  let extractionContext = null;
   if (context.modeId === "extract-adopt" && fs.existsSync(adoptionPlanPath(topogramRoot))) {
+    extractionContext = readExtractionContext(topogramRoot);
     const workflowPresets = buildWorkflowPresetState({
       workspace: topogramRoot,
       selectors: workflowPresetSelectors(taskModeResult.artifact, context.providerId, context.presetId, "resolved-workflow-context")
@@ -195,7 +202,8 @@ function runResolvedWorkflowContext(context, selectors) {
       readJson(adoptionPlanPath(topogramRoot)),
       taskModeResult.artifact,
       maintainedBundleResult?.artifact?.maintained_boundary || null,
-      workflowPresets
+      workflowPresets,
+      extractionContext
     );
   }
   return printJson(buildResolvedWorkflowContextPayload({
@@ -205,6 +213,7 @@ function runResolvedWorkflowContext(context, selectors) {
     reviewBoundary: sliceResult?.artifact?.review_boundary || null,
     maintainedBoundary: maintainedBundleResult?.artifact?.maintained_boundary || null,
     generatorTargets,
+    extractionContext,
     selectors: workflowPresetSelectors(taskModeResult.artifact, context.providerId, context.presetId, "resolved-workflow-context")
   }));
 }

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

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { generateWorkspace } from "../../../generator.js";
+import { TOPOGRAM_IMPORT_FILE } from "../../../import/provenance.js";
 import { formatValidationErrors } from "../../../validator.js";
 import { buildChangePlanPayload } from "../../../agent-ops/query-builders.js";
 import { resolveTopoRoot } from "../../../workspace-paths.js";
@@ -196,6 +197,73 @@ export function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, "utf8"));
 }
 
+/**
+ * @param {AnyRecord} record
+ * @param {string} provenancePath
+ * @returns {AnyRecord}
+ */
+export function buildExtractionContext(record, provenancePath) {
+  const extractorPackages = /** @type {AnyRecord[]} */ (Array.isArray(record.extract?.extractorPackages)
+    ? record.extract.extractorPackages
+    : []);
+  const packageBackedExtractors = extractorPackages
+    .filter((entry) => entry?.source === "package")
+    .map((entry) => ({
+      id: entry.id || null,
+      version: entry.version || null,
+      packageName: entry.packageName || null,
+      extractors: Array.isArray(entry.extractors) ? entry.extractors : [],
+      manifestPath: entry.manifestPath || null
+    }));
+  const bundledExtractors = extractorPackages
+    .filter((entry) => entry?.source === "bundled")
+    .map((entry) => ({
+      id: entry.id || null,
+      version: entry.version || null,
+      extractors: Array.isArray(entry.extractors) ? entry.extractors : []
+    }));
+  return {
+    type: "extraction_context",
+    provenance_path: provenancePath,
+    kind: record.kind || null,
+    extracted_at: record.extractedAt || null,
+    refreshed_at: record.refreshedAt || null,
+    source_path: record.source?.path || null,
+    tracks: Array.isArray(record.extract?.tracks) ? record.extract.tracks : [],
+    findings_count: record.extract?.findingsCount || 0,
+    candidate_counts: record.extract?.candidateCounts || {},
+    package_backed_extractors: packageBackedExtractors,
+    bundled_extractors: bundledExtractors,
+    summary: {
+      package_backed_extractor_count: packageBackedExtractors.length,
+      bundled_extractor_count: bundledExtractors.length,
+      source_file_count: Array.isArray(record.files) ? record.files.length : 0
+    },
+    next_commands: [
+      "topogram extract check",
+      "topogram extract plan",
+      "topogram adopt --list",
+      "topogram adopt <selector> --dry-run"
+    ],
+    safety_notes: [
+      "Extractor packages are evidence producers only; review candidates before canonical adoption.",
+      "Use dry-run adoption before --write, especially when package-backed extractors contributed candidates."
+    ]
+  };
+}
+
+/**
+ * @param {string} topogramRoot
+ * @returns {AnyRecord|null}
+ */
+export function readExtractionContext(topogramRoot) {
+  const provenancePath = path.join(path.dirname(topogramRoot), TOPOGRAM_IMPORT_FILE);
+  if (!fs.existsSync(provenancePath)) {
+    return null;
+  }
+  return buildExtractionContext(readJson(provenancePath), provenancePath);
+}
+
 /**
  * @param {AnyRecord} options
  * @returns {boolean}

package/src/cli/commands/sdlc.js

@@ -220,6 +220,21 @@ export async function runSdlcCommand(context) {
     return result.ok ? 0 : 1;
   }
 
+  if (commandArgs.sdlcCommand === "audit") {
+    const { auditWorkspace } = await import("../../sdlc/audit.js");
+    const resolved = resolveSdlcWorkspace(sdlcRoot);
+    if (!resolved) {
+      return 1;
+    }
+    const result = auditWorkspace(sdlcRoot, resolved);
+    if (json) {
+      console.log(stableStringify(result));
+    } else {
+      printSdlcAudit(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, {
@@ -374,3 +389,30 @@ export async function runSdlcCommand(context) {
 
   throw new Error(`Unknown sdlc command '${commandArgs.sdlcCommand}'`);
 }
+
+/**
+ * @param {AnyRecord} result
+ */
+function printSdlcAudit(result) {
+  console.log("SDLC audit");
+  console.log(`Workspace: ${result.workspaceRoot}`);
+  console.log(`Draft requirements with completed task evidence: ${result.counts?.draftRequirementsWithCompletedTasks || 0}`);
+  console.log(`Draft acceptance criteria with completed task evidence: ${result.counts?.draftAcceptanceCriteriaWithCompletedTasks || 0}`);
+  console.log(`Approved acceptance criteria with draft parent requirements: ${result.counts?.approvedAcceptanceCriteriaWithDraftRequirements || 0}`);
+  console.log(`Done tasks with draft refs: ${result.counts?.doneTasksWithDraftReferences || 0}`);
+  console.log(`Remaining draft backlog: ${result.counts?.remainingDraftPitches || 0} pitch(es), ${result.counts?.remainingDraftRequirements || 0} requirement(s), ${result.counts?.remainingDraftAcceptanceCriteria || 0} acceptance criterion/criteria`);
+  const findings = [
+    ...(result.findings?.draftRequirementsWithCompletedTasks || []),
+    ...(result.findings?.draftAcceptanceCriteriaWithCompletedTasks || []),
+    ...(result.findings?.approvedAcceptanceCriteriaWithDraftRequirements || []),
+    ...(result.findings?.doneTasksWithDraftReferences || [])
+  ];
+  if (findings.length > 0) {
+    console.log("Actionable findings:");
+    for (const finding of findings.slice(0, 10)) {
+      console.log(`- ${finding.id}: ${finding.recommendedCommand || "review status"}`);
+    }
+  } else {
+    console.log("Actionable findings: none");
+  }
+}

package/src/cli/help.js

@@ -19,6 +19,7 @@ export function printUsage(options = {}) {
   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 audit [path] [--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]");
@@ -94,6 +95,7 @@ export function printUsage(options = {}) {
   console.log("  topogram agent brief");
   console.log("  topogram agent brief --json");
   console.log("  topogram sdlc policy explain");
+  console.log("  topogram sdlc audit . --json");
   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");

package/src/generator/context/diff.js

@@ -128,6 +128,101 @@ function collectAffectedProjectionIds(graph, baselineGraph, diff) {
   ]);
 }
 
+const WIDGET_CONTRACT_SECTIONS = [
+  "category",
+  "version",
+  "status",
+  "props",
+  "events",
+  "slots",
+  "behavior",
+  "behaviors",
+  "patterns",
+  "regions",
+  "approvals",
+  "lookups",
+  "dependencies"
+];
+
+function changedWidgetContractSections(entry) {
+  if (entry.classification === "additive") {
+    return WIDGET_CONTRACT_SECTIONS.filter((section) => entry.current?.[section] != null);
+  }
+  if (entry.classification === "removed") {
+    return WIDGET_CONTRACT_SECTIONS.filter((section) => entry.baseline?.[section] != null);
+  }
+  return WIDGET_CONTRACT_SECTIONS.filter((section) =>
+    JSON.stringify(entry.current?.[section] ?? null) !== JSON.stringify(entry.baseline?.[section] ?? null)
+  );
+}
+
+function affectedProjectionIdsForWidgetChange(graph, baselineGraph, entry) {
+  if (entry.classification === "additive") {
+    return relatedProjectionsForWidget(graph, entry.id);
+  }
+  if (entry.classification === "removed") {
+    return relatedProjectionsForWidget(baselineGraph, entry.id);
+  }
+  return stableSortedStrings([
+    ...relatedProjectionsForWidget(graph, entry.id),
+    ...relatedProjectionsForWidget(baselineGraph, entry.id)
+  ]);
+}
+
+function projectionMigrationCommands(widgetId, projectionId) {
+  return [
+    {
+      target: "ui-widget-contract",
+      command: `topogram emit ui-widget-contract ./topo --widget ${widgetId} --json`,
+      reason: `Refresh the normalized widget contract for ${widgetId}.`
+    },
+    {
+      target: "widget-conformance-report",
+      command: `topogram emit widget-conformance-report ./topo --projection ${projectionId} --json`,
+      reason: `Review projection ${projectionId} widget placement, required props, events, and region/pattern compatibility.`
+    },
+    {
+      target: "widget-behavior-report",
+      command: `topogram widget behavior ./topo --projection ${projectionId} --widget ${widgetId} --json`,
+      reason: `Review behavior data/event/action wiring for ${widgetId} on projection ${projectionId}.`
+    },
+    {
+      target: "ui-surface-contract",
+      command: `topogram emit ui-surface-contract ./topo --projection ${projectionId} --json`,
+      reason: `Refresh the surface contract consumed by stack generators for projection ${projectionId}.`
+    }
+  ];
+}
+
+function buildWidgetContractMigrationPlan(graph, baselineGraph, diff) {
+  const widgets = (diff.widgets || []).map((entry) => {
+    const affectedProjectionIds = affectedProjectionIdsForWidgetChange(graph, baselineGraph, entry);
+    return {
+      widget_id: entry.id,
+      classification: entry.classification,
+      changed_sections: changedWidgetContractSections(entry),
+      affected_projection_ids: affectedProjectionIds,
+      affected_projections: affectedProjectionIds
+        .map((id) => summarizeById(graph, id) || summarizeById(baselineGraph, id))
+        .filter(Boolean),
+      review_commands: affectedProjectionIds.flatMap((projectionId) => projectionMigrationCommands(entry.id, projectionId)),
+      migration_steps: [
+        "Review changed_sections to understand the semantic widget contract delta.",
+        "Refresh the widget contract and affected surface contracts.",
+        "Run conformance and behavior reports for every affected projection.",
+        "Regenerate generated-owned outputs or manually update maintained surfaces after review."
+      ]
+    };
+  });
+
+  return {
+    widgets,
+    affected_widget_ids: stableSortedStrings(widgets.map((entry) => entry.widget_id)),
+    affected_projection_ids: stableSortedStrings(widgets.flatMap((entry) => entry.affected_projection_ids)),
+    review_command_count: widgets.reduce((count, entry) => count + entry.review_commands.length, 0)
+  };
+}
+
 function collectAffectedCapabilityIds(graph, diff) {
   const changedCapabilities = stableSortedStrings((diff.capabilities || []).map((entry) => entry.id));
   const changedEntities = stableSortedStrings((diff.entities || []).map((entry) => entry.id));
@@ -213,6 +308,7 @@ export function generateContextDiff(graph, options = {}) {
   const affectedCapabilities = collectAffectedCapabilityIds(graph, diff);
   const affectedProjections = collectAffectedProjectionIds(graph, baselineGraph, diff);
   const affectedVerifications = collectAffectedVerificationIds(graph, diff);
+  const widgetContractMigrationPlan = buildWidgetContractMigrationPlan(graph, baselineGraph, diff);
   const changedSemanticIds = changedIdsForDiffSections(diff);
   const affectedMaintainedStories = maintainedProofMetadata(graph).filter((item) => {
     const emittedDependencies = item.emittedDependencies || [];
@@ -257,6 +353,7 @@ export function generateContextDiff(graph, options = {}) {
       }))
     },
     affected_verifications: affectedVerifications.map((id) => summarizeById(graph, id) || summarizeById(baselineGraph, id)).filter(Boolean),
+    widget_contract_migration_plan: widgetContractMigrationPlan,
     review_boundary_changes: reviewBoundaryChangeItems,
     sdlc: sdlcChanges
   };

package/src/generator/registry/index.js

@@ -6,7 +6,11 @@ import {
   packageInstallHint,
   resolvePackageManifestPath
 } from "../../package-adapters/index.js";
-import { UI_GENERATOR_RENDERED_COMPONENT_PATTERNS } from "../../ui/taxonomy.js";
+import {
+  UI_GENERATOR_RENDERED_COMPONENT_PATTERNS,
+  UI_PATTERN_KINDS,
+  WIDGET_BEHAVIOR_KINDS
+} from "../../ui/taxonomy.js";
 
 /**
  * @typedef {Object} GeneratorManifest
@@ -193,6 +197,18 @@ function isStringArray(value, nonEmpty = false) {
     value.every((entry) => typeof entry === "string" && entry.length > 0);
 }
 
+/**
+ * @param {any} value
+ * @param {Set<string>} allowed
+ * @returns {string[]}
+ */
+function unsupportedStringValues(value, allowed) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((entry) => typeof entry === "string" && !allowed.has(entry));
+}
+
 /**
  * @param {string} oldName
  * @param {string} newName
@@ -377,9 +393,15 @@ export function validateGeneratorManifest(manifest) {
       if (manifest.widgetSupport.patterns != null && !isStringArray(manifest.widgetSupport.patterns)) {
         errors.push(`${label} widgetSupport.patterns must be a string array`);
       }
+      for (const pattern of unsupportedStringValues(manifest.widgetSupport.patterns, UI_PATTERN_KINDS)) {
+        errors.push(`${label} widgetSupport.patterns contains unsupported pattern '${pattern}'`);
+      }
       if (manifest.widgetSupport.behaviors != null && !isStringArray(manifest.widgetSupport.behaviors)) {
         errors.push(`${label} widgetSupport.behaviors must be a string array`);
       }
+      for (const behavior of unsupportedStringValues(manifest.widgetSupport.behaviors, WIDGET_BEHAVIOR_KINDS)) {
+        errors.push(`${label} widgetSupport.behaviors contains unsupported behavior '${behavior}'`);
+      }
       if (
         manifest.widgetSupport.unsupported != null &&
         !["error", "warning", "contract-only"].includes(manifest.widgetSupport.unsupported)

package/src/sdlc/audit.js

@@ -0,0 +1,205 @@
+// @ts-check
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+const DONE_TASK_STATUSES = new Set(["done"]);
+
+/**
+ * @param {unknown} refs
+ * @returns {string[]}
+ */
+function refIds(refs) {
+  if (!Array.isArray(refs)) {
+    return [];
+  }
+  return refs
+    .map((ref) => {
+      if (typeof ref === "string") {
+        return ref;
+      }
+      if (ref && typeof ref === "object" && "id" in ref) {
+        return String(ref.id);
+      }
+      return "";
+    })
+    .filter(Boolean);
+}
+
+/**
+ * @param {AnyRecord} statement
+ * @returns {{ id: string, name: string|null, status: string|null, file: string|null }}
+ */
+function summary(statement) {
+  return {
+    id: String(statement.id || ""),
+    name: typeof statement.name === "string" ? statement.name : null,
+    status: typeof statement.status === "string" ? statement.status : null,
+    file: typeof statement.loc?.file === "string" ? statement.loc.file : null
+  };
+}
+
+/**
+ * @param {Map<string, AnyRecord[]>} map
+ * @param {string} key
+ * @param {AnyRecord} value
+ */
+function pushMap(map, key, value) {
+  const values = map.get(key) || [];
+  values.push(value);
+  map.set(key, values);
+}
+
+/**
+ * @param {AnyRecord} graph
+ * @param {string} id
+ * @returns {AnyRecord|null}
+ */
+function byId(graph, id) {
+  const value = graph?.byId?.get ? graph.byId.get(id) : graph?.byId?.[id];
+  if (value && typeof value === "object") {
+    return value;
+  }
+  const byKind = graph?.byKind || {};
+  for (const statements of Object.values(byKind)) {
+    if (!Array.isArray(statements)) {
+      continue;
+    }
+    const found = statements.find((statement) => statement?.id === id);
+    if (found && typeof found === "object") {
+      return found;
+    }
+  }
+  return value && typeof value === "object" ? value : null;
+}
+
+/**
+ * Reports SDLC status hygiene issues that are easy to miss after implementation:
+ * draft requirements or acceptance criteria that already have completed task
+ * evidence, and approved acceptance criteria whose parent requirement is still
+ * draft. The audit is read-only.
+ *
+ * @param {string} workspaceRoot
+ * @param {AnyRecord} resolved
+ * @returns {AnyRecord}
+ */
+export function auditWorkspace(workspaceRoot, resolved) {
+  const graph = resolved.graph || {};
+  const byKind = graph.byKind || {};
+  /** @type {AnyRecord[]} */
+  const tasks = Array.isArray(byKind.task) ? byKind.task : [];
+  /** @type {AnyRecord[]} */
+  const requirements = Array.isArray(byKind.requirement) ? byKind.requirement : [];
+  /** @type {AnyRecord[]} */
+  const acceptanceCriteria = Array.isArray(byKind.acceptance_criterion) ? byKind.acceptance_criterion : [];
+  /** @type {AnyRecord[]} */
+  const pitches = Array.isArray(byKind.pitch) ? byKind.pitch : [];
+
+  const doneTasks = tasks.filter((task) => DONE_TASK_STATUSES.has(String(task.status || "")));
+  /** @type {Map<string, AnyRecord[]>} */
+  const doneTasksByRequirement = new Map();
+  /** @type {Map<string, AnyRecord[]>} */
+  const doneTasksByAcceptance = new Map();
+
+  for (const task of doneTasks) {
+    for (const id of refIds(task.satisfies)) {
+      pushMap(doneTasksByRequirement, id, task);
+    }
+    for (const id of refIds(task.acceptanceRefs)) {
+      pushMap(doneTasksByAcceptance, id, task);
+    }
+  }
+
+  const draftRequirementsWithCompletedTasks = requirements
+    .filter((requirement) => requirement.status === "draft" && doneTasksByRequirement.has(String(requirement.id || "")))
+    .map((requirement) => ({
+      ...summary(requirement),
+      completedTasks: (doneTasksByRequirement.get(String(requirement.id || "")) || []).map(summary),
+      recommendedCommand: `topogram sdlc transition ${requirement.id} in-review . --actor <actor> --note "<reason>"`
+    }));
+
+  const draftAcceptanceCriteriaWithCompletedTasks = acceptanceCriteria
+    .filter((criterion) => criterion.status === "draft" && doneTasksByAcceptance.has(String(criterion.id || "")))
+    .map((criterion) => ({
+      ...summary(criterion),
+      completedTasks: (doneTasksByAcceptance.get(String(criterion.id || "")) || []).map(summary),
+      recommendedCommand: `topogram sdlc transition ${criterion.id} approved . --actor <actor> --note "<reason>"`
+    }));
+
+  const approvedAcceptanceCriteriaWithDraftRequirements = acceptanceCriteria
+    .filter((criterion) => {
+      if (criterion.status !== "approved") {
+        return false;
+      }
+      const requirementId = criterion.requirement?.id || "";
+      const requirement = requirementId ? byId(graph, requirementId) : null;
+      return requirement?.status === "draft";
+    })
+    .map((criterion) => {
+      const requirement = byId(graph, criterion.requirement?.id || "");
+      return {
+        ...summary(criterion),
+        requirement: requirement ? summary(requirement) : null,
+        recommendedCommand: requirement
+          ? `topogram sdlc transition ${requirement.id} in-review . --actor <actor> --note "<reason>"`
+          : null
+      };
+    });
+
+  const doneTasksWithDraftReferences = doneTasks
+    .map((task) => {
+      const draftRequirements = refIds(task.satisfies)
+        .map((id) => byId(graph, id))
+        .filter((statement) => statement?.status === "draft")
+        .map((statement) => summary(/** @type {AnyRecord} */ (statement)));
+      const draftAcceptanceCriteria = refIds(task.acceptanceRefs)
+        .map((id) => byId(graph, id))
+        .filter((statement) => statement?.status === "draft")
+        .map((statement) => summary(/** @type {AnyRecord} */ (statement)));
+      return {
+        ...summary(task),
+        draftRequirements,
+        draftAcceptanceCriteria
+      };
+    })
+    .filter((task) => task.draftRequirements.length > 0 || task.draftAcceptanceCriteria.length > 0);
+
+  const counts = {
+    draftRequirementsWithCompletedTasks: draftRequirementsWithCompletedTasks.length,
+    draftAcceptanceCriteriaWithCompletedTasks: draftAcceptanceCriteriaWithCompletedTasks.length,
+    approvedAcceptanceCriteriaWithDraftRequirements: approvedAcceptanceCriteriaWithDraftRequirements.length,
+    doneTasksWithDraftReferences: doneTasksWithDraftReferences.length,
+    remainingDraftPitches: pitches.filter((pitch) => pitch.status === "draft").length,
+    remainingDraftRequirements: requirements.filter((requirement) => requirement.status === "draft").length,
+    remainingDraftAcceptanceCriteria: acceptanceCriteria.filter((criterion) => criterion.status === "draft").length
+  };
+  const actionableFindings =
+    counts.draftRequirementsWithCompletedTasks +
+    counts.draftAcceptanceCriteriaWithCompletedTasks +
+    counts.approvedAcceptanceCriteriaWithDraftRequirements +
+    counts.doneTasksWithDraftReferences;
+
+  return {
+    type: "sdlc_audit",
+    version: "1",
+    ok: actionableFindings === 0,
+    workspaceRoot,
+    counts,
+    findings: {
+      draftRequirementsWithCompletedTasks,
+      draftAcceptanceCriteriaWithCompletedTasks,
+      approvedAcceptanceCriteriaWithDraftRequirements,
+      doneTasksWithDraftReferences
+    },
+    remainingDrafts: {
+      pitches: pitches.filter((pitch) => pitch.status === "draft").map(summary),
+      requirements: requirements.filter((requirement) => requirement.status === "draft").map(summary),
+      acceptanceCriteria: acceptanceCriteria.filter((criterion) => criterion.status === "draft").map(summary)
+    },
+    nextCommands: [
+      "topogram sdlc check --strict",
+      "topogram sdlc prep commit . --json"
+    ]
+  };
+}

package/src/ui/taxonomy.js

@@ -155,6 +155,51 @@ export const UI_GENERATOR_RENDERED_COMPONENT_PATTERNS = new Set([
   "data_grid_view"
 ]);
 
+export const WIDGET_CATEGORIES = new Set([
+  "collection",
+  "form",
+  "display",
+  "navigation",
+  "dialog",
+  "feedback",
+  "lookup",
+  "layout",
+  "service"
+]);
+
+export const WIDGET_BEHAVIOR_KINDS = new Set([
+  "selection",
+  "sorting",
+  "filtering",
+  "search",
+  "pagination",
+  "grouping",
+  "drag_drop",
+  "inline_edit",
+  "bulk_action",
+  "optimistic_update",
+  "realtime_update",
+  "keyboard_navigation"
+]);
+
+export const WIDGET_BEHAVIOR_DIRECTIVES = {
+  selection: new Set(["mode", "state", "emits"]),
+  sorting: new Set(["fields", "default"]),
+  filtering: new Set(["fields"]),
+  search: new Set(["fields"]),
+  pagination: new Set(["mode", "page_size"]),
+  grouping: new Set(["fields"]),
+  drag_drop: new Set(["axis", "reorder"]),
+  inline_edit: new Set(["fields", "submit", "emits"]),
+  bulk_action: new Set(["actions", "state", "emits"]),
+  optimistic_update: new Set(["actions", "rollback"]),
+  realtime_update: new Set(["source", "merge"]),
+  keyboard_navigation: new Set(["scope", "shortcuts"])
+};
+
+export const WIDGET_SELECTION_MODES = new Set(["single", "multi", "none"]);
+export const WIDGET_PAGINATION_MODES = new Set(["cursor", "paged", "infinite", "none"]);
+
 /**
  * @param {string[]} presentations
  * @returns {string}

package/src/validator/kinds.d.ts

@@ -47,4 +47,9 @@ export const UI_DESIGN_COLOR_ROLES: Set<string>;
 export const UI_DESIGN_TYPOGRAPHY_ROLES: Set<string>;
 export const UI_DESIGN_ACTION_ROLES: Set<string>;
 export const UI_DESIGN_ACCESSIBILITY_VALUES: Record<string, Set<string>>;
+export const WIDGET_CATEGORIES: Set<string>;
+export const WIDGET_BEHAVIOR_KINDS: Set<string>;
+export const WIDGET_BEHAVIOR_DIRECTIVES: Record<string, Set<string>>;
+export const WIDGET_SELECTION_MODES: Set<string>;
+export const WIDGET_PAGINATION_MODES: Set<string>;
 export const FIELD_SPECS: Record<string, { required: string[]; allowed: string[] }>;

package/src/validator/kinds.js

@@ -107,7 +107,12 @@ export {
   UI_DESIGN_COLOR_ROLES,
   UI_DESIGN_TYPOGRAPHY_ROLES,
   UI_DESIGN_ACTION_ROLES,
-  UI_DESIGN_ACCESSIBILITY_VALUES
+  UI_DESIGN_ACCESSIBILITY_VALUES,
+  WIDGET_CATEGORIES,
+  WIDGET_BEHAVIOR_KINDS,
+  WIDGET_BEHAVIOR_DIRECTIVES,
+  WIDGET_SELECTION_MODES,
+  WIDGET_PAGINATION_MODES
 } from "../ui/taxonomy.js";
 
 // Kinds that may carry an optional singular `domain dom_x` field. Keep this

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

@@ -1,5 +1,10 @@
 // @ts-check
 import {
+  WIDGET_BEHAVIOR_DIRECTIVES,
+  WIDGET_BEHAVIOR_KINDS,
+  WIDGET_CATEGORIES,
+  WIDGET_PAGINATION_MODES,
+  WIDGET_SELECTION_MODES,
   UI_PATTERN_KINDS,
   UI_REGION_KINDS
 } from "../kinds.js";
@@ -10,49 +15,6 @@ import {
   symbolValues
 } from "../utils.js";
 
-const WIDGET_CATEGORIES = new Set([
-  "collection",
-  "form",
-  "display",
-  "navigation",
-  "dialog",
-  "feedback",
-  "lookup",
-  "layout",
-  "service"
-]);
-
-const WIDGET_BEHAVIOR_KINDS = new Set([
-  "selection",
-  "sorting",
-  "filtering",
-  "search",
-  "pagination",
-  "grouping",
-  "drag_drop",
-  "inline_edit",
-  "bulk_action",
-  "optimistic_update",
-  "realtime_update",
-  "keyboard_navigation"
-]);
-
-/** @type {Record<string, Set<string>>} */
-const WIDGET_BEHAVIOR_DIRECTIVES = {
-  selection: new Set(["mode", "state", "emits"]),
-  sorting: new Set(["fields", "default"]),
-  filtering: new Set(["fields"]),
-  search: new Set(["fields"]),
-  pagination: new Set(["mode", "page_size"]),
-  grouping: new Set(["fields"]),
-  drag_drop: new Set(["axis", "reorder"]),
-  inline_edit: new Set(["fields", "submit", "emits"]),
-  bulk_action: new Set(["actions", "state", "emits"]),
-  optimistic_update: new Set(["actions", "rollback"]),
-  realtime_update: new Set(["source", "merge"]),
-  keyboard_navigation: new Set(["scope", "shortcuts"])
-};
-
 /** @param {TopogramToken | null | undefined} token @returns {any} */
 function tokenValue(token) {
   return token?.value ?? null;
@@ -262,10 +224,10 @@ function validateWidgetBehaviors(errors, statement, fieldMap, registry) {
       if (directive === "actions" || directive === "submit") {
         validateBehaviorActionReferences(errors, statement, registry, kind, directive, valueToken, eventNames);
       }
-      if (kind === "selection" && directive === "mode" && !["single", "multi", "none"].includes(tokenValue(valueToken))) {
+      if (kind === "selection" && directive === "mode" && !WIDGET_SELECTION_MODES.has(tokenValue(valueToken))) {
         pushError(errors, `Widget ${statement.id} behavior 'selection' has invalid mode '${tokenValue(valueToken)}'`, valueToken.loc);
       }
-      if (kind === "pagination" && directive === "mode" && !["cursor", "paged", "infinite", "none"].includes(tokenValue(valueToken))) {
+      if (kind === "pagination" && directive === "mode" && !WIDGET_PAGINATION_MODES.has(tokenValue(valueToken))) {
         pushError(errors, `Widget ${statement.id} behavior 'pagination' has invalid mode '${tokenValue(valueToken)}'`, valueToken.loc);
       }
     }