@topogram/cli 0.3.82 → 0.3.83

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.82",
+  "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/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/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}