@topogram/cli 0.3.82 → 0.3.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.82",
+  "version": "0.3.84",
   "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/command-parsers/extractor.js

@@ -2,6 +2,17 @@
 
 import { commandPath } from "./shared.js";
 
+/**
+ * @param {string[]} args
+ * @param {string} flag
+ * @returns {string|null}
+ */
+function optionValue(args, flag) {
+  const index = args.indexOf(flag);
+  const value = index >= 0 ? args[index + 1] : null;
+  return value && !value.startsWith("-") ? value : null;
+}
+
 /**
  * @param {string[]} args
  * @returns {import("./shared.js").SplitCommandArgs|null}
@@ -16,6 +27,15 @@ export function parseExtractorCommandArgs(args) {
   if (args[0] === "extractor" && args[1] === "check") {
     return { extractorCommand: "check", inputPath: args[2] };
   }
+  if (args[0] === "extractor" && args[1] === "scaffold") {
+    return {
+      extractorCommand: "scaffold",
+      inputPath: args[2],
+      extractorScaffoldTrack: optionValue(args, "--track"),
+      extractorScaffoldPackage: optionValue(args, "--package"),
+      extractorScaffoldId: optionValue(args, "--id")
+    };
+  }
   if (args[0] === "extractor" && args[1] === "policy" && args[2] === "init") {
     return { extractorPolicyCommand: "init", inputPath: commandPath(args, 3, ".") };
   }
@@ -37,4 +57,3 @@ export function parseExtractorCommandArgs(args) {
   }
   return null;
 }
-

package/src/cli/commands/extractor.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { stableStringify } from "../../format.js";
 import { checkExtractorPack } from "../../extractor/check.js";
 import { FIRST_PARTY_EXTRACTOR_PACKAGES, firstPartyExtractorInfo } from "../../extractor/first-party.js";
+import { scaffoldExtractorPack } from "../../extractor/scaffold.js";
 import {
   EXTRACTOR_MANIFESTS,
   getExtractorManifest,
@@ -30,6 +31,7 @@ export function printExtractorHelp() {
   console.log("Usage: topogram extractor list [--json]");
   console.log("   or: topogram extractor show <id-or-package> [--json]");
   console.log("   or: topogram extractor check <path-or-package> [--json]");
+  console.log("   or: topogram extractor scaffold <target> [--track <track>] [--package <name>] [--id <manifest-id>] [--json]");
   console.log("   or: topogram extractor policy init [path] [--json]");
   console.log("   or: topogram extractor policy status [path] [--json]");
   console.log("   or: topogram extractor policy check [path] [--json]");
@@ -48,11 +50,37 @@ export function printExtractorHelp() {
   console.log("  topogram extractor show topogram/api-extractors");
   console.log("  topogram extractor show @topogram/extractor-prisma-db");
   console.log("  topogram extractor check ./extractor-package");
+  console.log("  topogram extractor scaffold ./topogram-extractor-node-cli --track cli --package @scope/topogram-extractor-node-cli");
   console.log("  topogram extractor policy init");
   console.log("  topogram extractor policy pin @topogram/extractor-node-cli@1");
   console.log("  topogram extract ./express-api --out ./imported-topogram --from api --extractor @topogram/extractor-express-api");
 }
 
+/**
+ * @param {ReturnType<typeof scaffoldExtractorPack>} payload
+ * @returns {void}
+ */
+export function printExtractorScaffold(payload) {
+  console.log(payload.ok ? "Extractor scaffold created." : "Extractor scaffold failed.");
+  console.log(`Target: ${payload.target}`);
+  if (payload.packageName) console.log(`Package: ${payload.packageName}`);
+  if (payload.manifestId) console.log(`Manifest id: ${payload.manifestId}`);
+  if (payload.track) console.log(`Track: ${payload.track}`);
+  if (payload.files.length > 0) {
+    console.log("Files:");
+    for (const file of payload.files) {
+      console.log(`- ${file}`);
+    }
+  }
+  if (payload.nextCommands.length > 0) {
+    console.log("Next commands:");
+    for (const command of payload.nextCommands) {
+      console.log(`- ${command}`);
+    }
+  }
+  for (const error of payload.errors || []) console.log(`Error: ${error}`);
+}
+
 /**
  * @param {string} cwd
  * @returns {string[]}
@@ -587,6 +615,16 @@ export function runExtractorCommand(context) {
     else printExtractorCheck(payload);
     return payload.ok ? 0 : 1;
   }
+  if (commandArgs.extractorCommand === "scaffold") {
+    const payload = scaffoldExtractorPack(inputPath || "", {
+      track: commandArgs.extractorScaffoldTrack,
+      packageName: commandArgs.extractorScaffoldPackage,
+      manifestId: commandArgs.extractorScaffoldId
+    });
+    if (json) console.log(stableStringify(payload));
+    else printExtractorScaffold(payload);
+    return payload.ok ? 0 : 1;
+  }
   if (commandArgs.extractorCommand === "list") {
     const payload = buildExtractorListPayload(cwd);
     if (json) console.log(stableStringify(payload));

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/help.js

@@ -71,6 +71,7 @@ export function printUsage(options = {}) {
   console.log("   or: topogram extractor list [--json]");
   console.log("   or: topogram extractor show <id-or-package> [--json]");
   console.log("   or: topogram extractor check <path-or-package> [--json]");
+  console.log("   or: topogram extractor scaffold <target> [--track <track>] [--package <name>] [--id <manifest-id>] [--json]");
   console.log("   or: topogram extractor policy init [path] [--json]");
   console.log("   or: topogram extractor policy status [path] [--json]");
   console.log("   or: topogram extractor policy check [path] [--json]");
@@ -111,6 +112,7 @@ export function printUsage(options = {}) {
   console.log("  topogram extractor list");
   console.log("  topogram extractor show @topogram/extractor-prisma-db");
   console.log("  topogram extractor check ./extractor-package");
+  console.log("  topogram extractor scaffold ./topogram-extractor-node-cli --track cli --package @scope/topogram-extractor-node-cli");
   console.log("  topogram extractor policy check");
   console.log("  topogram extract ./express-api --out ./extracted-topogram --from api --extractor @topogram/extractor-express-api");
   console.log("  topogram generate");

package/src/extractor/scaffold.js

@@ -0,0 +1,482 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { stableStringify } from "../format.js";
+import { EXTRACTOR_TRACKS } from "./registry.js";
+
+const DEFAULT_TRACK = "cli";
+
+/**
+ * @typedef {Object} ExtractorScaffoldOptions
+ * @property {string|null|undefined} [packageName]
+ * @property {string|null|undefined} [manifestId]
+ * @property {string|null|undefined} [track]
+ */
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function slugify(value) {
+  return String(value || "extractor")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "extractor";
+}
+
+/**
+ * @param {string} target
+ * @returns {string}
+ */
+function defaultPackageName(target) {
+  const basename = slugify(path.basename(path.resolve(target)));
+  return basename.startsWith("topogram-extractor-") ? basename : `topogram-extractor-${basename}`;
+}
+
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isValidPackageName(value) {
+  return /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value);
+}
+
+/**
+ * @returns {string}
+ */
+function currentCliVersion() {
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+    return typeof packageJson.version === "string" && packageJson.version ? packageJson.version : "latest";
+  } catch {
+    return "latest";
+  }
+}
+
+/**
+ * @param {string} packageName
+ * @param {string} track
+ * @returns {string}
+ */
+function extractorId(packageName, track) {
+  const bareName = packageName.split("/").pop() || packageName;
+  return `${track}.${slugify(bareName.replace(/^topogram-extractor-/, "").replace(/^extractor-/, ""))}`;
+}
+
+/**
+ * @param {string} track
+ * @returns {{ stack: Record<string, string>, capabilities: Record<string, boolean>, candidateKinds: string[], fixtureFiles: Record<string, string> }}
+ */
+function trackDefaults(track) {
+  if (track === "db") {
+    return {
+      stack: { domain: "database", framework: "scaffold" },
+      capabilities: { schema: true },
+      candidateKinds: ["entity"],
+      fixtureFiles: {
+        "package.json": `${stableStringify({ name: "topogram-extractor-fixture-db", private: true })}\n`,
+        "src/schema.sql": "create table scaffold_records (id text primary key, name text not null);\n"
+      }
+    };
+  }
+  if (track === "api") {
+    return {
+      stack: { runtime: "node", framework: "scaffold" },
+      capabilities: { routes: true },
+      candidateKinds: ["capability", "route", "stack"],
+      fixtureFiles: {
+        "package.json": `${stableStringify({ name: "topogram-extractor-fixture-api", private: true })}\n`,
+        "src/server.js": "app.get('/scaffold-records', listScaffoldRecords);\n"
+      }
+    };
+  }
+  if (track === "ui") {
+    return {
+      stack: { framework: "scaffold-ui" },
+      capabilities: { screens: true, flows: true },
+      candidateKinds: ["screen", "route", "flow"],
+      fixtureFiles: {
+        "package.json": `${stableStringify({ name: "topogram-extractor-fixture-ui", private: true })}\n`,
+        "src/routes/scaffold-records.jsx": "export default function ScaffoldRecords() { return <main>Scaffold records</main>; }\n"
+      }
+    };
+  }
+  if (track === "workflows") {
+    return {
+      stack: { domain: "workflow" },
+      capabilities: { workflows: true },
+      candidateKinds: ["workflow"],
+      fixtureFiles: {
+        "package.json": `${stableStringify({ name: "topogram-extractor-fixture-workflows", private: true })}\n`,
+        "docs/workflows.md": "# Scaffold workflow\n\n- draft\n- review\n- complete\n"
+      }
+    };
+  }
+  if (track === "verification") {
+    return {
+      stack: { domain: "verification" },
+      capabilities: { verifications: true },
+      candidateKinds: ["verification"],
+      fixtureFiles: {
+        "package.json": `${stableStringify({ name: "topogram-extractor-fixture-verification", private: true, scripts: { test: "node test.js" } })}\n`,
+        "test.js": "console.log('scaffold verification fixture');\n"
+      }
+    };
+  }
+  return {
+    stack: { runtime: "node", framework: "generic-cli" },
+    capabilities: { commands: true, options: true, effects: true },
+    candidateKinds: ["command", "capability", "cli_surface"],
+    fixtureFiles: {
+      "package.json": `${stableStringify({ name: "topogram-extractor-fixture-cli", private: true, bin: { scaffold: "./bin/scaffold.js" } })}\n`,
+      "bin/scaffold.js": "#!/usr/bin/env node\nconsole.log('Usage: scaffold check --json');\n"
+    }
+  };
+}
+
+/**
+ * @param {string} track
+ * @returns {string}
+ */
+function candidateSourceForTrack(track) {
+  if (track === "db") {
+    return `{
+        entities: [{
+          id_hint: "entity_scaffold_record",
+          label: "Scaffold Record",
+          confidence: "low",
+          provenance: ["package-extractor-scaffold"],
+          fields: [{ name: "id", field_type: "string", required: true }]
+        }]
+      }`;
+  }
+  if (track === "api") {
+    return `{
+        capabilities: [{
+          id_hint: "cap_list_scaffold_records",
+          label: "List scaffold records",
+          confidence: "low",
+          provenance: ["package-extractor-scaffold"]
+        }],
+        routes: [{
+          method: "GET",
+          path: "/scaffold-records",
+          capability_hint: "cap_list_scaffold_records",
+          confidence: "low",
+          provenance: ["package-extractor-scaffold"]
+        }],
+        stacks: ["scaffold-api"]
+      }`;
+  }
+  if (track === "ui") {
+    return `{
+        screens: [{
+          id_hint: "screen_scaffold_records",
+          label: "Scaffold Records",
+          screen_kind: "list",
+          route_path: "/scaffold-records",
+          confidence: "low",
+          provenance: ["package-extractor-scaffold"]
+        }],
+        routes: [{
+          id_hint: "route_scaffold_records",
+          path: "/scaffold-records",
+          screen_id: "screen_scaffold_records",
+          confidence: "low",
+          provenance: ["package-extractor-scaffold"]
+        }],
+        flows: [],
+        stacks: ["scaffold-ui"]
+      }`;
+  }
+  if (track === "workflows") {
+    return `{
+        workflows: [{
+          id_hint: "workflow_scaffold_review",
+          label: "Scaffold Review",
+          confidence: "low",
+          provenance: ["package-extractor-scaffold"]
+        }]
+      }`;
+  }
+  if (track === "verification") {
+    return `{
+        verifications: [{
+          id_hint: "verification_scaffold_check",
+          label: "Scaffold Check",
+          confidence: "low",
+          provenance: ["package-extractor-scaffold"]
+        }],
+        frameworks: ["scaffold"],
+        scripts: [{
+          id_hint: "script_scaffold_check",
+          command: "npm test",
+          confidence: "low",
+          provenance: ["package-extractor-scaffold"]
+        }]
+      }`;
+  }
+  return `{
+        commands: [{
+          command_id: "scaffold_check",
+          label: "Scaffold Check",
+          usage: "scaffold check --json",
+          provenance: ["package-extractor-scaffold"]
+        }],
+        capabilities: [{
+          id_hint: "cap_scaffold_check",
+          label: "Run scaffold check",
+          command_id: "scaffold_check",
+          provenance: ["package-extractor-scaffold"]
+        }],
+        surfaces: [{
+          id_hint: "proj_cli_surface",
+          commands: ["scaffold_check"],
+          options: [{ command_id: "scaffold_check", name: "json", flag: "--json", type: "boolean", required: false }],
+          effects: [{ command_id: "scaffold_check", effect: "read_only" }],
+          provenance: ["package-extractor-scaffold"]
+        }]
+      }`;
+}
+
+/**
+ * @param {string} track
+ * @param {string} extractor
+ * @returns {string}
+ */
+function adapterSource(track, extractor) {
+  return `const manifest = require("./topogram-extractor.json");
+
+exports.manifest = manifest;
+exports.extractors = [{
+  id: ${JSON.stringify(extractor)},
+  track: ${JSON.stringify(track)},
+  detect(context) {
+    return { score: 1, reasons: ["Scaffold extractor runs against the included fixture."] };
+  },
+  extract(context) {
+    return {
+      findings: [{
+        kind: "scaffold_finding",
+        message: "Replace this scaffold extractor with precise framework evidence.",
+        evidence: ["fixtures/basic-source"]
+      }],
+      candidates: ${candidateSourceForTrack(track)},
+      diagnostics: []
+    };
+  }
+}];
+`;
+}
+
+/**
+ * @param {string} packageName
+ * @param {string} track
+ * @returns {string}
+ */
+function checkScriptSource(packageName, track) {
+  return `import childProcess from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const packageJson = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const packageName = packageJson.name || ${JSON.stringify(packageName)};
+const track = ${JSON.stringify(track)};
+const topogramBin = process.env.TOPOGRAM_BIN || "topogram";
+const root = process.cwd();
+
+function run(args, options = {}) {
+  const result = childProcess.spawnSync(topogramBin, args, {
+    cwd: options.cwd || root,
+    encoding: "utf8",
+    env: { ...process.env, FORCE_COLOR: "0" },
+    maxBuffer: 1024 * 1024 * 10
+  });
+  if (result.status !== 0) {
+    process.stderr.write(result.stdout || "");
+    process.stderr.write(result.stderr || "");
+    throw new Error(\`Command failed: \${topogramBin} \${args.join(" ")}\`);
+  }
+  return result.stdout;
+}
+
+function snapshotFixture() {
+  const fixtureRoot = path.join(root, "fixtures", "basic-source");
+  const files = [];
+  function visit(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const absolute = path.join(dir, entry.name);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile()) files.push([path.relative(fixtureRoot, absolute), fs.readFileSync(absolute, "utf8")]);
+    }
+  }
+  visit(fixtureRoot);
+  return JSON.stringify(files.sort());
+}
+
+run(["extractor", "check", "."]);
+
+const before = snapshotFixture();
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "topogram-extractor-smoke."));
+const policyPath = path.join(tmp, "topogram.extractor-policy.json");
+fs.writeFileSync(policyPath, JSON.stringify({
+  version: "0.1",
+  allowedPackageScopes: [],
+  allowedPackages: [packageName],
+  pinnedVersions: { [packageName]: "1" },
+  enabledPackages: []
+}, null, 2) + "\\n", "utf8");
+
+const extracted = path.join(tmp, "extracted");
+run([
+  "extract",
+  path.join(root, "fixtures", "basic-source"),
+  "--out",
+  extracted,
+  "--from",
+  track,
+  "--extractor",
+  ".",
+  "--extractor-policy",
+  policyPath,
+  "--json"
+]);
+run(["extract", "plan", extracted, "--json"]);
+run(["query", "extract-plan", path.join(extracted, "topo"), "--json"]);
+run(["adopt", "--list", extracted, "--json"]);
+
+const after = snapshotFixture();
+if (after !== before) {
+  throw new Error("Extractor smoke mutated fixture source files.");
+}
+
+console.log(\`Extractor package smoke passed for \${packageName}.\`);
+`;
+}
+
+/**
+ * @param {Record<string, string>} files
+ * @returns {string[]}
+ */
+function writeFiles(files) {
+  const written = [];
+  for (const [filePath, contents] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, contents, "utf8");
+    written.push(filePath);
+  }
+  return written.sort();
+}
+
+/**
+ * @param {string} target
+ * @param {ExtractorScaffoldOptions} [options]
+ * @returns {{ ok: boolean, target: string, packageName: string|null, manifestId: string|null, track: string|null, files: string[], nextCommands: string[], errors: string[] }}
+ */
+export function scaffoldExtractorPack(target, options = {}) {
+  const absoluteTarget = path.resolve(target || "");
+  if (!target || target.startsWith("-")) {
+    return { ok: false, target: absoluteTarget, packageName: null, manifestId: null, track: null, files: [], nextCommands: [], errors: ["Usage: topogram extractor scaffold <target> [--track <track>] [--package <name>] [--id <manifest-id>]"] };
+  }
+  if (fs.existsSync(absoluteTarget) && fs.readdirSync(absoluteTarget).length > 0) {
+    return { ok: false, target: absoluteTarget, packageName: null, manifestId: null, track: null, files: [], nextCommands: [], errors: [`Extractor scaffold target '${absoluteTarget}' already exists and is not empty.`] };
+  }
+
+  const track = options.track || DEFAULT_TRACK;
+  if (!EXTRACTOR_TRACKS.includes(track)) {
+    return { ok: false, target: absoluteTarget, packageName: null, manifestId: null, track, files: [], nextCommands: [], errors: [`Extractor track '${track}' is not supported. Expected one of: ${EXTRACTOR_TRACKS.join(", ")}.`] };
+  }
+
+  const packageName = options.packageName || defaultPackageName(absoluteTarget);
+  if (!isValidPackageName(packageName)) {
+    return { ok: false, target: absoluteTarget, packageName, manifestId: null, track, files: [], nextCommands: [], errors: [`Extractor package name '${packageName}' is invalid. Use a lowercase npm package name such as @scope/topogram-extractor-example.`] };
+  }
+  const manifestId = options.manifestId || packageName;
+  const extractor = extractorId(packageName, track);
+  const defaults = trackDefaults(track);
+  const manifest = {
+    id: manifestId,
+    version: "1",
+    tracks: [track],
+    source: "package",
+    package: packageName,
+    stack: defaults.stack,
+    capabilities: defaults.capabilities,
+    candidateKinds: defaults.candidateKinds,
+    evidenceTypes: ["runtime_source"],
+    extractors: [extractor]
+  };
+  const packageJson = {
+    name: packageName,
+    version: "0.1.0",
+    private: true,
+    description: "Topogram extractor pack scaffold.",
+    main: "index.cjs",
+    files: [
+      "index.cjs",
+      "topogram-extractor.json",
+      "README.md",
+      "scripts",
+      "fixtures"
+    ],
+    scripts: {
+      check: "node ./scripts/check-extractor.mjs"
+    },
+    devDependencies: {
+      "@topogram/cli": `^${currentCliVersion()}`
+    }
+  };
+  const files = {
+    [path.join(absoluteTarget, "package.json")]: `${stableStringify(packageJson)}\n`,
+    [path.join(absoluteTarget, "topogram-extractor.json")]: `${stableStringify(manifest)}\n`,
+    [path.join(absoluteTarget, "index.cjs")]: adapterSource(track, extractor),
+    [path.join(absoluteTarget, "scripts", "check-extractor.mjs")]: checkScriptSource(packageName, track),
+    [path.join(absoluteTarget, "README.md")]: `# ${packageName}
+
+This is a Topogram extractor pack scaffold for the \`${track}\` track.
+
+## Author Loop
+
+\`\`\`bash
+npm install
+npm run check
+\`\`\`
+
+\`npm run check\` runs:
+
+- \`topogram extractor check .\`
+- \`topogram extract ./fixtures/basic-source --out <tmp> --from ${track} --extractor .\`
+- \`topogram extract plan <tmp>\`
+- \`topogram query extract-plan <tmp>/topo\`
+- \`topogram adopt --list <tmp>\`
+
+Replace the scaffold adapter in \`index.cjs\` with precise, read-only source evidence.
+Extractor packages must not mutate source files, write canonical \`topo/**\`, install
+packages, perform network access, or define adoption semantics.
+`
+  };
+  for (const [relative, contents] of Object.entries(defaults.fixtureFiles)) {
+    files[path.join(absoluteTarget, "fixtures", "basic-source", relative)] = contents;
+  }
+
+  const written = writeFiles(files);
+  return {
+    ok: true,
+    target: absoluteTarget,
+    packageName,
+    manifestId,
+    track,
+    files: written.map((filePath) => path.relative(absoluteTarget, filePath).replace(/\\/g, "/")),
+    nextCommands: [
+      `cd ${absoluteTarget}`,
+      "npm install",
+      "npm run check",
+      "topogram extractor check ."
+    ],
+    errors: []
+  };
+}