@topogram/cli 0.3.76 → 0.3.78

package/src/import/extractors/ui/next-pages-router.js

@@ -2,10 +2,13 @@ import path from "node:path";
 
 import {
   dedupeCandidateRecords,
-  findImportFiles,
+  findPrimaryImportFiles,
+  inferNonResourceUiFlow,
   makeCandidateRecord,
+  proposedUiContractAdditionsForFlow,
   relativeTo,
   titleCase,
+  uiFlowIdForRoute,
   idHintify
 } from "../../core/shared.js";
 
@@ -58,7 +61,7 @@ export const nextPagesRouterUiExtractor = {
   id: "ui.next-pages-router",
   track: "ui",
   detect(context) {
-    const pageFiles = findImportFiles(context.paths, (filePath) => /src\/pages\/.+\.(tsx|ts|jsx|js|mdx)$/i.test(filePath))
+    const pageFiles = findPrimaryImportFiles(context.paths, (filePath) => /src\/pages\/.+\.(tsx|ts|jsx|js|mdx)$/i.test(filePath))
       .filter((filePath) => !/\/api\//.test(filePath) && !/\/_(app|document|error)\./.test(filePath) && !/\/404\./.test(filePath));
     return {
       score: pageFiles.length > 0 ? 85 : 0,
@@ -67,10 +70,10 @@ export const nextPagesRouterUiExtractor = {
   },
   extract(context) {
     const pagesRoot = path.join(context.paths.workspaceRoot, "src", "pages");
-    const pageFiles = findImportFiles(context.paths, (filePath) => /src\/pages\/.+\.(tsx|ts|jsx|js|mdx)$/i.test(filePath))
+    const pageFiles = findPrimaryImportFiles(context.paths, (filePath) => /src\/pages\/.+\.(tsx|ts|jsx|js|mdx)$/i.test(filePath))
       .filter((filePath) => !/\/api\//.test(filePath) && !/\/_(app|document|error)\./.test(filePath) && !/\/404\./.test(filePath));
     const findings = [];
-    const candidates = { screens: [], routes: [], actions: [], stacks: [] };
+    const candidates = { screens: [], routes: [], actions: [], flows: [], stacks: [] };
     if (pageFiles.length > 0) {
       const routes = [];
       for (const filePath of pageFiles) {
@@ -78,6 +81,7 @@ export const nextPagesRouterUiExtractor = {
         const text = context.helpers.readTextIfExists(filePath) || "";
         const hooks = inferTrpcHooks(text);
         const screen = screenFromRouteAndHooks(routePath, hooks);
+        const flow = inferNonResourceUiFlow(routePath);
         const provenance = `${relativeTo(context.paths.repoRoot, filePath)}#${routePath}`;
         routes.push(routePath);
         candidates.screens.push(makeCandidateRecord({
@@ -88,11 +92,11 @@ export const nextPagesRouterUiExtractor = {
           sourceKind: "route_code",
           provenance,
           track: "ui",
-          entity_id: screen.entity,
-          concept_id: screen.concept,
-          screen_kind: screen.kind,
+          entity_id: flow ? null : screen.entity,
+          concept_id: flow?.concept_id || screen.concept,
+          screen_kind: flow ? "flow" : screen.kind,
           route_path: routePath,
-          capability_hints: hooks.map((hook) => capabilityHint(hook.router, hook.procedure))
+          capability_hints: flow ? [] : hooks.map((hook) => capabilityHint(hook.router, hook.procedure))
         }));
         candidates.routes.push(makeCandidateRecord({
           kind: "ui_route",
@@ -103,10 +107,29 @@ export const nextPagesRouterUiExtractor = {
           provenance,
           track: "ui",
           screen_id: screen.id,
-          entity_id: screen.entity,
-          concept_id: screen.concept,
+          entity_id: flow ? null : screen.entity,
+          concept_id: flow?.concept_id || screen.concept,
           path: routePath
         }));
+        if (flow) {
+          candidates.flows.push(makeCandidateRecord({
+            kind: "ui_flow",
+            idHint: uiFlowIdForRoute(routePath, screen.id),
+            label: `${titleCase(flow.flow_type)} Flow`,
+            confidence: flow.confidence,
+            sourceKind: "route_code",
+            sourceOfTruth: "candidate",
+            provenance,
+            track: "ui",
+            flow_type: flow.flow_type,
+            concept_id: flow.concept_id,
+            screen_ids: [screen.id],
+            route_paths: [routePath],
+            evidence: [provenance],
+            missing_decisions: flow.missing_decisions,
+            proposed_ui_contract_additions: proposedUiContractAdditionsForFlow(routePath, screen.id, "flow")
+          }));
+        }
         for (const hook of hooks.filter((hook) => hook.hook === "Mutation")) {
           const capability = capabilityHint(hook.router, hook.procedure);
           candidates.actions.push(makeCandidateRecord({
@@ -135,6 +158,7 @@ export const nextPagesRouterUiExtractor = {
     candidates.screens = dedupeCandidateRecords(candidates.screens, (record) => record.id_hint);
     candidates.routes = dedupeCandidateRecords(candidates.routes, (record) => record.id_hint);
     candidates.actions = dedupeCandidateRecords(candidates.actions, (record) => record.id_hint);
+    candidates.flows = dedupeCandidateRecords(candidates.flows, (record) => record.id_hint);
     candidates.stacks = [...new Set(candidates.stacks)].sort();
     return { findings, candidates };
   }

package/src/import/extractors/ui/razor-pages.js

@@ -1,7 +1,7 @@
 import {
   canonicalCandidateTerm,
   dedupeCandidateRecords,
-  findImportFiles,
+  findPrimaryImportFiles,
   idHintify,
   makeCandidateRecord,
   relativeTo,
@@ -81,7 +81,7 @@ export const razorPagesUiExtractor = {
   id: "ui.razor-pages",
   track: "ui",
   detect(context) {
-    const files = findImportFiles(context.paths, (filePath) => /\.cshtml$/i.test(filePath))
+    const files = findPrimaryImportFiles(context.paths, (filePath) => /\.cshtml$/i.test(filePath))
       .filter((filePath) => !shouldIgnoreFile(filePath));
     const score = files.length > 0 ? 84 : 0;
     return {
@@ -90,7 +90,7 @@ export const razorPagesUiExtractor = {
     };
   },
   extract(context) {
-    const files = findImportFiles(context.paths, (filePath) => /\.cshtml$/i.test(filePath))
+    const files = findPrimaryImportFiles(context.paths, (filePath) => /\.cshtml$/i.test(filePath))
       .filter((filePath) => !shouldIgnoreFile(filePath));
     const findings = [];
     const candidates = { screens: [], routes: [], actions: [], stacks: [] };

package/src/import/extractors/ui/react-native-screens.js

@@ -1,7 +1,7 @@
 import {
   canonicalCandidateTerm,
   dedupeCandidateRecords,
-  findImportFiles,
+  findPrimaryImportFiles,
   idHintify,
   makeCandidateRecord,
   relativeTo,
@@ -119,7 +119,7 @@ export const reactNativeScreensExtractor = {
   id: "ui.react-native-screens",
   track: "ui",
   detect(context) {
-    const files = findImportFiles(
+    const files = findPrimaryImportFiles(
       context.paths,
       (filePath) => /\/src\/.+\/presentation\/screens\/.+Screen\.tsx$/i.test(filePath)
     );
@@ -130,11 +130,11 @@ export const reactNativeScreensExtractor = {
     };
   },
   extract(context) {
-    const screenFiles = findImportFiles(
+    const screenFiles = findPrimaryImportFiles(
       context.paths,
       (filePath) => /\/src\/.+\/presentation\/screens\/.+Screen\.tsx$/i.test(filePath)
     );
-    const navigatorFile = findImportFiles(
+    const navigatorFile = findPrimaryImportFiles(
       context.paths,
       (filePath) => /\/src\/core\/presentation\/navigation\/RootNavigator\.tsx$/i.test(filePath)
     )[0];

package/src/import/extractors/ui/react-router.js

@@ -2,14 +2,17 @@ import {
   dedupeCandidateRecords,
   detectUiPresentationFeatures,
   entityIdForRoute,
+  inferNonResourceUiFlow,
   inferNavigationStructure,
   inferReactRoutes,
   makeCandidateRecord,
   navigationPatternsFromStructure,
+  proposedUiContractAdditionsForFlow,
   relativeTo,
   shellKindFromNavigation,
   screenIdForRoute,
   screenKindForRoute,
+  uiFlowIdForRoute,
   uiCapabilityHintsForRoute,
   titleCase,
   idHintify
@@ -29,7 +32,7 @@ export const reactRouterUiExtractor = {
   },
   extract(context) {
     const findings = [];
-    const candidates = { screens: [], routes: [], actions: [], stacks: [] };
+    const candidates = { screens: [], routes: [], actions: [], flows: [], stacks: [] };
     const roots = [
       path.join(context.paths.workspaceRoot, "apps", "web"),
       path.join(context.paths.workspaceRoot, "examples", "maintained", "proof-app")
@@ -75,16 +78,20 @@ export const reactRouterUiExtractor = {
       for (const routePath of routes) {
         const screenId = screenIdForRoute(routePath);
         const screenKind = screenKindForRoute(routePath);
-        const capabilityHints = uiCapabilityHintsForRoute(routePath);
+        const flow = inferNonResourceUiFlow(routePath);
+        const capabilityHints = flow ? { load: null, submit: null, primary_action: null } : uiCapabilityHintsForRoute(routePath);
+        const entityId = flow ? null : entityIdForRoute(routePath);
+        const routeProvenance = `${provenance}#${routePath}`;
         candidates.screens.push(makeCandidateRecord({
           kind: "screen",
           idHint: screenId,
           label: titleCase(screenId),
           confidence: "medium",
           sourceKind: "route_code",
-          provenance: `${provenance}#${routePath}`,
+          provenance: routeProvenance,
           track: "ui",
-          entity_id: entityIdForRoute(routePath),
+          entity_id: entityId,
+          concept_id: flow?.concept_id || entityId,
           screen_kind: screenKind,
           route_path: routePath,
           capability_hints: capabilityHints
@@ -95,12 +102,32 @@ export const reactRouterUiExtractor = {
           label: routePath,
           confidence: "medium",
           sourceKind: "route_code",
-          provenance: `${provenance}#${routePath}`,
+          provenance: routeProvenance,
           track: "ui",
           screen_id: screenId,
-          entity_id: entityIdForRoute(routePath),
+          entity_id: entityId,
+          concept_id: flow?.concept_id || entityId,
           path: routePath
         }));
+        if (flow) {
+          candidates.flows.push(makeCandidateRecord({
+            kind: "ui_flow",
+            idHint: uiFlowIdForRoute(routePath, screenId),
+            label: `${titleCase(flow.flow_type)} Flow`,
+            confidence: flow.confidence,
+            sourceKind: "route_code",
+            sourceOfTruth: "candidate",
+            provenance: routeProvenance,
+            track: "ui",
+            flow_type: flow.flow_type,
+            concept_id: flow.concept_id,
+            screen_ids: [screenId],
+            route_paths: [routePath],
+            evidence: [routeProvenance],
+            missing_decisions: flow.missing_decisions,
+            proposed_ui_contract_additions: proposedUiContractAdditionsForFlow(routePath, screenId, screenKind)
+          }));
+        }
         if (capabilityHints.primary_action) {
           candidates.actions.push(makeCandidateRecord({
             kind: "ui_action",
@@ -133,6 +160,7 @@ export const reactRouterUiExtractor = {
     candidates.screens = dedupeCandidateRecords(candidates.screens, (record) => record.id_hint);
     candidates.routes = dedupeCandidateRecords(candidates.routes, (record) => record.id_hint);
     candidates.actions = dedupeCandidateRecords(candidates.actions, (record) => record.id_hint);
+    candidates.flows = dedupeCandidateRecords(candidates.flows, (record) => record.id_hint);
     candidates.stacks = [...new Set(candidates.stacks)].sort();
     return { findings, candidates };
   }

package/src/import/extractors/ui/sveltekit.js

@@ -2,14 +2,17 @@ import {
   dedupeCandidateRecords,
   detectUiPresentationFeatures,
   entityIdForRoute,
+  inferNonResourceUiFlow,
   inferNavigationStructure,
   inferSvelteRoutes,
   makeCandidateRecord,
   navigationPatternsFromStructure,
+  proposedUiContractAdditionsForFlow,
   relativeTo,
   shellKindFromNavigation,
   screenIdForRoute,
   screenKindForRoute,
+  uiFlowIdForRoute,
   uiCapabilityHintsForRoute,
   titleCase
 } from "../../core/shared.js";
@@ -28,7 +31,7 @@ export const svelteKitUiExtractor = {
   },
   extract(context) {
     const findings = [];
-    const candidates = { screens: [], routes: [], actions: [], stacks: [] };
+    const candidates = { screens: [], routes: [], actions: [], flows: [], stacks: [] };
     const roots = [
       path.join(context.paths.workspaceRoot, "apps", "web-sveltekit"),
       path.join(context.paths.workspaceRoot, "apps", "local-stack", "web")
@@ -74,16 +77,20 @@ export const svelteKitUiExtractor = {
       for (const routePath of routes) {
         const screenId = screenIdForRoute(routePath);
         const screenKind = screenKindForRoute(routePath);
-        const capabilityHints = uiCapabilityHintsForRoute(routePath);
+        const flow = inferNonResourceUiFlow(routePath);
+        const capabilityHints = flow ? { load: null, submit: null, primary_action: null } : uiCapabilityHintsForRoute(routePath);
+        const entityId = flow ? null : entityIdForRoute(routePath);
+        const routeProvenance = `${provenance}#${routePath}`;
         candidates.screens.push(makeCandidateRecord({
           kind: "screen",
           idHint: screenId,
           label: titleCase(screenId),
           confidence: "medium",
           sourceKind: "route_code",
-          provenance: `${provenance}#${routePath}`,
+          provenance: routeProvenance,
           track: "ui",
-          entity_id: entityIdForRoute(routePath),
+          entity_id: entityId,
+          concept_id: flow?.concept_id || entityId,
           screen_kind: screenKind,
           route_path: routePath,
           capability_hints: capabilityHints
@@ -94,12 +101,32 @@ export const svelteKitUiExtractor = {
           label: routePath,
           confidence: "medium",
           sourceKind: "route_code",
-          provenance: `${provenance}#${routePath}`,
+          provenance: routeProvenance,
           track: "ui",
           screen_id: screenId,
-          entity_id: entityIdForRoute(routePath),
+          entity_id: entityId,
+          concept_id: flow?.concept_id || entityId,
           path: routePath
         }));
+        if (flow) {
+          candidates.flows.push(makeCandidateRecord({
+            kind: "ui_flow",
+            idHint: uiFlowIdForRoute(routePath, screenId),
+            label: `${titleCase(flow.flow_type)} Flow`,
+            confidence: flow.confidence,
+            sourceKind: "route_code",
+            sourceOfTruth: "candidate",
+            provenance: routeProvenance,
+            track: "ui",
+            flow_type: flow.flow_type,
+            concept_id: flow.concept_id,
+            screen_ids: [screenId],
+            route_paths: [routePath],
+            evidence: [routeProvenance],
+            missing_decisions: flow.missing_decisions,
+            proposed_ui_contract_additions: proposedUiContractAdditionsForFlow(routePath, screenId, screenKind)
+          }));
+        }
       }
       for (const feature of features) {
         candidates.actions.push(makeCandidateRecord({
@@ -117,6 +144,7 @@ export const svelteKitUiExtractor = {
     candidates.screens = dedupeCandidateRecords(candidates.screens, (record) => record.id_hint);
     candidates.routes = dedupeCandidateRecords(candidates.routes, (record) => record.id_hint);
     candidates.actions = dedupeCandidateRecords(candidates.actions, (record) => record.id_hint);
+    candidates.flows = dedupeCandidateRecords(candidates.flows, (record) => record.id_hint);
     candidates.stacks = [...new Set(candidates.stacks)].sort();
     return { findings, candidates };
   }

package/src/import/extractors/ui/swiftui.js

@@ -1,8 +1,9 @@
 import {
   canonicalCandidateTerm,
   dedupeCandidateRecords,
-  findImportFiles,
+  findPrimaryImportFiles,
   idHintify,
+  isPrimaryImportSource,
   makeCandidateRecord,
   relativeTo,
   titleCase
@@ -117,7 +118,7 @@ export const swiftUiExtractor = {
   id: "ui.swiftui",
   track: "ui",
   detect(context) {
-    const files = findImportFiles(context.paths, (filePath) => /\.swift$/i.test(filePath))
+    const files = findPrimaryImportFiles(context.paths, (filePath) => /\.swift$/i.test(filePath) && isPrimaryImportSource(context.paths, filePath))
       .filter((filePath) => /:\s*View\b/.test(context.helpers.readTextIfExists(filePath) || ""));
     return {
       score: files.length > 0 ? 84 : 0,
@@ -125,7 +126,7 @@ export const swiftUiExtractor = {
     };
   },
   extract(context) {
-    const files = findImportFiles(context.paths, (filePath) => /\.swift$/i.test(filePath))
+    const files = findPrimaryImportFiles(context.paths, (filePath) => /\.swift$/i.test(filePath) && isPrimaryImportSource(context.paths, filePath))
       .filter((filePath) => /:\s*View\b/.test(context.helpers.readTextIfExists(filePath) || ""));
     const findings = [];
     const candidates = { screens: [], routes: [], actions: [], stacks: [] };

package/src/import/extractors/ui/uikit.js

@@ -1,7 +1,7 @@
 import {
   canonicalCandidateTerm,
   dedupeCandidateRecords,
-  findImportFiles,
+  findPrimaryImportFiles,
   idHintify,
   makeCandidateRecord,
   relativeTo,
@@ -64,7 +64,7 @@ export const uiKitExtractor = {
   id: "ui.uikit",
   track: "ui",
   detect(context) {
-    const controllerFiles = findImportFiles(context.paths, (filePath) => /\.swift$/i.test(filePath))
+    const controllerFiles = findPrimaryImportFiles(context.paths, (filePath) => /\.swift$/i.test(filePath))
       .filter((filePath) => !shouldIgnoreFile(filePath))
       .filter((filePath) => /(UIViewController|UITableViewController|UICollectionViewController)/.test(context.helpers.readTextIfExists(filePath) || ""));
     return {
@@ -73,7 +73,7 @@ export const uiKitExtractor = {
     };
   },
   extract(context) {
-    const controllerFiles = findImportFiles(context.paths, (filePath) => /\.swift$/i.test(filePath))
+    const controllerFiles = findPrimaryImportFiles(context.paths, (filePath) => /\.swift$/i.test(filePath))
       .filter((filePath) => !shouldIgnoreFile(filePath))
       .filter((filePath) => /(UIViewController|UITableViewController|UICollectionViewController)/.test(context.helpers.readTextIfExists(filePath) || ""));
     const findings = [];

package/src/workflows/reconcile/bundle-core/index.js

@@ -39,6 +39,7 @@ export function getOrCreateCandidateBundle(bundles, conceptId, label) {
       screens: [],
       uiRoutes: [],
       uiActions: [],
+      uiFlows: [],
       workflows: [],
       verifications: [],
       workflowStates: [],
@@ -337,6 +338,7 @@ export function renderCandidateBundleReadme(bundle, proposalSurfaces = []) {
     `Screens: ${bundle.screens.length}`,
     `UI routes: ${bundle.uiRoutes.length}`,
     `UI actions: ${bundle.uiActions.length}`,
+    `UI flows: ${(bundle.uiFlows || []).length}`,
     `Workflows: ${bundle.workflows.length}`,
     `Verifications: ${bundle.verifications.length}`,
     `Workflow states: ${bundle.workflowStates.length}`,
@@ -455,6 +457,16 @@ export function renderCandidateBundleReadme(bundle, proposalSurfaces = []) {
         lines.push(`    - label ${candidate.label}`);
         lines.push(`    - kind ${candidate.kind}`);
         lines.push(`    - why matched ${candidate.match_reasons.length ? candidate.match_reasons.join("; ") : "dependency overlap with maintained seam evidence"}`);
+        lines.push(`    - missing decisions ${(candidate.missing_decisions || []).length ? candidate.missing_decisions.join("; ") : "none"}`);
+        lines.push(`    - project config target \`${candidate.project_config_target?.path || "topology.runtimes[].migration"}\``);
+        lines.push(`    - evidence ${(candidate.evidence || []).slice(0, 3).map((/** @type {string} */ item) => `\`${item}\``).join(", ") || "_none_"}`);
+        lines.push("    - proposed runtime migration");
+        lines.push("      ```json");
+        lines.push(`      ${JSON.stringify(candidate.proposed_runtime_migration || {}, null, 2).replace(/\n/g, "\n      ")}`);
+        lines.push("      ```");
+        for (const step of candidate.manual_next_steps || []) {
+          lines.push(`    - manual next: ${step}`);
+        }
       }
     }
   }
@@ -554,6 +566,13 @@ export function renderCandidateBundleReadme(bundle, proposalSurfaces = []) {
       lines.push(`- \`${entry.id_hint}\` ${entry.screen_kind} at \`${entry.route_path}\``);
     }
   }
+  if ((bundle.uiFlows || []).length > 0) {
+    lines.push("", "## UI Flow Evidence", "");
+    for (const entry of bundle.uiFlows) {
+      lines.push(`- \`${entry.id_hint}\` ${entry.flow_type || "flow"} routes ${(entry.route_paths || []).map((/** @type {string} */ item) => `\`${item}\``).join(", ") || "_none_"}`);
+      lines.push(`  - missing decisions ${(entry.missing_decisions || []).length ? entry.missing_decisions.join("; ") : "none"}`);
+    }
+  }
   if (bundle.workflows.length > 0) {
     lines.push("", "## Workflow Evidence", "");
     for (const entry of bundle.workflows) {
@@ -578,7 +597,7 @@ export function renderMaintainedSeamCandidatesInline(bundle) {
   return entries
     .map((/** @type {any} */ surface) => {
       const seams = (surface.maintained_seam_candidates || [])
-        .map((/** @type {any} */ candidate) => `\`${candidate.seam_id}\` (${candidate.status}, ${candidate.ownership_class}, confidence=${candidate.confidence})`)
+        .map((/** @type {any} */ candidate) => `\`${candidate.seam_id}\` (${candidate.status}, ${candidate.ownership_class}, confidence=${candidate.confidence}, missing decisions=${(candidate.missing_decisions || []).length})`)
         .join(", ");
       return `${surface.id}: ${seams}`;
     })

package/src/workflows/reconcile/candidate-model.js

@@ -22,6 +22,7 @@ import {
   renderCandidateEntity,
   renderCandidateEnum,
   renderCandidateShape,
+  renderCandidateUiFlowDoc,
   renderCandidateUiReportDoc,
   renderCandidateVerification,
   renderCandidateWidget,
@@ -83,8 +84,9 @@ export function bestContextBundleForCandidate(bundles, candidate) {
 export function buildCandidateModelBundles(graph, appImport, topogramRoot) {
   const dbCandidates = appImport.candidates.db || { entities: [], enums: [], maintained_seams: [] };
   const apiCandidates = appImport.candidates.api || { capabilities: [] };
-  const uiCandidates = appImport.candidates.ui || { screens: [], routes: [], actions: [], widgets: [], shapes: [] };
+  const uiCandidates = appImport.candidates.ui || { screens: [], routes: [], actions: [], flows: [], widgets: [], shapes: [] };
   const uiWidgetCandidates = uiCandidates.widgets || uiCandidates.components || [];
+  const uiFlowCandidates = uiCandidates.flows || [];
   const uiShapeCandidates = uiCandidates.shapes || [];
   const uiShapeCandidatesById = new Map(uiShapeCandidates.map((/** @type {any} */ shape) => [shape.id || shape.id_hint, shape]));
   const workflowCandidates = appImport.candidates.workflows || { workflows: [], workflow_states: [], workflow_transitions: [] };
@@ -209,6 +211,11 @@ export function buildCandidateModelBundles(graph, appImport, topogramRoot) {
     const bundle = getOrCreateCandidateBundle(bundles, conceptId, bundleLabelFromConceptId(conceptId || entry.screen_id || entry.id_hint));
     bundle.uiActions.push(entry);
   }
+  for (const entry of uiFlowCandidates) {
+    const conceptId = entry.concept_id || `flow_${canonicalCandidateTerm(entry.flow_type || entry.id_hint)}`;
+    const bundle = getOrCreateCandidateBundle(bundles, conceptId, bundleLabelFromConceptId(conceptId || entry.id_hint));
+    bundle.uiFlows.push(entry);
+  }
   /** @param {WorkflowRecord} entry @returns {any} */
   function widgetConceptId(entry) {
     if (entry.entity_id || entry.concept_id) {
@@ -334,6 +341,7 @@ export function buildCandidateModelBundles(graph, appImport, topogramRoot) {
       bundle.screens.length > 0 ||
       bundle.uiRoutes.length > 0 ||
       bundle.uiActions.length > 0 ||
+      bundle.uiFlows.length > 0 ||
       bundle.workflows.length > 0 ||
       bundle.verifications.length > 0 ||
       bundle.workflowStates.length > 0 ||
@@ -354,6 +362,7 @@ export function buildCandidateModelBundles(graph, appImport, topogramRoot) {
         screens: bundle.screens.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
         uiRoutes: bundle.uiRoutes.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
         uiActions: bundle.uiActions.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
+        uiFlows: bundle.uiFlows.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
         workflows: bundle.workflows.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
         verifications: bundle.verifications.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
         workflowStates: bundle.workflowStates.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
@@ -499,6 +508,9 @@ export function buildCandidateModelFiles(graph, appImport, topogramRoot) {
       const actions = bundle.uiActions.filter((/** @type {any} */ action) => action.screen_id === screen.id_hint);
       files[`${bundleRoot}/docs/reports/ui-${screen.id_hint}.md`] = renderCandidateUiReportDoc(screen, routes, actions);
     }
+    for (const flow of bundle.uiFlows || []) {
+      files[`${bundleRoot}/docs/reports/ui-flow-${flow.id_hint}.md`] = renderCandidateUiFlowDoc(flow);
+    }
     for (const patch of bundle.projectionPatches || []) {
       files[`${bundleRoot}/${patch.patch_rel_path}`] = renderProjectionPatchDoc(patch);
     }

package/src/workflows/reconcile/impacts/adoption-plan.js

@@ -156,6 +156,19 @@ export function buildBundleAdoptionPlan(bundle, canonicalShapeIndex) {
       canonical_rel_path: `docs/reports/ui-${screen.id_hint}.md`
     });
   }
+  for (const flow of bundle.uiFlows || []) {
+    steps.push({
+      action: "promote_ui_flow_report",
+      item: `ui_flow_${flow.id_hint}`,
+      target: null,
+      confidence: flow.confidence || "medium",
+      inference_summary: `Review non-resource UI flow candidate ${flow.id_hint}.`,
+      source_kind: flow.source_kind || "route_code",
+      source_path: `candidates/reconcile/model/bundles/${bundle.slug}/docs/reports/ui-flow-${flow.id_hint}.md`,
+      canonical_rel_path: `docs/reports/ui-flow-${flow.id_hint}.md`,
+      track: "ui"
+    });
+  }
   for (const patch of bundle.projectionPatches || []) {
     for (const hint of patch.missing_auth_permissions || []) {
       steps.push({

package/src/workflows/reconcile/renderers.js

@@ -283,6 +283,39 @@ export function renderCandidateUiReportDoc(screen, routes, actions) {
   return renderMarkdownDoc(metadata, body);
 }
 
+/** @param {WorkflowRecord} flow @returns {any} */
+export function renderCandidateUiFlowDoc(flow) {
+  /** @type {WorkflowRecord} */
+  const metadata = {
+    id: `ui_flow_${flow.id_hint}`,
+    kind: "report",
+    title: `${flow.label || flow.id_hint} Review`,
+    status: "inferred",
+    source_of_truth: "imported",
+    confidence: flow.confidence || "medium",
+    review_required: true,
+    provenance: flow.provenance || flow.evidence || [],
+    tags: ["import", "ui", "flow"]
+  };
+  const body = [
+    "Candidate non-resource UI flow imported from brownfield route evidence.",
+    "",
+    `Flow: \`${flow.id_hint}\` (${flow.flow_type || "unknown"})`,
+    `Screens: ${(flow.screen_ids || []).map((/** @type {string} */ item) => `\`${item}\``).join(", ") || "_none_"}`,
+    `Routes: ${(flow.route_paths || []).map((/** @type {string} */ item) => `\`${item}\``).join(", ") || "_none_"}`,
+    `Missing decisions: ${(flow.missing_decisions || []).length ? flow.missing_decisions.join("; ") : "none"}`,
+    "",
+    "Proposed UI contract additions:",
+    "",
+    "```json",
+    JSON.stringify(flow.proposed_ui_contract_additions || {}, null, 2),
+    "```",
+    "",
+    "Review this flow before promoting it into shared UI contract behavior."
+  ].join("\n");
+  return renderMarkdownDoc(metadata, body);
+}
+
 /** @param {WorkflowRecord} widget @returns {any} */
 export function renderCandidateWidget(widget) {
   const propName = widget.data_prop || "rows";

package/src/workflows/reconcile/workflow.js

@@ -262,6 +262,7 @@ export function reconcileWorkflow(inputPath, options = {}) {
       widgets: bundle.widgets.map((/** @type {any} */ entry) => entry.id_hint),
       cli_surfaces: (bundle.cliSurfaces || []).map((/** @type {any} */ entry) => entry.id_hint),
       screens: bundle.screens.map((/** @type {any} */ entry) => entry.id_hint),
+      ui_flows: (bundle.uiFlows || []).map((/** @type {any} */ entry) => entry.id_hint),
       workflows: bundle.workflows.map((/** @type {any} */ entry) => entry.id_hint),
       docs: bundle.docs.map((/** @type {any} */ entry) => entry.id),
       maintained_seam_candidates: (agentAdoptionPlan.imported_proposal_surfaces || [])
@@ -284,7 +285,7 @@ export function reconcileWorkflow(inputPath, options = {}) {
     : "## Promoted Canonical Items";
   files["candidates/reconcile/report.json"] = `${stableStringify(report)}\n`;
   const candidateModelBundlesMarkdown = report.candidate_model_bundles.length
-    ? report.candidate_model_bundles.map((/** @type {any} */ bundle) => `- \`${bundle.slug}\` (${bundle.actors.length} actors, ${bundle.roles.length} roles, ${bundle.entities.length} entities, ${bundle.enums.length} enums, ${bundle.capabilities.length} capabilities, ${bundle.shapes.length} shapes, ${bundle.widgets.length} widgets, ${bundle.cli_surfaces.length} CLI surfaces, ${bundle.screens.length} screens, ${bundle.workflows.length} workflows, ${bundle.docs.length} docs)
+    ? report.candidate_model_bundles.map((/** @type {any} */ bundle) => `- \`${bundle.slug}\` (${bundle.actors.length} actors, ${bundle.roles.length} roles, ${bundle.entities.length} entities, ${bundle.enums.length} enums, ${bundle.capabilities.length} capabilities, ${bundle.shapes.length} shapes, ${bundle.widgets.length} widgets, ${bundle.cli_surfaces.length} CLI surfaces, ${bundle.screens.length} screens, ${(bundle.ui_flows || []).length} UI flows, ${bundle.workflows.length} workflows, ${bundle.docs.length} docs)
   - primary concept \`${bundle.operator_summary.primaryConcept}\`${bundle.operator_summary.primaryEntityId ? `, primary entity \`${bundle.operator_summary.primaryEntityId}\`` : ""}
   - participants ${bundle.operator_summary.participants.label}
   - main capabilities ${summarizeBundleSurface(bundle, bundle.operator_summary.capabilityIds)}