@akanjs/devkit 2.3.9-rc.7 → 2.3.9-rc.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.3.9-rc.7",
+  "version": "2.3.9-rc.9",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -32,7 +32,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.9-rc.7",
+    "akanjs": "2.3.9-rc.9",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/workflow/artifacts.ts

@@ -7,9 +7,12 @@ import type {
   RepairReport,
   WorkflowApplyCommand,
   WorkflowApplyReport,
+  WorkflowBaselineSummary,
   WorkflowDiagnostic,
   WorkflowFailureScope,
   WorkflowKnownBlocker,
+  WorkflowNextActionCode,
+  WorkflowOverallStatus,
   WorkflowPlan,
   WorkflowRunArtifact,
   WorkflowRunSource,
@@ -19,6 +22,43 @@ import type {
 } from "./types";
 import { commandStatus, jsonText, uniqueBy, workflowStatus } from "./utils";
 
+const sourceChangeBlocked = (diagnostics: readonly WorkflowDiagnostic[]) =>
+  diagnostics.some(
+    (diagnostic) =>
+      diagnostic.severity === "error" &&
+      (diagnostic.failureScope === "source-change" ||
+        !diagnostic.failureScope ||
+        diagnostic.failureScope === "unknown"),
+  );
+
+export const workflowPlanApproval = {
+  required: true,
+  meaning: "Review this read-only plan before apply_workflow mutates files.",
+  applyTool: "apply_workflow",
+} as const;
+
+const inferNextActionCode = (
+  action: { action?: WorkflowNextActionCode; command: string },
+  diagnostics: readonly WorkflowDiagnostic[],
+): WorkflowNextActionCode => {
+  if (action.action) return action.action;
+  if (sourceChangeBlocked(diagnostics) && action.command.startsWith("akan workflow explain")) return "blocked";
+  if (action.command.startsWith("akan workflow repair")) return "repair";
+  if (action.command.startsWith("akan workflow explain")) return "manual-review";
+  if (action.command.startsWith("akan ")) return "validate";
+  return "answer";
+};
+
+const nextActionPriority = (
+  action: { action?: WorkflowNextActionCode },
+  diagnostics: readonly WorkflowDiagnostic[],
+) => {
+  const priority = sourceChangeBlocked(diagnostics)
+    ? { blocked: 0, repair: 1, "manual-review": 2, validate: 3, answer: 4 }
+    : { "manual-review": 0, validate: 1, repair: 2, blocked: 3, answer: 4 };
+  return priority[action.action ?? "answer"];
+};
+
 export const createWorkflowApplyReport = ({
   workflow,
   mode,
@@ -39,6 +79,7 @@ export const createWorkflowApplyReport = ({
   | "applyReportPath"
   | "validationTarget"
   | "status"
+  | "summary"
   | "appliedCommands"
   | "recommendedValidationCommands"
   | "commands"
@@ -52,18 +93,33 @@ export const createWorkflowApplyReport = ({
   recommendations?: WorkflowApplyReport["recommendations"];
 }): WorkflowApplyReport => {
   const validationCommands = recommendedValidationCommands ?? commands;
-  const orderedNextActions = uniqueBy(nextActions, (action) => action.command).sort((left, right) => {
-    const leftRepair = left.command.startsWith("akan workflow explain") ? 0 : 1;
-    const rightRepair = right.command.startsWith("akan workflow explain") ? 0 : 1;
-    return leftRepair - rightRepair;
-  });
+  const nextActionsWithIntent = nextActions.map((action) => ({
+    ...action,
+    action: inferNextActionCode(action, diagnostics),
+  }));
+  if (sourceChangeBlocked(diagnostics) && !nextActionsWithIntent.some((action) => action.action === "blocked")) {
+    nextActionsWithIntent.unshift({
+      command: `akan workflow explain ${workflow}`,
+      reason: "Review source-change blockers before running validation.",
+      action: "blocked",
+    });
+  }
+  const orderedNextActions = uniqueBy(nextActionsWithIntent, (action) => action.command).sort(
+    (left, right) => nextActionPriority(left, diagnostics) - nextActionPriority(right, diagnostics),
+  );
+  const sourceFilesChanged = uniqueBy(changedFiles, (file) => `${file.action}:${file.path}:${file.reason}`);
+  const generatedFilesSynced = uniqueBy(generatedFiles, (file) => `${file.action}:${file.path}:${file.reason}`);
   return {
     schemaVersion: 1,
     workflow,
     mode,
     status: workflowStatus(diagnostics),
-    changedFiles: uniqueBy(changedFiles, (file) => `${file.action}:${file.path}:${file.reason}`),
-    generatedFiles: uniqueBy(generatedFiles, (file) => `${file.action}:${file.path}:${file.reason}`),
+    summary: {
+      sourceFilesChanged,
+      generatedFilesSynced,
+    },
+    changedFiles: sourceFilesChanged,
+    generatedFiles: generatedFilesSynced,
     appliedCommands: uniqueBy(appliedCommands, (command) => command.command),
     recommendedValidationCommands: uniqueBy(validationCommands, (command) => command.command),
     commands: uniqueBy(validationCommands, (command) => command.command),
@@ -204,6 +260,58 @@ const statusForValidationKind = (
   return matching.some((command) => command.status === "failed") ? "failed" : "passed";
 };
 
+const statusForCommands = (commands: readonly WorkflowValidationCommandResult[]): WorkflowValidationStatus => {
+  if (commands.length === 0) return "unknown";
+  return commandStatus(commands) === "failed" ? "failed" : "passed";
+};
+
+const statusForDiagnostics = (diagnostics: readonly WorkflowDiagnostic[]): WorkflowValidationStatus => {
+  if (diagnostics.length === 0) return "unknown";
+  return workflowStatus(diagnostics) === "failed" ? "failed" : "passed";
+};
+
+const workflowDiagnosticContextPaths = (diagnostics: readonly WorkflowDiagnostic[]) =>
+  uniqueBy(
+    diagnostics.flatMap((diagnostic) => diagnostic.context?.paths ?? []),
+    (filePath) => filePath,
+  );
+
+export const createWorkflowBaselineSummary = (
+  diagnostics: readonly WorkflowDiagnostic[],
+  { detailsIncluded = true, knownBlockerCount = 0 }: { detailsIncluded?: boolean; knownBlockerCount?: number } = {},
+): WorkflowBaselineSummary => {
+  const grouped = new Map<string, WorkflowBaselineSummary["byCode"][number]>();
+  let totalErrors = 0;
+  let totalWarnings = 0;
+  for (const diagnostic of diagnostics) {
+    if (diagnostic.severity === "error") totalErrors += 1;
+    else totalWarnings += 1;
+    const existing = grouped.get(diagnostic.code);
+    if (existing) {
+      existing.count += 1;
+      if (existing.severity !== diagnostic.severity) existing.severity = "mixed";
+    } else {
+      grouped.set(diagnostic.code, {
+        code: diagnostic.code,
+        severity: diagnostic.severity,
+        count: 1,
+        sampleMessage: diagnostic.message,
+      });
+    }
+  }
+  const contextPaths = workflowDiagnosticContextPaths(diagnostics);
+  return {
+    status: totalErrors > 0 ? "failed" : diagnostics.length > 0 ? "passed" : "unknown",
+    total: diagnostics.length,
+    totalErrors,
+    totalWarnings,
+    detailsIncluded,
+    knownBlockerCount,
+    byCode: [...grouped.values()],
+    ...(contextPaths.length ? { contextPaths } : {}),
+  };
+};
+
 const createKnownBlockers = (
   commands: readonly WorkflowValidationCommandResult[],
   diagnostics: readonly WorkflowDiagnostic[],
@@ -250,10 +358,37 @@ const createKnownBlockers = (
 
 const createValidationStatuses = (
   commands: readonly WorkflowValidationCommandResult[],
-  diagnostics: readonly WorkflowDiagnostic[],
-) => {
+  reportDiagnostics: readonly WorkflowDiagnostic[],
+  baselineDiagnostics: readonly WorkflowDiagnostic[],
+  workflowDiagnostics: readonly WorkflowDiagnostic[],
+): {
+  sourceStatus: WorkflowValidationStatus;
+  workspaceStatus: WorkflowValidationStatus;
+  validationCommandsStatus: WorkflowValidationStatus;
+  baselineStatus: WorkflowValidationStatus;
+  overallStatus: WorkflowOverallStatus;
+  summary: {
+    sourceChange: WorkflowValidationStatus;
+    generatedSync: WorkflowValidationStatus;
+    validationCommands: WorkflowValidationStatus;
+    baseline: WorkflowValidationStatus;
+    workspaceConfig: WorkflowValidationStatus;
+    environment: WorkflowValidationStatus;
+  };
+} => {
+  const diagnostics = [...reportDiagnostics, ...baselineDiagnostics, ...workflowDiagnostics];
   const scopes = [...failedCommandScopes(commands), ...errorDiagnosticScopes(diagnostics)];
-  const sourceStatus = statusForScope(commands, diagnostics, scopes, "source-change");
+  const sourceDiagnostics = [...reportDiagnostics, ...workflowDiagnostics].filter(
+    (diagnostic) =>
+      diagnostic.failureScope === "source-change" ||
+      diagnostic.scope === "workflow" ||
+      (!diagnostic.failureScope && diagnostic.scope !== "baseline"),
+  );
+  const sourceScopes = [...failedCommandScopes(commands), ...errorDiagnosticScopes(sourceDiagnostics)];
+  const sourceStatus = statusForScope(commands, sourceDiagnostics, sourceScopes, "source-change");
+  const validationCommandsStatus = statusForCommands(commands);
+  const baselineStatus = statusForDiagnostics(baselineDiagnostics);
+  const nonBaselineDiagnostics = [...reportDiagnostics, ...workflowDiagnostics];
   const workspaceStatus =
     hasScopeFailure(scopes, "workspace-config", diagnostics) || hasScopeFailure(scopes, "environment", diagnostics)
       ? "failed"
@@ -262,20 +397,28 @@ const createValidationStatuses = (
         : "unknown";
   const overallStatus = hasScopeFailure(scopes, "source-change", diagnostics)
     ? "failed"
-    : hasScopeFailure(scopes, "workspace-config", diagnostics)
-      ? "blocked-by-workspace-config"
-      : hasScopeFailure(scopes, "environment", diagnostics)
-        ? "blocked-by-environment"
-        : workflowStatus(diagnostics) === "failed" || commandStatus(commands) === "failed"
-          ? "failed"
-          : "passed";
+    : validationCommandsStatus === "passed" &&
+        baselineStatus === "failed" &&
+        workflowStatus(nonBaselineDiagnostics) !== "failed"
+      ? "passed-with-baseline-blockers"
+      : hasScopeFailure(scopes, "workspace-config", diagnostics)
+        ? "blocked-by-workspace-config"
+        : hasScopeFailure(scopes, "environment", diagnostics)
+          ? "blocked-by-environment"
+          : workflowStatus(diagnostics) === "failed" || commandStatus(commands) === "failed"
+            ? "failed"
+            : "passed";
   return {
     sourceStatus,
     workspaceStatus,
+    validationCommandsStatus,
+    baselineStatus,
     overallStatus,
     summary: {
       sourceChange: sourceStatus,
       generatedSync: statusForValidationKind(commands, "sync"),
+      validationCommands: validationCommandsStatus,
+      baseline: baselineStatus,
       workspaceConfig: statusForScope(commands, diagnostics, scopes, "workspace-config"),
       environment: statusForScope(commands, diagnostics, scopes, "environment"),
     },
@@ -325,7 +468,8 @@ export const createWorkflowValidationRunReport = async ({
   );
   const reportDiagnostics = [...diagnostics, ...commandDiagnostics];
   const scopedDiagnostics = [...reportDiagnostics, ...baselineDiagnostics, ...workflowDiagnostics];
-  const statuses = createValidationStatuses(results, scopedDiagnostics);
+  const knownBlockers = createKnownBlockers(results, scopedDiagnostics);
+  const statuses = createValidationStatuses(results, reportDiagnostics, baselineDiagnostics, workflowDiagnostics);
   return {
     schemaVersion: 1,
     runId,
@@ -334,9 +478,12 @@ export const createWorkflowValidationRunReport = async ({
     source,
     status: statuses.overallStatus === "passed" ? "passed" : "failed",
     ...statuses,
-    knownBlockers: createKnownBlockers(results, scopedDiagnostics),
+    knownBlockers,
     commands: results,
     diagnostics: reportDiagnostics,
+    baselineSummary: createWorkflowBaselineSummary(baselineDiagnostics, {
+      knownBlockerCount: knownBlockers.filter((blocker) => blocker.failureScope === "workspace-config").length,
+    }),
     baselineDiagnostics,
     workflowDiagnostics,
     repairActions: uniqueBy(repairActions, (action) => action.command),

package/workflow/executor.ts

@@ -1,9 +1,17 @@
-import { capitalize } from "akanjs/common";
 import ts from "typescript";
+import type { AkanModuleContext } from "../akanContext";
 import type { Sys, Workspace } from "../commandDecorators";
 import { AppExecutor, LibExecutor } from "../executors";
 import { createWorkflowApplyReport, workflowCommandsForPlan } from "./artifacts";
-import { moduleSourcePaths } from "./source";
+import { buildAkanModuleContextIndex } from "./moduleIndex";
+import {
+  insertionIndexForFieldOrder,
+  inspectConstantStructure,
+  inspectDictionaryStructure,
+  moduleComponentName,
+  moduleSourcePaths,
+  normalizeFieldType,
+} from "./source";
 import type {
   PrimitiveChangedFile,
   PrimitiveGeneratedFile,
@@ -47,6 +55,14 @@ const postApplyDiagnostic = (code: string, message: string, target: string): Wor
   context: { target },
 });
 
+const postApplyWarning = (code: string, message: string, target: string): WorkflowDiagnostic => ({
+  severity: "warning",
+  code,
+  message,
+  failureScope: "source-change",
+  context: { target },
+});
+
 const sourceKindForPath = (filePath: string) => {
   if (filePath.endsWith(".tsx")) return ts.ScriptKind.TSX;
   if (filePath.endsWith(".ts")) return ts.ScriptKind.TS;
@@ -81,7 +97,8 @@ const checkTypeScriptSyntax = async (workspace: Workspace, filePath: string) =>
   if (!scriptKind) return null;
   const content = await workspace.readFile(filePath);
   const source = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, scriptKind);
-  const diagnostic = source.parseDiagnostics[0];
+  const diagnostic = ((source as ts.SourceFile & { parseDiagnostics?: readonly ts.DiagnosticWithLocation[] })
+    .parseDiagnostics ?? [])[0];
   if (!diagnostic) return null;
   const position = diagnostic.file?.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
   const location = position ? `:${position.line + 1}:${position.character + 1}` : "";
@@ -136,6 +153,188 @@ const checkRecommendationPath = async (
   };
 };
 
+const sourceChangeError = (diagnostics: readonly WorkflowDiagnostic[]) =>
+  diagnostics.some(
+    (diagnostic) =>
+      diagnostic.severity === "error" &&
+      (diagnostic.failureScope === "source-change" ||
+        !diagnostic.failureScope ||
+        diagnostic.failureScope === "unknown"),
+  );
+
+const fieldCount = (fields: readonly string[], fieldName: string) =>
+  fields.filter((field) => field === fieldName).length;
+
+const fieldOrderValid = (fields: readonly string[], fieldName: string) => {
+  const actualIndex = fields.indexOf(fieldName);
+  if (actualIndex < 0 || fields.lastIndexOf(fieldName) !== actualIndex) return false;
+  const fieldsWithoutRequested = fields.filter((_, index) => index !== actualIndex);
+  return insertionIndexForFieldOrder(fieldsWithoutRequested, fieldName) === actualIndex;
+};
+
+const workflowModuleContext = async (workspace: Workspace, plan: WorkflowPlan): Promise<AkanModuleContext | null> => {
+  const app = workflowStringInput(plan.inputs.app);
+  const moduleName = workflowStringInput(plan.inputs.module);
+  if (!app || !moduleName) return null;
+  const [apps, libs] = await workspace.getSyss();
+  const sysType = apps.includes(app) ? "app" : libs.includes(app) ? "lib" : null;
+  if (!sysType) return null;
+  const modulePath = `${sysType}s/${app}/lib/${moduleName}`;
+  const files = await workspace.readdir(modulePath);
+  const abstractPath = `${modulePath}/${moduleName}.abstract.md`;
+  return {
+    kind: "domain",
+    name: moduleName,
+    folderName: moduleName,
+    sysName: app,
+    sysType,
+    path: modulePath,
+    abstract: {
+      path: abstractPath,
+      exists: files.includes(`${moduleName}.abstract.md`),
+      headings: [],
+    },
+    files,
+  };
+};
+
+const structureCheck = (
+  code: string,
+  target: string,
+  status: WorkflowPostApplyCheck["status"],
+  message: string,
+): WorkflowPostApplyCheck => ({
+  code,
+  target,
+  status,
+  message,
+});
+
+const checkAddFieldStructure = async (workspace: Workspace, plan: WorkflowPlan): Promise<WorkflowStepResult> => {
+  if (plan.workflow !== "add-field" && plan.workflow !== "add-enum-field") return {};
+  const app = workflowStringInput(plan.inputs.app);
+  const moduleName = workflowStringInput(plan.inputs.module);
+  const fieldName = workflowStringInput(plan.inputs.field);
+  const typeName = workflowStringInput(plan.inputs.type);
+  if (!app || !moduleName || !fieldName || !typeName) return {};
+
+  const moduleContext = await workflowModuleContext(workspace, plan);
+  if (!moduleContext) return {};
+
+  const paths = moduleSourcePaths(moduleName);
+  const constantPath = `${moduleContext.path}/${paths.constant.replace(`lib/${moduleName}/`, "")}`;
+  const dictionaryPath = `${moduleContext.path}/${paths.dictionary.replace(`lib/${moduleName}/`, "")}`;
+  const moduleClassName = moduleComponentName(moduleName);
+  const inputClassName = `${moduleClassName}Input`;
+  const index = await buildAkanModuleContextIndex(workspace, moduleContext, { field: fieldName });
+  const diagnostics: WorkflowDiagnostic[] = [];
+  const postApplyChecks: WorkflowPostApplyCheck[] = [];
+
+  const constantContent = await workspace.readFile(constantPath);
+  const constantStructure = inspectConstantStructure(constantContent, inputClassName, moduleClassName);
+  const constantNames = constantStructure.fields.map((field) => field.name);
+  const requestedConstantFields = constantStructure.fields.filter((field) => field.name === fieldName);
+  const normalizedType = typeName.toLowerCase() === "enum" ? typeName : normalizeFieldType(typeName);
+  const constantFailures = [
+    !constantStructure.parseValid ? "constant file does not parse" : null,
+    !constantStructure.inputObjectFound ? `${inputClassName} via builder object was not found` : null,
+    requestedConstantFields.length !== 1
+      ? `field "${fieldName}" appears ${requestedConstantFields.length} time(s) in ${inputClassName}`
+      : null,
+    constantStructure.builderName &&
+    requestedConstantFields[0]?.expressionBuilder &&
+    requestedConstantFields[0].expressionBuilder !== constantStructure.builderName
+      ? `field "${fieldName}" uses builder "${requestedConstantFields[0].expressionBuilder}" instead of "${constantStructure.builderName}"`
+      : null,
+    !constantStructure.builderName ? `${inputClassName} via builder parameter was not found` : null,
+    (normalizedType === "Int" || normalizedType === "Float") && !constantStructure.baseImports.includes(normalizedType)
+      ? `missing ${normalizedType} import from "akanjs/base"`
+      : null,
+    workflowBooleanInput(plan.inputs.includeInLight) === true &&
+    fieldCount(constantStructure.lightProjectionFields, fieldName) !== 1
+      ? `field "${fieldName}" is not present exactly once in Light${moduleClassName}`
+      : null,
+    ...index.diagnostics
+      .filter((diagnostic) => diagnostic.severity === "error" && diagnostic.context?.paths?.includes(constantPath))
+      .map((diagnostic) => diagnostic.message),
+  ].filter((failure): failure is string => failure !== null);
+  const constantValid = constantFailures.length === 0;
+  postApplyChecks.push(
+    structureCheck(
+      constantValid ? "workflow-post-apply-constant-shape-valid" : "workflow-post-apply-structure-invalid",
+      constantPath,
+      constantValid ? "passed" : "failed",
+      constantValid
+        ? `${inputClassName} keeps via structure, builder usage, imports, and requested field presence.`
+        : constantFailures.join(" "),
+    ),
+  );
+  if (!constantValid) {
+    diagnostics.push(
+      postApplyDiagnostic("workflow-post-apply-structure-invalid", constantFailures.join(" "), constantPath),
+    );
+  }
+
+  const dictionaryContent = await workspace.readFile(dictionaryPath);
+  const dictionaryStructure = inspectDictionaryStructure(dictionaryContent, moduleClassName);
+  const dictionaryFailures = [
+    !dictionaryStructure.parseValid ? "dictionary file does not parse" : null,
+    !dictionaryStructure.modelObjectFound ? `.model<${moduleClassName}> object was not found` : null,
+    dictionaryStructure.modelObjectFound && !dictionaryStructure.chainOrderValid
+      ? `.model(), .slice(), .enum(), .error(), and .translate() chain order is broken: ${dictionaryStructure.chainMethods.join(
+          " -> ",
+        )}`
+      : null,
+    fieldCount(dictionaryStructure.fields, fieldName) !== 1
+      ? `field "${fieldName}" appears ${fieldCount(dictionaryStructure.fields, fieldName)} time(s) in .model<${moduleClassName}>`
+      : null,
+    ...index.diagnostics
+      .filter((diagnostic) => diagnostic.severity === "error" && diagnostic.context?.paths?.includes(dictionaryPath))
+      .map((diagnostic) => diagnostic.message),
+  ].filter((failure): failure is string => failure !== null);
+  const dictionaryValid = dictionaryFailures.length === 0;
+  postApplyChecks.push(
+    structureCheck(
+      dictionaryValid ? "workflow-post-apply-dictionary-shape-valid" : "workflow-post-apply-structure-invalid",
+      dictionaryPath,
+      dictionaryValid ? "passed" : "failed",
+      dictionaryValid
+        ? `.model<${moduleClassName}> keeps the requested field inside the model object and preserves dictionary chain order.`
+        : dictionaryFailures.join(" "),
+    ),
+  );
+  if (!dictionaryValid) {
+    diagnostics.push(
+      postApplyDiagnostic("workflow-post-apply-structure-invalid", dictionaryFailures.join(" "), dictionaryPath),
+    );
+  }
+
+  const constantOrderValid = fieldOrderValid(constantNames, fieldName);
+  const dictionaryOrderValid = fieldOrderValid(dictionaryStructure.fields, fieldName);
+  const orderValid = constantOrderValid && dictionaryOrderValid;
+  postApplyChecks.push(
+    structureCheck(
+      "workflow-post-apply-field-order-valid",
+      `${constantPath}, ${dictionaryPath}`,
+      orderValid ? "passed" : "failed",
+      orderValid
+        ? `Field "${fieldName}" follows the shared priority ordering policy.`
+        : `Field "${fieldName}" is present but does not match the shared priority ordering policy.`,
+    ),
+  );
+  if (!orderValid) {
+    diagnostics.push(
+      postApplyWarning(
+        "workflow-post-apply-field-order-mismatch",
+        `Field "${fieldName}" is present but does not match the shared priority ordering policy.`,
+        `${constantPath}, ${dictionaryPath}`,
+      ),
+    );
+  }
+
+  return { diagnostics, postApplyChecks };
+};
+
 const resolveWorkflowSys = async (workspace: Workspace, target: string | null): Promise<Sys | null> => {
   if (!target) return null;
   const [apps, libs] = await workspace.getSyss();
@@ -173,7 +372,7 @@ const addFieldUiSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult =>
   const policy = addFieldUiPolicyForType(typeName ?? "String");
   const surfaces = workflowStringArrayInput(plan.inputs.surfaces);
   const templateRequested = surfaces?.includes("template") ?? false;
-  const moduleClassName = capitalize(module);
+  const moduleClassName = moduleComponentName(module);
   const target = `${app ? `apps/${app}` : "*"}/${moduleSourcePaths(module).template}`;
   return {
     recommendations: [
@@ -182,10 +381,10 @@ const addFieldUiSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult =>
         kind: "manual-action",
         target,
         action: templateRequested
-          ? `Template was requested for ${field}. If no Template file changed, auto-edit was skipped because the file was missing, the generated ${module}Form/Layout.Template pattern was not found, or ${policy.component} needs option binding. Candidate position: inside Layout.Template near the existing Field components.`
-          : `Template was not selected, so UI files are intentionally left unchanged. Candidate positions if you expose it later: Layout.Template field list for editing, Light${moduleClassName} projection for list/card data, and Unit/View card sections for display.`,
+          ? `Template was requested for ${field}. If no Template file changed, users will not see the field in the form yet because the file was missing, the generated ${module}Form/Layout.Template pattern was not found, or ${policy.component} needs option binding. Add it inside Layout.Template near existing Field components.`
+          : `Template was not selected, so users will not see ${field} in the form from this apply. If list/card display is needed, include ${field} in Light${moduleClassName} projection data and place it in the local Unit/View card layout.`,
         confidence: "medium",
-        message: `Review UI surfaces for ${module}.${field}; recommended component is ${policy.component}, with manual reasons and candidate positions in action.`,
+        message: `Review user-visible UI for ${module}.${field}; recommended component is ${policy.component}.`,
       },
     ],
     nextActions: [
@@ -362,6 +561,11 @@ export class WorkflowExecutor {
         postApplyChecks.push(...(result.postApplyChecks ?? []));
         diagnostics.push(...(result.diagnostics ?? []));
       }
+      if (!sourceChangeError(diagnostics)) {
+        const result = await checkAddFieldStructure(this.workspace, plan);
+        postApplyChecks.push(...(result.postApplyChecks ?? []));
+        diagnostics.push(...(result.diagnostics ?? []));
+      }
       const recommendationDiagnostics = await Promise.all(
         recommendations.map((recommendation) => checkRecommendationPath(this.workspace as Workspace, recommendation)),
       );

package/workflow/index.ts

@@ -1,8 +1,10 @@
 export * from "./artifacts";
 export * from "./executor";
+export * from "./moduleIndex";
 export * from "./plan";
 export * from "./primitive";
 export * from "./render";
+export * from "./rolloutGate";
 export * from "./source";
 export * from "./types";
 export * from "./uiPolicy";