@topogram/cli 0.3.75 → 0.3.77

package/package.json

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

package/src/adoption/plan/index.js

@@ -637,6 +637,7 @@ function mappingSuggestionsForItem(item) {
 }
 
 export function buildAgentAdoptionPlan(adoptionPlan, maintainedBoundaryArtifact = null) {
+  const importedMaintainedDbSeams = [...(adoptionPlan?.imported_maintained_db_seams || [])];
   const items = (adoptionPlan?.items || []).map((item) => {
     const currentState = inferCurrentAdoptionState(item);
     const maintainedSeamCandidates = inferMaintainedSeamCandidates({
@@ -656,6 +657,9 @@ export function buildAgentAdoptionPlan(adoptionPlan, maintainedBoundaryArtifact
       ui_impacts: [...(item.ui_impacts || [])],
       workflow_impacts: [...(item.workflow_impacts || [])]
     }, maintainedBoundaryArtifact);
+    const importedDbSeamCandidates = ["entity", "enum", "index", "relation", "db"].includes(item.kind) || item.track === "db"
+      ? importedMaintainedDbSeams
+      : [];
     return {
       id: adoptionItemKey(item),
       bundle: item.bundle,
@@ -691,11 +695,68 @@ export function buildAgentAdoptionPlan(adoptionPlan, maintainedBoundaryArtifact
       projection_impacts: [...(item.projection_impacts || [])],
       ui_impacts: [...(item.ui_impacts || [])],
       workflow_impacts: [...(item.workflow_impacts || [])],
-      maintained_seam_candidates: maintainedSeamCandidates,
+      maintained_seam_candidates: [...maintainedSeamCandidates, ...importedDbSeamCandidates],
       mapping_suggestions: mappingSuggestionsForItem(item),
       available_actions: ADOPTION_STATE_VOCABULARY
     };
   });
+  const importedDbSeamSurfaces = importedMaintainedDbSeams.map((seam) => ({
+    id: seam.id_hint || seam.seam_id,
+    bundle: "database",
+    item: seam.id_hint || seam.seam_id,
+    kind: seam.kind || "maintained_db_migration_seam",
+    track: "db",
+    source_kind: seam.source_kind || "migration_strategy_inference",
+    source_path: "candidates/app/db/candidates.json",
+    canonical_rel_path: null,
+    related_shapes: [],
+    review_boundary: {
+      automation_class: "review_required",
+      reasons: [
+        "manual_project_config_review",
+        "proposal_only_maintained_db_migration_seam"
+      ]
+    },
+    current_state: "stage",
+    recommended_state: "customize",
+    supported_states: ADOPTION_STATE_VOCABULARY,
+    human_review_required: true,
+    provenance: {
+      bundle: "database",
+      source_path: "candidates/app/db/candidates.json",
+      canonical_rel_path: null
+    },
+    requirements: {
+      related_docs: [],
+      related_capabilities: [],
+      related_shapes: [],
+      related_rules: [],
+      related_workflows: [],
+      blocking_dependencies: []
+    },
+    projection_impacts: [],
+    ui_impacts: [],
+    workflow_impacts: [],
+    maintained_seam_candidates: [seam],
+    mapping_suggestions: [{
+      type: "manual_project_config_review",
+      id: seam.id_hint || seam.seam_id,
+      reason: "Review the inferred database migration strategy before editing topogram.project.json.",
+      project_config_target: seam.project_config_target || {
+        file: "topogram.project.json",
+        path: "topology.runtimes[].migration"
+      },
+      proposed_runtime_migration: seam.proposed_runtime_migration || null,
+      missing_decisions: seam.missing_decisions || [],
+      evidence: seam.evidence || seam.provenance || [],
+      manual_next_steps: seam.manual_next_steps || [
+        "Review evidence and missing decisions.",
+        "Manually copy the accepted migration strategy into topogram.project.json."
+      ]
+    }],
+    available_actions: ADOPTION_STATE_VOCABULARY
+  }));
+  const proposalSurfaces = [...items, ...importedDbSeamSurfaces];
 
   return {
     type: "agent_adoption_plan",
@@ -708,10 +769,11 @@ export function buildAgentAdoptionPlan(adoptionPlan, maintainedBoundaryArtifact
       non_canonical_adoption_state: "stage"
     },
     approved_review_groups: [...new Set(adoptionPlan?.approved_review_groups || [])].sort(),
-    imported_proposal_surfaces: items,
-    staged_items: items.filter((item) => item.current_state === "stage").map((item) => item.id),
-    accepted_items: items.filter((item) => item.current_state === "accept").map((item) => item.id),
-    rejected_items: items.filter((item) => item.current_state === "reject").map((item) => item.id),
-    requires_human_review: items.filter((item) => item.human_review_required).map((item) => item.id)
+    imported_maintained_db_seam_candidates: importedMaintainedDbSeams,
+    imported_proposal_surfaces: proposalSurfaces,
+    staged_items: proposalSurfaces.filter((item) => item.current_state === "stage").map((item) => item.id),
+    accepted_items: proposalSurfaces.filter((item) => item.current_state === "accept").map((item) => item.id),
+    rejected_items: proposalSurfaces.filter((item) => item.current_state === "reject").map((item) => item.id),
+    requires_human_review: proposalSurfaces.filter((item) => item.human_review_required).map((item) => item.id)
   };
 }

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

@@ -110,10 +110,12 @@ export function importCandidateCounts(summary) {
   return {
     dbEntities: candidates.db?.entities?.length || 0,
     dbEnums: candidates.db?.enums?.length || 0,
+    dbMaintainedSeams: candidates.db?.maintained_seams?.length || 0,
     apiCapabilities: candidates.api?.capabilities?.length || 0,
     apiRoutes: candidates.api?.routes?.length || 0,
     uiScreens: candidates.ui?.screens?.length || 0,
     uiRoutes: candidates.ui?.routes?.length || 0,
+    uiFlows: candidates.ui?.flows?.length || 0,
     uiWidgets: candidates.ui?.widgets?.length || candidates.ui?.components?.length || 0,
     uiShapes: candidates.ui?.shapes?.length || 0,
     cliCommands: candidates.cli?.commands?.length || 0,

package/src/cli.js

@@ -63,18 +63,18 @@ const inputPath = commandArgs && Object.prototype.hasOwnProperty.call(commandArg
 const cliOptions = parseCliOptions(args, commandArgs);
 
 try {
-  process.exit(await runCliDispatch({
+  process.exitCode = await runCliDispatch({
     args,
     commandArgs,
     inputPath,
     cliOptions,
     executablePath: path.resolve(process.argv[1] || fileURLToPath(import.meta.url))
-  }));
+  });
 } catch (error) {
   if (error.validation) {
     console.error(formatValidationErrors(error.validation));
   } else {
     console.error(error.message);
   }
-  process.exit(1);
+  process.exitCode = 1;
 }

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

@@ -261,7 +261,8 @@ export function normalizeCandidatesForTrack(track, candidates) {
       entities: dedupeCandidateRecords(candidates.entities || [], idHint),
       enums: dedupeCandidateRecords(candidates.enums || [], idHint),
       relations: dedupeCandidateRecords(candidates.relations || [], idHint),
-      indexes: dedupeCandidateRecords(candidates.indexes || [], idHint)
+      indexes: dedupeCandidateRecords(candidates.indexes || [], idHint),
+      maintained_seams: dedupeCandidateRecords(candidates.maintained_seams || [], idHint)
     };
   }
   if (track === "api") {
@@ -283,6 +284,7 @@ export function normalizeCandidatesForTrack(track, candidates) {
       screens: dedupeCandidateRecords(candidates.screens || [], idHint),
       routes: dedupeCandidateRecords(candidates.routes || [], idHint),
       actions: dedupeCandidateRecords(candidates.actions || [], idHint),
+      flows: dedupeCandidateRecords(candidates.flows || [], idHint),
       widgets,
       shapes: dedupeCandidateRecords([...(candidates.shapes || []), ...eventShapes], idHint),
       stacks: [...new Set(candidates.stacks || [])].sort()
@@ -329,6 +331,7 @@ export function enrichUiWidgetDataSources(uiCandidates, allCandidates) {
   const { components, ...canonicalCandidates } = uiCandidates;
   return {
     ...canonicalCandidates,
+    flows: dedupeCandidateRecords(canonicalCandidates.flows || [], (/** @type {any} */ flow) => flow.id_hint),
     widgets: widgets.map((widget) => {
       const dataSource = inferredDataSourceForWidget(widget, allCandidates);
       const dataProp = widget.data_prop || "rows";

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

@@ -10,8 +10,14 @@ import { uiWidgetCandidates } from "./candidates.js";
  */
 export function reportMarkdown(track, candidates) {
   if (track === "db") {
+    const seamLines = (candidates.maintained_seams || []).flatMap((/** @type {any} */ seam) => [
+      `- \`${seam.id_hint}\` tool \`${seam.tool}\` confidence ${seam.confidence || "unknown"} schema \`${seam.schemaPath || "none"}\` migrations \`${seam.migrationsPath || "review-required"}\` missing decisions ${(seam.missing_decisions || []).length}`,
+      `  - project config target: \`${seam.project_config_target?.path || "topology.runtimes[].migration"}\``,
+      `  - evidence: ${(seam.evidence || []).slice(0, 3).map((/** @type {string} */ item) => `\`${item}\``).join(", ") || "_none_"}`,
+      `  - manual next: ${(seam.manual_next_steps || []).slice(0, 2).join(" ")}`
+    ]);
     return ensureTrailingNewline(
-      `# DB Import Report\n\n- Entities: ${candidates.entities.length}\n- Enums: ${candidates.enums.length}\n- Relations: ${candidates.relations.length}\n- Indexes: ${candidates.indexes.length}\n`
+      `# DB Import Report\n\n- Entities: ${candidates.entities.length}\n- Enums: ${candidates.enums.length}\n- Relations: ${candidates.relations.length}\n- Indexes: ${candidates.indexes.length}\n- Maintained DB migration seams: ${(candidates.maintained_seams || []).length}\n\n## Maintained DB Migration Seam Candidates\n\n${seamLines.length ? seamLines.join("\n") : "- none"}\n`
     );
   }
   if (track === "api") {
@@ -22,11 +28,15 @@ export function reportMarkdown(track, candidates) {
   if (track === "ui") {
     const widgets = uiWidgetCandidates(candidates);
     const shapes = candidates.shapes || [];
+    const flows = candidates.flows || [];
     const widgetLines = widgets.map((widget) =>
       `- \`${widget.id_hint}\` confidence ${widget.confidence || "unknown"} pattern \`${widget.pattern || widget.inferred_pattern || "unknown"}\` region \`${widget.region || widget.inferred_region || "unknown"}\` events ${(widget.inferred_events || []).length} evidence ${(widget.evidence || widget.provenance || []).length} missing decisions ${(widget.missing_decisions || []).length}`
     );
+    const flowLines = flows.map((/** @type {any} */ flow) =>
+      `- \`${flow.id_hint}\` type \`${flow.flow_type}\` confidence ${flow.confidence || "unknown"} routes ${(flow.route_paths || []).map((/** @type {string} */ route) => `\`${route}\``).join(", ") || "_none_"} missing decisions ${(flow.missing_decisions || []).length}`
+    );
     return ensureTrailingNewline(
-      `# UI Import Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Widgets: ${widgets.length}\n- Event payload shapes: ${shapes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n\n## Widget Candidates\n\n${widgetLines.length ? widgetLines.join("\n") : "- none"}\n\n## Next Validation\n\n- Review candidates under \`topo/candidates/app/ui/drafts/widgets/**\`.\n- Run \`topogram import plan <path>\` before adoption.\n- After adoption, run \`topogram check <path>\`, \`topogram widget check <path>\`, and \`topogram widget behavior <path>\`.\n`
+      `# UI Import Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Flow candidates: ${flows.length}\n- Widgets: ${widgets.length}\n- Event payload shapes: ${shapes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n\n## Flow Candidates\n\n${flowLines.length ? flowLines.join("\n") : "- none"}\n\n## Widget Candidates\n\n${widgetLines.length ? widgetLines.join("\n") : "- none"}\n\n## Next Validation\n\n- Review flow candidates in \`topo/candidates/app/ui/candidates.json\` before adding shared UI contract behavior.\n- Review candidates under \`topo/candidates/app/ui/drafts/widgets/**\`.\n- Run \`topogram import plan <path>\` before adoption.\n- After adoption, run \`topogram check <path>\`, \`topogram widget check <path>\`, and \`topogram widget behavior <path>\`.\n`
     );
   }
   if (track === "cli") {
@@ -54,6 +64,6 @@ export function reportMarkdown(track, candidates) {
  */
 export function appReportMarkdown(candidates, tracks) {
   return ensureTrailingNewline(
-    `# App Import Report\n\nTracks: ${tracks.join(", ")}\n\n## DB\n\n- Entities: ${candidates.db?.entities?.length || 0}\n- Enums: ${candidates.db?.enums?.length || 0}\n- Relations: ${candidates.db?.relations?.length || 0}\n\n## API\n\n- Capabilities: ${candidates.api?.capabilities?.length || 0}\n- Routes: ${candidates.api?.routes?.length || 0}\n- Stacks: ${candidates.api?.stacks?.length ? candidates.api.stacks.join(", ") : "none"}\n\n## UI\n\n- Screens: ${candidates.ui?.screens?.length || 0}\n- Routes: ${candidates.ui?.routes?.length || 0}\n- Actions: ${candidates.ui?.actions?.length || 0}\n- Widgets: ${uiWidgetCandidates(candidates.ui).length}\n- Event payload shapes: ${candidates.ui?.shapes?.length || 0}\n- Stacks: ${candidates.ui?.stacks?.length ? candidates.ui.stacks.join(", ") : "none"}\n\n## CLI\n\n- Commands: ${candidates.cli?.commands?.length || 0}\n- Capabilities: ${candidates.cli?.capabilities?.length || 0}\n- CLI surfaces: ${candidates.cli?.surfaces?.length || 0}\n\n## Workflows\n\n- Workflows: ${candidates.workflows?.workflows?.length || 0}\n- States: ${candidates.workflows?.workflow_states?.length || 0}\n- Transitions: ${candidates.workflows?.workflow_transitions?.length || 0}\n\n## Verification\n\n- Verifications: ${candidates.verification?.verifications?.length || 0}\n- Scenarios: ${candidates.verification?.scenarios?.length || 0}\n- Frameworks: ${candidates.verification?.frameworks?.length ? candidates.verification.frameworks.join(", ") : "none"}\n- Scripts: ${candidates.verification?.scripts?.length || 0}\n`
+    `# App Import Report\n\nTracks: ${tracks.join(", ")}\n\n## DB\n\n- Entities: ${candidates.db?.entities?.length || 0}\n- Enums: ${candidates.db?.enums?.length || 0}\n- Relations: ${candidates.db?.relations?.length || 0}\n- Maintained DB migration seams: ${candidates.db?.maintained_seams?.length || 0}\n\n## API\n\n- Capabilities: ${candidates.api?.capabilities?.length || 0}\n- Routes: ${candidates.api?.routes?.length || 0}\n- Stacks: ${candidates.api?.stacks?.length ? candidates.api.stacks.join(", ") : "none"}\n\n## UI\n\n- Screens: ${candidates.ui?.screens?.length || 0}\n- Routes: ${candidates.ui?.routes?.length || 0}\n- Actions: ${candidates.ui?.actions?.length || 0}\n- Flow candidates: ${candidates.ui?.flows?.length || 0}\n- Widgets: ${uiWidgetCandidates(candidates.ui).length}\n- Event payload shapes: ${candidates.ui?.shapes?.length || 0}\n- Stacks: ${candidates.ui?.stacks?.length ? candidates.ui.stacks.join(", ") : "none"}\n\n## CLI\n\n- Commands: ${candidates.cli?.commands?.length || 0}\n- Capabilities: ${candidates.cli?.capabilities?.length || 0}\n- CLI surfaces: ${candidates.cli?.surfaces?.length || 0}\n\n## Workflows\n\n- Workflows: ${candidates.workflows?.workflows?.length || 0}\n- States: ${candidates.workflows?.workflow_states?.length || 0}\n- Transitions: ${candidates.workflows?.workflow_transitions?.length || 0}\n\n## Verification\n\n- Verifications: ${candidates.verification?.verifications?.length || 0}\n- Scenarios: ${candidates.verification?.scenarios?.length || 0}\n- Frameworks: ${candidates.verification?.frameworks?.length ? candidates.verification.frameworks.join(", ") : "none"}\n- Scripts: ${candidates.verification?.scripts?.length || 0}\n`
   );
 }

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

@@ -96,13 +96,13 @@ function selectDetectionsForTrack(track, detections) {
  */
 function initialCandidatesForTrack(track) {
   if (track === "db") {
-    return { entities: [], enums: [], relations: [], indexes: [] };
+    return { entities: [], enums: [], relations: [], indexes: [], maintained_seams: [] };
   }
   if (track === "api") {
     return { capabilities: [], routes: [], stacks: [] };
   }
   if (track === "ui") {
-    return { screens: [], routes: [], actions: [], stacks: [] };
+    return { screens: [], routes: [], actions: [], flows: [], stacks: [] };
   }
   if (track === "cli") {
     return { commands: [], capabilities: [], surfaces: [] };

package/src/import/core/shared/files.js

@@ -6,12 +6,17 @@ import { relativeTo } from "../../../path-helpers.js";
 export const DEFAULT_IGNORED_DIRS = new Set([
   ".git",
   ".next",
+  ".tmp",
   ".turbo",
   ".yarn",
+  ".cache",
+  ".parcel-cache",
+  ".svelte-kit",
   "build",
   "coverage",
   "dist",
   "node_modules",
+  "out",
   "tmp"
 ]);
 
@@ -82,6 +87,54 @@ export function normalizeImportRelativePath(paths, filePath) {
   return relativeTo(paths.repoRoot, filePath);
 }
 
+/**
+ * @param {import("./types.d.ts").ImportPaths} paths
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function importSourcePathRelativeToWorkspace(paths, filePath) {
+  return relativeTo(paths.workspaceRoot, filePath).replaceAll(path.sep, "/");
+}
+
+/**
+ * @param {import("./types.d.ts").ImportPaths} paths
+ * @param {string} filePath
+ * @returns {"runtime_source"|"parser_config"|"docs"|"tests"|"fixtures"|"generated_output"}
+ */
+export function classifyImportSourcePath(paths, filePath) {
+  const relativePath = importSourcePathRelativeToWorkspace(paths, filePath);
+  const basename = path.basename(relativePath).toLowerCase();
+  if (/(^|\/)(\.tmp|tmp|temp|dist|build|coverage|out|generated|docs-generated|snapshots?)(\/|$)/i.test(relativePath)) {
+    return "generated_output";
+  }
+  if (/(^|\/)[^/]*templates?[^/]*(\/|$)/i.test(relativePath)) {
+    return "fixtures";
+  }
+  if (/(^|\/)(test|tests|__tests__|spec|specs|mocks?)(\/|$)|\.(test|spec)\.(js|jsx|ts|tsx|mjs|cjs)$/i.test(relativePath)) {
+    return "tests";
+  }
+  if (/(^|\/)(fixture|fixtures|examples?)(\/|$)/i.test(relativePath)) {
+    return "fixtures";
+  }
+  if (/(^|\/)(doc|docs|documentation|guides?)(\/|$)|^(readme|changelog|contributing|license)(\.[a-z0-9]+)?$/i.test(relativePath) || /^(readme|changelog|contributing|license)(\.[a-z0-9]+)?$/i.test(basename)) {
+    return "docs";
+  }
+  if (/(^|\/)(package\.json|openapi\.(json|ya?ml)|swagger\.(json|ya?ml)|drizzle\.config\.(ts|js|mjs|cjs)|tsconfig\.json)$/i.test(relativePath)) {
+    return "parser_config";
+  }
+  return "runtime_source";
+}
+
+/**
+ * @param {import("./types.d.ts").ImportPaths} paths
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isPrimaryImportSource(paths, filePath) {
+  const sourceType = classifyImportSourcePath(paths, filePath);
+  return sourceType === "runtime_source" || sourceType === "parser_config";
+}
+
 /**
  * @param {import("./types.d.ts").ImportPaths} paths
  * @param {string} filePath
@@ -130,6 +183,9 @@ export function canonicalSourceRank(paths, filePath, kind) {
       rank += penalty.weight;
     }
   }
+  if (!isPrimaryImportSource(paths, filePath)) {
+    rank += 1000;
+  }
   return rank;
 }
 

package/src/import/core/shared/next-app.js

@@ -10,7 +10,7 @@ import {
   normalizeEndpointPathForMatch,
   normalizeOpenApiPath
 } from "./api-routes.js";
-import { entityIdForRoute, screenIdForRoute, screenKindForRoute, uiCapabilityHintsForRoute } from "./ui-routes.js";
+import { entityIdForRoute, inferNonResourceUiFlow, screenIdForRoute, screenKindForRoute, uiCapabilityHintsForRoute } from "./ui-routes.js";
 
 /**
  * @param {string} rootDir
@@ -48,7 +48,7 @@ export function inferNextAppRoutes(rootDir) {
  */
 export function nextScreenKindForRoute(routePath) {
   const normalized = String(routePath || "");
-  if (/\/(login|register|setup)$/.test(normalized)) return "flow";
+  if (inferNonResourceUiFlow(normalized) || /\/(login|register|setup)$/.test(normalized)) return "flow";
   return screenKindForRoute(routePath);
 }
 

package/src/import/core/shared/ui-routes.js

@@ -5,6 +5,51 @@ import { relativeTo } from "../../../path-helpers.js";
 import { canonicalCandidateTerm } from "./candidates.js";
 import { listFilesRecursive, readTextIfExists } from "./files.js";
 
+const NON_RESOURCE_FLOW_DEFINITIONS = [
+  {
+    flow_type: "auth",
+    concept_id: "flow_auth",
+    pattern: /\/(login|log-in|signin|sign-in|sign_in|logout|log-out|register|signup|sign-up|forgot-password|reset-password|password-reset)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm auth provider and session lifecycle", "confirm success and failure destinations"]
+  },
+  {
+    flow_type: "onboarding_wizard",
+    concept_id: "flow_onboarding",
+    pattern: /\/(onboarding|setup|welcome|get-started|getting-started|wizard|stepper)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm step order and completion criteria", "confirm resumability and exit behavior"]
+  },
+  {
+    flow_type: "settings_preferences",
+    concept_id: "flow_settings",
+    pattern: /\/(settings|preferences|profile|account|billing|security)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm settings ownership boundary", "confirm save, validation, and permission behavior"]
+  },
+  {
+    flow_type: "dashboard_reporting",
+    concept_id: "flow_dashboard",
+    pattern: /\/(dashboard|reports|reporting|analytics|insights|metrics)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm reporting data sources", "confirm refresh cadence and empty states"]
+  },
+  {
+    flow_type: "search_filter",
+    concept_id: "flow_search",
+    pattern: /\/(search|results|explore|browse|discover)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm searchable resources", "confirm filter, sorting, and pagination behavior"]
+  },
+  {
+    flow_type: "bulk_review",
+    concept_id: "flow_bulk_review",
+    pattern: /\/(review|reviews|approvals|approval|moderation|queue|bulk)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm bulk action eligibility", "confirm review outcomes and audit requirements"]
+  }
+];
+
 /**
  * @param {string} routePath
  * @returns {any}
@@ -23,12 +68,72 @@ export function routeSegments(routePath) {
 export function screenKindForRoute(routePath) {
   const normalized = String(routePath || "");
   const segments = routeSegments(normalized);
+  if (inferNonResourceUiFlow(normalized)) return "flow";
   if (/\/new$/.test(normalized)) return "form";
   if (/\/:?[A-Za-z0-9_]+\/edit$/.test(normalized)) return "form";
   if (segments.length >= 2 && !/\/new$/.test(normalized) && !/\/edit$/.test(normalized)) return "detail";
   return "list";
 }
 
+/**
+ * @param {string} routePath
+ * @returns {any}
+ */
+export function inferNonResourceUiFlow(routePath) {
+  const normalized = String(routePath || "");
+  for (const definition of NON_RESOURCE_FLOW_DEFINITIONS) {
+    if (definition.pattern.test(normalized)) {
+      return {
+        flow_type: definition.flow_type,
+        concept_id: definition.concept_id,
+        confidence: definition.confidence,
+        missing_decisions: definition.missing_decisions
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} routePath
+ * @param {string} screenId
+ * @returns {any}
+ */
+export function uiFlowIdForRoute(routePath, screenId) {
+  const flow = inferNonResourceUiFlow(routePath);
+  if (!flow) return null;
+  return `flow_${canonicalCandidateTerm(screenId || flow.flow_type).replace(/-/g, "_")}`;
+}
+
+/**
+ * @param {string} routePath
+ * @param {string} screenId
+ * @param {string} screenKind
+ * @returns {any}
+ */
+export function proposedUiContractAdditionsForFlow(routePath, screenId, screenKind) {
+  return {
+    projection_type: "ui_contract",
+    screens: [
+      {
+        id: screenId,
+        kind: screenKind || "flow",
+        title: screenId
+      }
+    ],
+    screen_routes: [
+      {
+        screen: screenId,
+        path: routePath
+      }
+    ],
+    notes: [
+      "Review-only flow recovery proposal.",
+      "Promote into the shared UI contract only after confirming behavior, state, and ownership decisions."
+    ]
+  };
+}
+
 /**
  * @param {string} routePath
  * @returns {any}
@@ -37,6 +142,7 @@ export function screenIdForRoute(routePath) {
   const segments = routeSegments(routePath);
   const resource = canonicalCandidateTerm(segments[0] || "home");
   const kind = screenKindForRoute(routePath);
+  if (kind === "flow") return canonicalCandidateTerm(segments.join("_") || "home").replace(/-/g, "_");
   if (kind === "form" && /\/new$/.test(routePath)) return `${resource}_create`;
   if (kind === "form" && /\/edit$/.test(routePath)) return `${resource}_edit`;
   if (kind === "detail") return `${resource}_detail`;

package/src/import/core/shared.js

@@ -19,6 +19,9 @@ export {
   listFilesRecursive,
   importSearchRoots,
   normalizeImportRelativePath,
+  importSourcePathRelativeToWorkspace,
+  classifyImportSourcePath,
+  isPrimaryImportSource,
   canonicalSourceRank,
   selectPreferredImportFiles,
   findImportFiles
@@ -38,6 +41,9 @@ export {
   screenIdForRoute,
   uiCapabilityHintsForRoute,
   entityIdForRoute,
+  inferNonResourceUiFlow,
+  uiFlowIdForRoute,
+  proposedUiContractAdditionsForFlow,
   inferReactRoutes,
   inferSvelteRoutes,
   inferNavigationStructure,

package/src/import/extractors/api/generic-route-fallback.js

@@ -1,4 +1,4 @@
-import { findImportFiles, inferRouteAuthHint, inferRouteCapabilityId, inferRouteQueryParams, makeCandidateRecord, normalizeOpenApiPath, relativeTo } from "../../core/shared.js";
+import { findImportFiles, inferRouteAuthHint, inferRouteCapabilityId, inferRouteQueryParams, isPrimaryImportSource, makeCandidateRecord, normalizeOpenApiPath, relativeTo } from "../../core/shared.js";
 
 function extractHandlerContext(text, handlerName) {
   if (!handlerName) return "";
@@ -19,6 +19,7 @@ function inferServerRoutes(context) {
     context.paths,
     (filePath) =>
       /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(filePath) &&
+      isPrimaryImportSource(context.paths, filePath) &&
       /(server|api|routes|src)/i.test(filePath)
   );
   for (const filePath of routeFiles) {

package/src/import/extractors/api/openapi.js

@@ -1,4 +1,4 @@
-import { findImportFiles, makeCandidateRecord, normalizeOpenApiPath, relativeTo, selectPreferredImportFiles, slugify, titleCase } from "../../core/shared.js";
+import { findImportFiles, isPrimaryImportSource, makeCandidateRecord, normalizeOpenApiPath, relativeTo, selectPreferredImportFiles, slugify, titleCase } from "../../core/shared.js";
 
 function openApiRefName(ref) {
   return typeof ref === "string" ? ref.split("/").pop() || null : null;
@@ -196,7 +196,7 @@ export const openApiExtractor = {
   detect(context) {
     const files = selectPreferredImportFiles(
       context.paths,
-      findImportFiles(context.paths, (filePath) => /(openapi|swagger)\.(json|ya?ml)$/i.test(filePath)),
+      findImportFiles(context.paths, (filePath) => /(openapi|swagger)\.(json|ya?ml)$/i.test(filePath) && isPrimaryImportSource(context.paths, filePath)),
       "openapi"
     );
     return {
@@ -207,7 +207,7 @@ export const openApiExtractor = {
   extract(context) {
     const openApiFiles = selectPreferredImportFiles(
       context.paths,
-      findImportFiles(context.paths, (filePath) => /(openapi|swagger)\.(json|ya?ml)$/i.test(filePath)),
+      findImportFiles(context.paths, (filePath) => /(openapi|swagger)\.(json|ya?ml)$/i.test(filePath) && isPrimaryImportSource(context.paths, filePath)),
       "openapi"
     );
     const findings = [];

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

@@ -5,6 +5,7 @@ import path from "node:path";
 import {
   findImportFiles,
   idHintify,
+  isPrimaryImportSource,
   makeCandidateRecord,
   normalizeImportRelativePath,
   readJsonIfExists,
@@ -33,7 +34,7 @@ function normalizePath(value) {
  */
 function isAuthoritativeCliSource(paths, filePath) {
   const normalized = normalizePath(normalizeImportRelativePath(paths, filePath));
-  return !NON_AUTHORITATIVE_CLI_PATH_PATTERN.test(normalized);
+  return isPrimaryImportSource(paths, filePath) && !NON_AUTHORITATIVE_CLI_PATH_PATTERN.test(normalized);
 }
 
 /**

package/src/import/extractors/db/drizzle.js

@@ -5,11 +5,13 @@ import {
   dedupeCandidateRecords,
   findImportFiles,
   idHintify,
+  isPrimaryImportSource,
   makeCandidateRecord,
   relativeTo,
   slugify,
   titleCase
 } from "../../core/shared.js";
+import { inferDrizzleMaintainedDbSeams } from "./maintained-seams.js";
 
 function splitTopLevelEntries(block) {
   const entries = [];
@@ -165,21 +167,59 @@ function parseDrizzleTables(schemaText) {
   };
 }
 
+function drizzleConfigFiles(context) {
+  return findImportFiles(context.paths, (filePath) =>
+    /drizzle\.config\.(ts|js|mjs|cjs)$/i.test(path.basename(filePath)) &&
+    isPrimaryImportSource(context.paths, filePath)
+  );
+}
+
+function configuredSchemaFiles(context, configFiles) {
+  const files = [];
+  for (const configFile of configFiles) {
+    const configText = context.helpers.readTextIfExists(configFile) || "";
+    for (const match of configText.matchAll(/\bschema\s*:\s*["'`]([^"'`*]+)["'`]/g)) {
+      const absoluteSchemaPath = path.resolve(path.dirname(configFile), match[1]);
+      if (context.helpers.readTextIfExists(absoluteSchemaPath) !== null) {
+        files.push(absoluteSchemaPath);
+      }
+    }
+  }
+  return files;
+}
+
+function isDrizzleSchemaSource(context, filePath) {
+  const text = context.helpers.readTextIfExists(filePath) || "";
+  return /\b(?:pgTable|sqliteTable|mysqlTable)\s*\(/.test(text);
+}
+
+function findDrizzleSchemaFiles(context) {
+  const configFiles = drizzleConfigFiles(context);
+  const conventionalSchemaFiles = findImportFiles(context.paths, (filePath) =>
+    /(?:^|\/)(?:src\/db\/schema|src\/schema|db\/schema|schema)\.(ts|js|mjs|cjs)$/i.test(relativeTo(context.paths.workspaceRoot, filePath).replaceAll(path.sep, "/")) &&
+    isPrimaryImportSource(context.paths, filePath)
+  );
+  return [...new Set([
+    ...configuredSchemaFiles(context, configFiles),
+    ...conventionalSchemaFiles
+  ])].filter((filePath) => isDrizzleSchemaSource(context, filePath)).sort();
+}
+
 export const drizzleExtractor = {
   id: "db.drizzle",
   track: "db",
   detect(context) {
-    const hasConfig = findImportFiles(context.paths, (filePath) => /drizzle\.config\.(ts|js|mjs|cjs)$/i.test(path.basename(filePath))).length > 0;
-    const hasSchema = findImportFiles(context.paths, (filePath) => /src\/schema\.(ts|js|mjs|cjs)$/i.test(filePath)).length > 0;
+    const hasConfig = drizzleConfigFiles(context).length > 0;
+    const hasSchema = findDrizzleSchemaFiles(context).length > 0;
     return {
       score: hasConfig || hasSchema ? 95 : 0,
       reasons: hasConfig || hasSchema ? ["Found Drizzle config/schema source"] : []
     };
   },
   extract(context) {
-    const schemaFiles = findImportFiles(context.paths, (filePath) => /src\/schema\.(ts|js|mjs|cjs)$/i.test(filePath));
+    const schemaFiles = findDrizzleSchemaFiles(context);
     const findings = [];
-    const candidates = { entities: [], enums: [], relations: [], indexes: [] };
+    const candidates = { entities: [], enums: [], relations: [], indexes: [], maintained_seams: [] };
     for (const filePath of schemaFiles) {
       const parsed = parseDrizzleTables(context.helpers.readTextIfExists(filePath) || "");
       const provenance = relativeTo(context.paths.repoRoot, filePath);
@@ -237,6 +277,7 @@ export const drizzleExtractor = {
     candidates.enums = dedupeCandidateRecords(candidates.enums, (record) => record.id_hint);
     candidates.relations = dedupeCandidateRecords(candidates.relations, (record) => record.id_hint);
     candidates.indexes = dedupeCandidateRecords(candidates.indexes, (record) => record.id_hint);
+    candidates.maintained_seams = inferDrizzleMaintainedDbSeams(context, schemaFiles);
     return { findings, candidates };
   }
 };