@akanjs/devkit 2.3.9-rc.2 → 2.3.9-rc.3

package/akanContext.ts

@@ -4,7 +4,15 @@ import { capitalize } from "akanjs/common";
 import { AppExecutor, LibExecutor, type SysExecutor, type WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
 import type { PackageJson } from "./types";
-import type { RepairAction } from "./workflow";
+import {
+  type GeneratedSyncState,
+  type RepairAction,
+  type WorkflowApplyReport,
+  type WorkflowPlan,
+  type WorkflowRunArtifact,
+  workflowRunArtifactPath,
+  workflowSyncDir,
+} from "./workflow";
 
 export type AkanContextFormat = "json" | "markdown";
 export type AkanModuleKind = "domain" | "service" | "scalar";
@@ -61,6 +69,29 @@ export interface AkanDiagnostic {
   message: string;
   path?: string;
   repairActions?: RepairAction[];
+  scope?: "baseline" | "workflow" | "unknown";
+  context?: {
+    workflow?: string;
+    planPath?: string;
+    runId?: string;
+    target?: string;
+    paths?: string[];
+  };
+}
+
+export interface GeneratedFilesFreshness {
+  status: "fresh" | "stale" | "missing" | "unknown";
+  message: string;
+  refreshCommand: string;
+  verifyingCommands: string[];
+  targets?: {
+    target: string;
+    status: "fresh" | "stale" | "missing" | "unknown";
+    lastSyncedAt?: string;
+    runId?: string;
+    generatedFiles: string[];
+    reason: string;
+  }[];
 }
 
 export interface AkanDoctorResult {
@@ -71,14 +102,11 @@ export interface AkanDoctorResult {
   status: "passed" | "failed";
   diagnostics: AkanDiagnostic[];
   generatedFiles: string[];
-  generatedFilesFreshness: {
-    status: "unknown";
-    message: string;
-    refreshCommand: string;
-    verifyingCommands: string[];
-  };
+  generatedFilesFreshness: GeneratedFilesFreshness;
   validationCommands: string[];
   repairActions: RepairAction[];
+  baselineDiagnostics?: AkanDiagnostic[];
+  workflowDiagnostics?: AkanDiagnostic[];
 }
 
 export type JsonRpcRequest = {
@@ -136,6 +164,7 @@ export const renderDoctorText = (result: AkanDoctorResult) => {
   lines.push(
     "",
     "Generated file freshness:",
+    `Status: ${result.generatedFilesFreshness.status}`,
     result.generatedFilesFreshness.message,
     `Refresh: ${result.generatedFilesFreshness.refreshCommand}`,
     "",
@@ -182,7 +211,7 @@ const validationCommands = [
   "akan doctor --strict --format json",
 ];
 
-const generatedFilesFreshness = {
+const unknownGeneratedFilesFreshness: GeneratedFilesFreshness = {
   status: "unknown" as const,
   message: "Run sync before validation so generated Akan files match the current source conventions.",
   refreshCommand: "akan sync <app-or-lib>",
@@ -269,6 +298,135 @@ const safeReadJson = async <T>(filePath: string) => {
   }
 };
 
+const isWorkflowPlan = (value: unknown): value is WorkflowPlan =>
+  typeof value === "object" &&
+  value !== null &&
+  "schemaVersion" in value &&
+  value.schemaVersion === 1 &&
+  "mode" in value &&
+  value.mode === "plan";
+
+const isWorkflowApplyReport = (value: unknown): value is WorkflowApplyReport =>
+  typeof value === "object" &&
+  value !== null &&
+  "schemaVersion" in value &&
+  value.schemaVersion === 1 &&
+  "mode" in value &&
+  (value.mode === "apply" || value.mode === "dry-run");
+
+const isWorkflowRunArtifact = (value: unknown): value is WorkflowRunArtifact =>
+  typeof value === "object" && value !== null && "schemaVersion" in value && value.schemaVersion === 1;
+
+const planInputString = (plan: WorkflowPlan, key: string) => {
+  const value = plan.inputs[key];
+  return typeof value === "string" ? value : "";
+};
+
+const expandWorkflowTarget = (target: string, plan: WorkflowPlan) => {
+  const app = planInputString(plan, "app");
+  const module = planInputString(plan, "module");
+  const moduleClass = module ? capitalize(module) : "<Module>";
+  return target
+    .replace(/^\*\//, app ? `apps/${app}/` : "")
+    .replaceAll("<module>", module || "<module>")
+    .replaceAll("<Module>", moduleClass);
+};
+
+const workflowPathsForPlan = (plan: WorkflowPlan) =>
+  plan.predictedChanges.map((change) => expandWorkflowTarget(change.target, plan));
+
+const workflowPathsForArtifact = (artifact: WorkflowRunArtifact) => {
+  if (isWorkflowPlan(artifact)) return workflowPathsForPlan(artifact);
+  if (isWorkflowApplyReport(artifact)) {
+    return [
+      ...artifact.changedFiles.map((file) => file.path),
+      ...artifact.generatedFiles.map((file) => file.path),
+      ...workflowPathsForPlan(artifact.plan),
+    ];
+  }
+  if ("mode" in artifact && artifact.mode === "validate" && artifact.plan) return workflowPathsForPlan(artifact.plan);
+  return [];
+};
+
+const loadWorkflowContextPaths = async (
+  workspace: WorkspaceExecutor,
+  runIdOrPlan: string | null,
+  changedFiles: string[],
+) => {
+  const paths = [...changedFiles];
+  if (!runIdOrPlan) return paths;
+  const inputPath = path.isAbsolute(runIdOrPlan) ? runIdOrPlan : path.join(workspace.workspaceRoot, runIdOrPlan);
+  const artifact =
+    (await safeReadJson<WorkflowRunArtifact | WorkflowPlan>(inputPath)) ??
+    (await safeReadJson<WorkflowRunArtifact>(path.join(workspace.workspaceRoot, workflowRunArtifactPath(runIdOrPlan))));
+  if (artifact && isWorkflowRunArtifact(artifact)) paths.push(...workflowPathsForArtifact(artifact));
+  return [...new Set(paths.filter(Boolean))];
+};
+
+const pathKey = (value: string) =>
+  value
+    .replaceAll("\\", "/")
+    .replaceAll("*", "")
+    .replace(/<[^>]+>/g, "")
+    .replace(/\/+/g, "/")
+    .replace(/^\/|\/$/g, "");
+
+const isWorkflowRelatedDiagnostic = (diagnostic: AkanDiagnostic, workflowPaths: string[]) => {
+  if (!diagnostic.path) return false;
+  const diagnosticPath = pathKey(diagnostic.path);
+  return workflowPaths.some((workflowPath) => {
+    const candidate = pathKey(workflowPath);
+    if (!candidate) return false;
+    return (
+      diagnosticPath.startsWith(candidate) || candidate.startsWith(diagnosticPath) || diagnosticPath.includes(candidate)
+    );
+  });
+};
+
+const readGeneratedSyncStates = async (workspace: WorkspaceExecutor) => {
+  const syncDir = path.join(workspace.workspaceRoot, workflowSyncDir);
+  const entries = await safeReadDir(syncDir);
+  const states = await Promise.all(
+    entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .map((entry) => safeReadJson<GeneratedSyncState>(path.join(syncDir, entry.name))),
+  );
+  return states.filter(
+    (state): state is GeneratedSyncState =>
+      !!state && state.schemaVersion === 1 && typeof state.target === "string" && typeof state.syncedAt === "string",
+  );
+};
+
+const generatedFreshnessFromStates = async (workspace: WorkspaceExecutor): Promise<GeneratedFilesFreshness> => {
+  const states = await readGeneratedSyncStates(workspace);
+  if (states.length === 0) return unknownGeneratedFilesFreshness;
+  const targets = states
+    .sort((a, b) => a.target.localeCompare(b.target))
+    .map((state) => ({
+      target: state.target,
+      status: state.status === "passed" ? ("fresh" as const) : ("stale" as const),
+      lastSyncedAt: state.syncedAt,
+      runId: state.runId,
+      generatedFiles: state.generatedFiles.map((file) => file.path),
+      reason:
+        state.status === "passed"
+          ? `Generated files were refreshed by ${state.command}.`
+          : `Last generated repair command failed: ${state.command}.`,
+    }));
+  const lastFresh = targets
+    .filter((target) => target.status === "fresh" && target.lastSyncedAt)
+    .sort((a, b) => (b.lastSyncedAt ?? "").localeCompare(a.lastSyncedAt ?? ""))[0];
+  return {
+    status: targets.some((target) => target.status === "fresh") ? "fresh" : "stale",
+    message: lastFresh
+      ? `Generated files were refreshed for ${lastFresh.target} at ${lastFresh.lastSyncedAt}.`
+      : "Generated sync state exists, but the last recorded repair did not pass.",
+    refreshCommand: "akan sync <app-or-lib>",
+    verifyingCommands: ["akan lint <app-or-lib-or-pkg>", "akan build <app-name>"],
+    targets,
+  };
+};
+
 const parseAbstractSummary = (
   relativePath: string,
   content: string | null,
@@ -422,9 +580,14 @@ export class AkanContextAnalyzer {
 
   static async doctor(
     workspace: WorkspaceExecutor,
-    { strict = false }: { strict?: boolean } = {},
+    {
+      strict = false,
+      runIdOrPlan = null,
+      changedFiles = [],
+    }: { strict?: boolean; runIdOrPlan?: string | null; changedFiles?: string[] } = {},
   ): Promise<AkanDoctorResult> {
     const context = await AkanContextAnalyzer.analyze(workspace);
+    const workflowPaths = await loadWorkflowContextPaths(workspace, runIdOrPlan, changedFiles);
     const diagnostics: AkanDiagnostic[] = [];
     const repairActions: RepairAction[] = [
       repairAction("generated", "akan repair generated --app <app-or-lib>", "Refresh generated Akan files.", true),
@@ -524,17 +687,29 @@ export class AkanContextAnalyzer {
       }
     }
 
+    const scopedDiagnostics = diagnostics.map((diagnostic) => ({
+      ...diagnostic,
+      scope: workflowPaths.length
+        ? isWorkflowRelatedDiagnostic(diagnostic, workflowPaths)
+          ? ("workflow" as const)
+          : ("baseline" as const)
+        : diagnostic.scope,
+      context: workflowPaths.length ? { ...diagnostic.context, paths: workflowPaths } : diagnostic.context,
+    }));
+    const workflowDiagnostics = scopedDiagnostics.filter((diagnostic) => diagnostic.scope === "workflow");
+    const baselineDiagnostics = scopedDiagnostics.filter((diagnostic) => diagnostic.scope === "baseline");
     return {
       schemaVersion: 1,
       repoName: context.repoName,
       root: context.root,
       strict,
-      status: diagnostics.some((diagnostic) => diagnostic.severity === "error") ? "failed" : "passed",
-      diagnostics,
+      status: scopedDiagnostics.some((diagnostic) => diagnostic.severity === "error") ? "failed" : "passed",
+      diagnostics: scopedDiagnostics,
       generatedFiles: context.generatedFiles,
-      generatedFilesFreshness,
+      generatedFilesFreshness: await generatedFreshnessFromStates(workspace),
       validationCommands: context.validationCommands,
       repairActions,
+      ...(workflowPaths.length ? { baselineDiagnostics, workflowDiagnostics } : {}),
     };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.3.9-rc.2",
+  "version": "2.3.9-rc.3",
   "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.2",
+    "akanjs": "2.3.9-rc.3",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/workflow/index.ts

@@ -1,3 +1,4 @@
+import { capitalize } from "akanjs/common";
 import type { Sys, Workspace } from "../commandDecorators";
 import { AppExecutor, LibExecutor } from "../executors";
 
@@ -47,6 +48,7 @@ export interface WorkflowPredictedChange {
   target: string;
   action: "inspect" | "create" | "modify" | "sync" | "validate";
   reason: string;
+  applyScope?: "auto" | "manual-review" | "generated-sync" | "validation";
 }
 
 export interface WorkflowValidation {
@@ -76,6 +78,23 @@ export interface WorkflowDiagnostic {
   command?: string;
   kind?: WorkflowValidationKind;
   failureScope?: WorkflowFailureScope;
+  scope?: "baseline" | "workflow" | "unknown";
+  context?: {
+    workflow?: string;
+    planPath?: string;
+    runId?: string;
+    target?: string;
+    paths?: string[];
+  };
+}
+
+export interface WorkflowRecommendation {
+  code: string;
+  message: string;
+  kind: "auto-apply" | "validation" | "manual-action" | "import" | "placement" | "ui-component";
+  target?: string;
+  action?: string;
+  confidence?: "high" | "medium" | "low";
 }
 
 export interface WorkflowPlan {
@@ -88,6 +107,7 @@ export interface WorkflowPlan {
   predictedChanges: readonly WorkflowPredictedChange[];
   validation: readonly WorkflowValidation[];
   diagnostics: WorkflowDiagnostic[];
+  recommendations: WorkflowRecommendation[];
   requiresApproval: true;
 }
 
@@ -167,6 +187,9 @@ export type PrimitiveFileMap = Record<string, { filename: string; content: strin
 
 export interface WorkflowApplyReport {
   schemaVersion: 1;
+  runId?: string;
+  applyReportPath?: string;
+  validationTarget?: string;
   workflow: string;
   mode: "dry-run" | "apply";
   status: "passed" | "failed";
@@ -176,6 +199,7 @@ export interface WorkflowApplyReport {
   recommendedValidationCommands: WorkflowApplyCommand[];
   commands: WorkflowApplyCommand[];
   diagnostics: WorkflowDiagnostic[];
+  recommendations: WorkflowRecommendation[];
   nextActions: PrimitiveNextAction[];
   plan: WorkflowPlan;
 }
@@ -189,6 +213,8 @@ export interface WorkflowValidationRunReport {
   status: "passed" | "failed";
   commands: WorkflowValidationCommandResult[];
   diagnostics: WorkflowDiagnostic[];
+  baselineDiagnostics?: WorkflowDiagnostic[];
+  workflowDiagnostics?: WorkflowDiagnostic[];
   repairActions: RepairAction[];
   nextActions: PrimitiveNextAction[];
   plan?: WorkflowPlan;
@@ -196,6 +222,8 @@ export interface WorkflowValidationRunReport {
 
 export interface RepairReport {
   schemaVersion: 1;
+  runId?: string;
+  repairReportPath?: string;
   command: string;
   kind: RepairAction["kind"];
   target: string | null;
@@ -204,6 +232,18 @@ export interface RepairReport {
   repairActions: RepairAction[];
   nextActions: PrimitiveNextAction[];
   commands: WorkflowValidationCommandResult[];
+  generatedFiles?: PrimitiveGeneratedFile[];
+  syncedAt?: string;
+}
+
+export interface GeneratedSyncState {
+  schemaVersion: 1;
+  target: string;
+  status: "passed" | "failed";
+  syncedAt: string;
+  command: string;
+  runId?: string;
+  generatedFiles: PrimitiveGeneratedFile[];
 }
 
 export type WorkflowRunArtifact = WorkflowApplyReport | WorkflowValidationRunReport | RepairReport;
@@ -213,6 +253,7 @@ export interface WorkflowStepResult {
   generatedFiles?: PrimitiveGeneratedFile[];
   commands?: WorkflowApplyCommand[];
   diagnostics?: WorkflowDiagnostic[];
+  recommendations?: WorkflowRecommendation[];
   nextActions?: PrimitiveNextAction[];
 }
 
@@ -264,6 +305,92 @@ export const getWorkflowSpec = (specs: readonly WorkflowSpec[], name: string) =>
 export const compactWorkflowInputs = (inputs: WorkflowPlanInputs) =>
   Object.fromEntries(Object.entries(inputs).filter(([, value]) => value !== null && value !== ""));
 
+const addFieldComponentForType = (typeName: string) => {
+  const normalizedType = normalizeFieldType(typeName);
+  if (normalizedType === "Boolean") return "Field.ToggleSelect";
+  if (normalizedType === "Date") return "Field.Date";
+  if (normalizedType === "Int" || normalizedType === "Float") return "Field.ToggleSelect or Field.Text";
+  if (typeName.toLowerCase() === "enum") return "Field.ToggleSelect";
+  return "Field.Text";
+};
+
+const createAddFieldRecommendations = (inputs: Record<string, WorkflowInputValue>): WorkflowRecommendation[] => {
+  const app = typeof inputs.app === "string" ? inputs.app : "<app-or-lib>";
+  const module = typeof inputs.module === "string" ? inputs.module : "<module>";
+  const field = typeof inputs.field === "string" ? inputs.field : "<field>";
+  const typeName = typeof inputs.type === "string" ? inputs.type : null;
+  if (!typeName) return [];
+
+  const normalizedType = typeName.toLowerCase() === "enum" ? "enum" : normalizeFieldType(typeName);
+  const constantPath = `*/lib/${module}/${module}.constant.ts`;
+  const dictionaryPath = `*/lib/${module}/${module}.dictionary.ts`;
+  const templatePath = `*/lib/${module}/${capitalize(module)}.Template.tsx`;
+  return [
+    ...(normalizedType === "Int" || normalizedType === "Float"
+      ? [
+          {
+            code: "add-field-import",
+            kind: "import" as const,
+            target: constantPath,
+            confidence: "high" as const,
+            message: `Import ${normalizedType} from "akanjs/base" before writing field(${normalizedType}).`,
+          },
+        ]
+      : []),
+    {
+      code: "add-field-placement-constant",
+      kind: "placement",
+      target: constantPath,
+      confidence: "high",
+      message: `Insert ${field}: field(${normalizedType}) in ${capitalize(module)}Input.`,
+    },
+    {
+      code: "add-field-placement-dictionary",
+      kind: "placement",
+      target: dictionaryPath,
+      confidence: "high",
+      message: `Add dictionary labels for ${module}.${field}.`,
+    },
+    {
+      code: "add-field-component",
+      kind: "ui-component",
+      target: templatePath,
+      confidence: normalizedType === "Int" || normalizedType === "Float" ? "medium" : "high",
+      message: `Recommended UI component for ${field} (${normalizedType}): ${addFieldComponentForType(typeName)}.`,
+    },
+    {
+      code: "add-field-ui-manual-review",
+      kind: "manual-action",
+      target: templatePath,
+      action: `Review ${app}:${module} Template/Unit/View/Store surfaces and add ${field} only where the existing pattern is clear.`,
+      confidence: "medium",
+      message: "UI surface edits are planned as manual-review unless a safe existing field-list pattern is detected.",
+    },
+  ];
+};
+
+const createWorkflowPlanRecommendations = (
+  spec: WorkflowSpec,
+  inputs: Record<string, WorkflowInputValue>,
+): WorkflowRecommendation[] => [
+  {
+    code: "workflow-apply-first",
+    kind: "auto-apply",
+    confidence: "high",
+    action: "Call apply_workflow with the MCP planPath before editing source files directly.",
+    message: `Apply the ${spec.name} plan through apply_workflow when MCP returns planPath or next.tool=apply_workflow.`,
+  },
+  {
+    code: "workflow-validate-apply-report",
+    kind: "validation",
+    confidence: "high",
+    action:
+      "After apply_workflow, call run_validation with validationTarget when present; otherwise use applyReportPath.",
+    message: "Validate the apply report artifact so diagnostics and recommendations follow the actual apply result.",
+  },
+  ...(spec.name === "add-field" ? createAddFieldRecommendations(inputs) : []),
+];
+
 export const createWorkflowPlan = (spec: WorkflowSpec, rawInputs: Record<string, unknown>): WorkflowPlan => {
   const inputs: Record<string, WorkflowInputValue> = {};
   const diagnostics: WorkflowDiagnostic[] = [];
@@ -328,6 +455,7 @@ export const createWorkflowPlan = (spec: WorkflowSpec, rawInputs: Record<string,
     predictedChanges: spec.predictedChanges,
     validation: spec.validation,
     diagnostics,
+    recommendations: createWorkflowPlanRecommendations(spec, inputs),
     requiresApproval: true,
   };
 };
@@ -387,7 +515,10 @@ export const renderWorkflowPlan = (plan: WorkflowPlan) =>
     ...plan.steps.map((step, index) => `${index + 1}. \`${step.id}\` (${step.tool}): ${step.description}`),
     "",
     "## Predicted Changes",
-    ...plan.predictedChanges.map((change) => `- \`${change.action}\` ${change.target}: ${change.reason}`),
+    ...plan.predictedChanges.map((change) => {
+      const scope = change.applyScope ? ` (${change.applyScope})` : "";
+      return `- \`${change.action}\`${scope} ${change.target}: ${change.reason}`;
+    }),
     "",
     "## Validation",
     ...plan.validation.map((validation) => `- \`${validation.command}\`: ${validation.reason}`),
@@ -397,6 +528,11 @@ export const renderWorkflowPlan = (plan: WorkflowPlan) =>
       ? plan.diagnostics.map((diagnostic) => `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`)
       : ["- none"]),
     "",
+    "## Recommendations",
+    ...(plan.recommendations.length
+      ? plan.recommendations.map((recommendation) => `- [${recommendation.kind}] ${recommendation.message}`)
+      : ["- none"]),
+    "",
   ].join("\n");
 
 const workflowStatus = (diagnostics: readonly WorkflowDiagnostic[]) =>
@@ -424,15 +560,25 @@ export const createWorkflowApplyReport = ({
   recommendedValidationCommands,
   commands = [],
   diagnostics = [],
+  recommendations = [],
   nextActions = [],
   plan,
 }: Omit<
   WorkflowApplyReport,
-  "schemaVersion" | "status" | "appliedCommands" | "recommendedValidationCommands" | "commands"
+  | "schemaVersion"
+  | "runId"
+  | "applyReportPath"
+  | "validationTarget"
+  | "status"
+  | "appliedCommands"
+  | "recommendedValidationCommands"
+  | "commands"
+  | "recommendations"
 > & {
   appliedCommands?: WorkflowApplyCommand[];
   recommendedValidationCommands?: WorkflowApplyCommand[];
   commands?: WorkflowApplyCommand[];
+  recommendations?: WorkflowRecommendation[];
 }): WorkflowApplyReport => {
   const validationCommands = recommendedValidationCommands ?? commands;
   return {
@@ -446,6 +592,7 @@ export const createWorkflowApplyReport = ({
     recommendedValidationCommands: uniqueBy(validationCommands, (command) => command.command),
     commands: uniqueBy(validationCommands, (command) => command.command),
     diagnostics,
+    recommendations: uniqueBy(recommendations, (recommendation) => `${recommendation.kind}:${recommendation.code}`),
     nextActions: uniqueBy(nextActions, (action) => action.command),
     plan,
   };
@@ -475,17 +622,55 @@ export const createWorkflowRunId = (prefix = "run") =>
     .slice(0, 14)}-${Math.random().toString(36).slice(2, 8)}`;
 
 const getRunId = (artifact: WorkflowRunArtifact) => {
-  if ("runId" in artifact) return artifact.runId;
+  if ("runId" in artifact && artifact.runId) return artifact.runId;
   return createWorkflowRunId("mode" in artifact ? artifact.mode : artifact.kind);
 };
 
 export const workflowRunArtifactPath = (runId: string) => `${workflowRunsDir}/${runId}.json`;
 
+const withWorkflowRunMetadata = (
+  artifact: WorkflowRunArtifact,
+  runId: string,
+  artifactPath: string,
+): WorkflowRunArtifact => {
+  if ("mode" in artifact && (artifact.mode === "apply" || artifact.mode === "dry-run")) {
+    return { ...artifact, runId, applyReportPath: artifactPath, validationTarget: artifactPath };
+  }
+  if ("kind" in artifact) return { ...artifact, runId, repairReportPath: artifactPath };
+  return artifact;
+};
+
 export const writeWorkflowRunArtifact = async (workspace: Workspace, artifact: WorkflowRunArtifact) => {
   const runId = getRunId(artifact);
   const artifactPath = workflowRunArtifactPath(runId);
-  await workspace.writeFile(artifactPath, jsonText(artifact), { silent: true });
-  return { runId, path: artifactPath };
+  const artifactWithMetadata = withWorkflowRunMetadata(artifact, runId, artifactPath);
+  await workspace.writeFile(artifactPath, jsonText(artifactWithMetadata), { silent: true });
+  return { runId, path: artifactPath, artifact: artifactWithMetadata };
+};
+
+export const workflowSyncDir = ".akan/workflows/sync";
+
+const syncStateSlug = (target: string) =>
+  target
+    .trim()
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+
+export const workflowSyncStatePath = (target: string) => `${workflowSyncDir}/${syncStateSlug(target) || "target"}.json`;
+
+export const generatedFilePathsForTarget = (targetRoot: string, reason = "Generated files were refreshed by sync.") =>
+  [
+    { path: `${targetRoot}/lib/cnst.ts`, action: "sync", reason },
+    { path: `${targetRoot}/lib/dict.ts`, action: "sync", reason },
+    { path: `${targetRoot}/lib/option.ts`, action: "sync", reason },
+    { path: `${targetRoot}/lib/index.ts`, action: "sync", reason },
+  ] satisfies PrimitiveGeneratedFile[];
+
+export const writeGeneratedSyncState = async (workspace: Workspace, state: GeneratedSyncState) => {
+  const statePath = workflowSyncStatePath(state.target);
+  await workspace.writeFile(statePath, jsonText(state), { silent: true });
+  return statePath;
 };
 
 export const readWorkflowRunArtifact = async (workspace: Workspace, runId: string) => {
@@ -506,6 +691,8 @@ export const createWorkflowValidationRunReport = async ({
   commands,
   execute,
   diagnostics = [],
+  baselineDiagnostics = [],
+  workflowDiagnostics = [],
   repairActions = [],
 }: {
   runId?: string;
@@ -515,6 +702,8 @@ export const createWorkflowValidationRunReport = async ({
   commands: WorkflowApplyCommand[];
   execute: WorkflowValidationCommandExecutor;
   diagnostics?: WorkflowDiagnostic[];
+  baselineDiagnostics?: WorkflowDiagnostic[];
+  workflowDiagnostics?: WorkflowDiagnostic[];
   repairActions?: RepairAction[];
 }): Promise<WorkflowValidationRunReport> => {
   const results: WorkflowValidationCommandResult[] = [];
@@ -544,6 +733,8 @@ export const createWorkflowValidationRunReport = async ({
     status: workflowStatus([...diagnostics, ...commandDiagnostics]) === "failed" ? "failed" : commandStatus(results),
     commands: results,
     diagnostics: [...diagnostics, ...commandDiagnostics],
+    baselineDiagnostics,
+    workflowDiagnostics,
     repairActions: uniqueBy(repairActions, (action) => action.command),
     nextActions: results
       .filter((result) => result.status === "failed")
@@ -581,6 +772,7 @@ export const createDryRunWorkflowApplyReport = (plan: WorkflowPlan) => {
     generatedFiles,
     commands: workflowCommandsForPlan(plan),
     diagnostics,
+    recommendations: plan.recommendations,
     nextActions: workflowCommandsForPlan(plan),
     plan,
   });
@@ -593,6 +785,7 @@ export const primitiveReportToWorkflowStepResult = (report: PrimitiveWriteReport
   generatedFiles: report.generatedFiles,
   commands: report.validationCommands,
   diagnostics: report.diagnostics,
+  recommendations: [],
   nextActions: report.nextActions,
 });
 
@@ -629,6 +822,31 @@ const unsupportedInput = (input: string, message: string): WorkflowDiagnostic =>
   message,
 });
 
+const addFieldUiSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult => {
+  const module = workflowStringInput(plan.inputs.module) ?? "<module>";
+  const field = workflowStringInput(plan.inputs.field) ?? "<field>";
+  const moduleClassName = capitalize(module);
+  const target = `*/lib/${module}/${moduleClassName}.Template.tsx`;
+  return {
+    recommendations: [
+      {
+        code: "add-field-ui-surface-review",
+        kind: "manual-action",
+        target,
+        action: `Add ${field} to ${moduleClassName} UI surfaces only when the local Field.* pattern is clear.`,
+        confidence: "medium",
+        message: `Review Template/Unit/View/Store surfaces for ${module}.${field}; no UI file was modified automatically.`,
+      },
+    ],
+    nextActions: [
+      {
+        command: `akan workflow explain ${plan.workflow}`,
+        reason: "Review UI surface guidance before manually editing ambiguous UI files.",
+      },
+    ],
+  };
+};
+
 export const createWorkflowStepRegistry = ({
   workspace,
   createModule,
@@ -699,7 +917,7 @@ export const createWorkflowStepRegistry = ({
       );
     },
     [workflowStepKey("add-field", "update-dictionary")]: inspect,
-    [workflowStepKey("add-field", "update-ui-surfaces")]: inspect,
+    [workflowStepKey("add-field", "update-ui-surfaces")]: async (_step, plan) => addFieldUiSurfaceInspection(plan),
     [workflowStepKey("add-enum-field", "update-constant")]: async (_step, plan) =>
       primitiveReportToWorkflowStepResult(
         await addEnumField({
@@ -756,6 +974,11 @@ export const renderWorkflowApplyReport = (report: WorkflowApplyReport) =>
       ? report.diagnostics.map((diagnostic) => `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`)
       : ["- none"]),
     "",
+    "## Recommendations",
+    ...(report.recommendations.length
+      ? report.recommendations.map((recommendation) => `- [${recommendation.kind}] ${recommendation.message}`)
+      : ["- none"]),
+    "",
     "## Next Actions",
     ...(report.nextActions.length
       ? report.nextActions.map((action) => `- \`${action.command}\`: ${action.reason}`)
@@ -818,12 +1041,25 @@ export const createRepairReport = ({
   repairActions = [],
   nextActions = [],
   commands = [],
+  generatedFiles = [],
+  syncedAt,
 }: Omit<
   RepairReport,
-  "schemaVersion" | "status" | "target" | "diagnostics" | "repairActions" | "nextActions" | "commands"
+  | "schemaVersion"
+  | "runId"
+  | "repairReportPath"
+  | "status"
+  | "target"
+  | "diagnostics"
+  | "repairActions"
+  | "nextActions"
+  | "commands"
 > &
   Partial<
-    Pick<RepairReport, "target" | "diagnostics" | "repairActions" | "nextActions" | "commands">
+    Pick<
+      RepairReport,
+      "target" | "diagnostics" | "repairActions" | "nextActions" | "commands" | "generatedFiles" | "syncedAt"
+    >
   >): RepairReport => ({
   schemaVersion: 1,
   command,
@@ -834,6 +1070,8 @@ export const createRepairReport = ({
   repairActions: uniqueBy(repairActions, (action) => action.command),
   nextActions: uniqueBy(nextActions, (action) => action.command),
   commands,
+  generatedFiles,
+  ...(syncedAt ? { syncedAt } : {}),
 });
 
 export const renderRepairReportMarkdown = (report: RepairReport) =>
@@ -871,6 +1109,7 @@ export class WorkflowExecutor {
     const generatedFiles: PrimitiveGeneratedFile[] = [];
     const recommendedValidationCommands: WorkflowApplyCommand[] = [];
     const diagnostics: WorkflowDiagnostic[] = [...plan.diagnostics];
+    const recommendations: WorkflowRecommendation[] = [...plan.recommendations];
     const nextActions: PrimitiveNextAction[] = [];
 
     if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
@@ -881,6 +1120,7 @@ export class WorkflowExecutor {
         generatedFiles,
         recommendedValidationCommands,
         diagnostics,
+        recommendations,
         nextActions,
         plan,
       });
@@ -911,6 +1151,7 @@ export class WorkflowExecutor {
       generatedFiles.push(...(result.generatedFiles ?? []));
       recommendedValidationCommands.push(...(result.commands ?? []));
       diagnostics.push(...(result.diagnostics ?? []));
+      recommendations.push(...(result.recommendations ?? []));
       nextActions.push(...(result.nextActions ?? []));
       if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) break;
     }
@@ -922,6 +1163,7 @@ export class WorkflowExecutor {
       generatedFiles,
       recommendedValidationCommands,
       diagnostics,
+      recommendations,
       nextActions,
       plan,
     });
@@ -994,12 +1236,7 @@ export const sourceFile = (sys: Sys, path: string, action: PrimitiveChangedFile[
 });
 
 export const generatedFilesForSync = (sys: Sys, reason = "Generated files may change after sync.") =>
-  [
-    { path: `${getSysRoot(sys)}/lib/cnst.ts`, action: "sync", reason },
-    { path: `${getSysRoot(sys)}/lib/dict.ts`, action: "sync", reason },
-    { path: `${getSysRoot(sys)}/lib/option.ts`, action: "sync", reason },
-    { path: `${getSysRoot(sys)}/lib/index.ts`, action: "sync", reason },
-  ] satisfies PrimitiveGeneratedFile[];
+  generatedFilePathsForTarget(getSysRoot(sys), reason);
 
 export const validationCommandsForTarget = (target: string) =>
   [