@ontrails/trails 1.0.0-beta.45 → 1.0.0-beta.46

package/src/trails/regrade.ts

@@ -14,14 +14,19 @@ import {
 } from '@ontrails/core';
 import type { PathScope, Result as TrailsResult } from '@ontrails/core';
 import {
+  applyPreparedRegradeRun,
+  applyPreparedVocabularyRegradeRun,
   createGovernedAstIdentifierRenameClasses,
   loadWardenRegradeClasses,
+  prepareRegradeRun,
+  prepareVocabularyRegradeRun,
   readVocabularyTransitionRecord,
   regradeReportOutput,
   runFileRenameRegrade,
   runRegrade,
   runVocabularyRegrade,
   transitionRecordReportWithSummary,
+  validatePreparedRegradeRun,
   vocabularyRegradeTransitionForInput,
   vocabularyDispositionValues,
   vocabularyRegradePlanSchema,
@@ -30,6 +35,9 @@ import {
 } from '@ontrails/regrade';
 import type {
   FileRenameRegradeRun,
+  PreparedRegradeRun,
+  PreparedRegradeRunIdentity,
+  PreparedVocabularyRegradeRun,
   RegradeApplySummary,
   RegradeReport,
   RegradeReportEntry,
@@ -46,7 +54,6 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync,
-  rmSync,
   writeFileSync,
 } from 'node:fs';
 import type { Dirent } from 'node:fs';
@@ -60,8 +67,12 @@ import {
 } from '../regrade/audit.js';
 import { loadRegradeConfig } from '../regrade/config.js';
 import {
-  REGRADE_HISTORY_SCHEMA_VERSION,
+  RegradeLifecycleTracker,
+  regradeLifecycleSchema,
+} from '../regrade/lifecycle.js';
+import {
   appendRegradeHistoryRun,
+  consumeActiveRegradePlanAfterHistoryWrite,
   readRegradeHistoryArtifact,
   regradeHistoryPathForPlan,
   resolveRegradeHistoryPath,
@@ -70,7 +81,18 @@ import {
 } from '../regrade/history.js';
 import type { RegradeHistorySummary } from '../regrade/history.js';
 import { deriveLiveApiPreserveInventory } from '../regrade/live-api-preserve.js';
+import {
+  captureRegradeChangedFilesBefore,
+  completeRegradeChangedFiles,
+  resolveRegradeSourceRevision,
+  validateRegradeReceiptPlan,
+} from '../regrade/receipt-history.js';
+import type { RegradeChangedFileEvidence } from '../regrade/receipt-history.js';
 import { deriveRegradePlanDerivation } from '../regrade/plan-derivation.js';
+import {
+  preparedRegradeRunIdentity,
+  validatePreparedRegradePlanArtifact,
+} from '../regrade/prepared-run.js';
 import {
   regradeApplyErrorAfterRollback,
   snapshotRegradeSources,
@@ -239,7 +261,19 @@ const regradePlansOutputSchema = z.object({
   plans: z.array(regradePlanSummarySchema),
 });
 
-const regradeCheckOutputSchema = regradeReportOutput.extend({
+const regradeLifecycleReportOutputSchema = regradeReportOutput.extend({
+  lifecycle: regradeLifecycleSchema.describe(
+    'Observed phases and wall-clock timings for this lifecycle command'
+  ),
+});
+
+const regradePlanCommandOutputSchema = regradePlanArtifactSchema.extend({
+  lifecycle: regradeLifecycleSchema.describe(
+    'Observed phases and wall-clock timings for this lifecycle command'
+  ),
+});
+
+const regradeCheckOutputSchema = regradeLifecycleReportOutputSchema.extend({
   check: z
     .object({
       plan: z
@@ -875,6 +909,19 @@ const mergeTransitionRunReportWithSymbol = (
   };
 };
 
+const withScannedPaths = (
+  report: RegradeReport,
+  paths: readonly string[]
+): RegradeReport => {
+  Object.defineProperty(report, 'scannedPaths', {
+    configurable: false,
+    enumerable: false,
+    value: Object.freeze([...paths]),
+    writable: false,
+  });
+  return report;
+};
+
 const mergeRegradeReports = (
   vocabularyReport: RegradeReport,
   symbolReport: RegradeReport
@@ -908,7 +955,15 @@ const mergeRegradeReports = (
     symbolReport.skipsByReason
   );
   const apply = mergeApplySummary(vocabularyReport.apply, symbolReport.apply);
-  const scanned = vocabularyReport.scanned + symbolReport.scanned;
+  const scannedPaths = uniqueSorted([
+    ...(vocabularyReport.scannedPaths ?? []),
+    ...(symbolReport.scannedPaths ?? []),
+  ]);
+  const scanned =
+    vocabularyReport.scannedPaths === undefined ||
+    symbolReport.scannedPaths === undefined
+      ? vocabularyReport.scanned + symbolReport.scanned
+      : scannedPaths.length;
   const run =
     vocabularyReport.run === undefined
       ? undefined
@@ -920,36 +975,39 @@ const mergeRegradeReports = (
           ),
         };
 
-  return {
-    ...vocabularyReport,
-    ...(apply === undefined ? {} : { apply }),
-    entries,
-    matched,
-    review,
-    rewritten,
-    scan: {
-      byDirectory: mergedDirectoryBuckets(matchedPaths, occurrencePaths),
-      byExtension: mergedExtensionBuckets(matchedPaths, occurrencePaths),
-      files: {
-        matched: new Set(matchedPaths).size,
-        scanned,
-        skipped: Math.max(vocabularyReport.skipped, symbolReport.skipped),
+  return withScannedPaths(
+    {
+      ...vocabularyReport,
+      ...(apply === undefined ? {} : { apply }),
+      entries,
+      matched,
+      review,
+      rewritten,
+      scan: {
+        byDirectory: mergedDirectoryBuckets(matchedPaths, occurrencePaths),
+        byExtension: mergedExtensionBuckets(matchedPaths, occurrencePaths),
+        files: {
+          matched: new Set(matchedPaths).size,
+          scanned,
+          skipped: Math.max(vocabularyReport.skipped, symbolReport.skipped),
+        },
+        skippedByReason,
       },
-      skippedByReason,
+      ...(run === undefined ? {} : { run }),
+      scanned,
+      selectedClassIds: uniqueSorted([
+        ...vocabularyReport.selectedClassIds,
+        ...symbolReport.selectedClassIds,
+      ]),
+      skipped: Math.max(vocabularyReport.skipped, symbolReport.skipped),
+      skipsByReason: skippedByReason,
+      unknownClassIds: uniqueSorted([
+        ...vocabularyReport.unknownClassIds,
+        ...symbolReport.unknownClassIds,
+      ]),
     },
-    ...(run === undefined ? {} : { run }),
-    scanned,
-    selectedClassIds: uniqueSorted([
-      ...vocabularyReport.selectedClassIds,
-      ...symbolReport.selectedClassIds,
-    ]),
-    skipped: Math.max(vocabularyReport.skipped, symbolReport.skipped),
-    skipsByReason: skippedByReason,
-    unknownClassIds: uniqueSorted([
-      ...vocabularyReport.unknownClassIds,
-      ...symbolReport.unknownClassIds,
-    ]),
-  };
+    scannedPaths
+  );
 };
 
 const vocabularySymbolCollection = (
@@ -1046,41 +1104,62 @@ const withoutVocabularySourceFilterSkips = (
   if (report === null || rejected === 0) {
     return report;
   }
-  return {
-    ...report,
-    ...(report.apply === undefined
-      ? {}
-      : {
-          apply: {
-            ...report.apply,
-            skipped: Math.max(0, report.apply.skipped - rejected),
-          },
-        }),
-    entries: report.entries.filter(
-      (entry) => entry.reason !== 'not-selected-source'
-    ),
-    scan: {
-      ...report.scan,
-      files: {
-        ...report.scan.files,
-        skipped: Math.max(0, report.scan.files.skipped - rejected),
-      },
-      skippedByReason: withoutNotSelectedSourceCount(
-        report.scan.skippedByReason
+  return withScannedPaths(
+    {
+      ...report,
+      ...(report.apply === undefined
+        ? {}
+        : {
+            apply: {
+              ...report.apply,
+              skipped: Math.max(0, report.apply.skipped - rejected),
+            },
+          }),
+      entries: report.entries.filter(
+        (entry) => entry.reason !== 'not-selected-source'
       ),
+      scan: {
+        ...report.scan,
+        files: {
+          ...report.scan.files,
+          skipped: Math.max(0, report.scan.files.skipped - rejected),
+        },
+        skippedByReason: withoutNotSelectedSourceCount(
+          report.scan.skippedByReason
+        ),
+      },
+      skipped: Math.max(0, report.skipped - rejected),
+      skipsByReason: withoutNotSelectedSourceCount(report.skipsByReason),
     },
-    skipped: Math.max(0, report.skipped - rejected),
-    skipsByReason: withoutNotSelectedSourceCount(report.skipsByReason),
-  };
+    report.scannedPaths ?? []
+  );
 };
 
 const vocabularyEvidenceSource = (
   path: string,
-  scope: VocabularyRegradePlan['scope'] | undefined
+  scope: VocabularyRegradePlan['scope'] | undefined,
+  includeCodeComments = false
 ): boolean =>
   vocabularyProseExtensions.includes(extname(path)) ||
+  (includeCodeComments && symbolSourceExtensions.includes(extname(path))) ||
   symbolOccurrenceIsPolicyClassified(scope, path);
 
+const classifiedCommentInventoryApplies = (
+  plan: VocabularyRegradePlan
+): boolean =>
+  vocabularyRegradeTransitionForInput(plan.from, plan.to)?.target.kind ===
+  'classified';
+
+const vocabularyEvidenceSourceKind = (
+  path: string,
+  plan: VocabularyRegradePlan
+): 'all' | 'comments' =>
+  classifiedCommentInventoryApplies(plan) &&
+  symbolSourceExtensions.includes(extname(path)) &&
+  !symbolOccurrenceIsPolicyClassified(plan.scope, path)
+    ? 'comments'
+    : 'all';
+
 const vocabularyProseEngineApplies = (
   scope: VocabularyRegradePlan['scope'] | undefined
 ): boolean =>
@@ -1215,8 +1294,12 @@ const buildVocabularyPlan = (
   const overrides = mergeVocabularyOverrides(registryPlan, input);
   const preserveRules = mergeVocabularyPreserveRules(registryPlan, preserve);
   const scope = mergeVocabularyScope(registryPlan?.scope, configScope, input);
-  const fileRenames =
-    input.fileRenames ?? registryFileRenamesForRoot(registryPlan, rootDir);
+  const fileRenames = (
+    input.fileRenames ?? registryFileRenamesForRoot(registryPlan, rootDir)
+  )?.map((rename) => ({
+    from: posix.normalize(rename.from.replaceAll('\\', '/')),
+    to: posix.normalize(rename.to.replaceAll('\\', '/')),
+  }));
 
   return Result.ok({
     ...(registryPlan?.caseSensitive === undefined
@@ -1312,41 +1395,40 @@ const reportWithVocabularyTransitionRun = (params: {
     report: transitionRunReportForRegradeReport(params.report),
   };
 
-  return {
-    ...params.report,
-    run: {
-      ...run,
-      plan: params.plan,
-      ...(preserveInventory === undefined ? {} : { preserveInventory }),
-      report:
-        params.report.run === undefined
-          ? transitionRunReportForRegradeReport(params.report)
-          : params.report.run.report,
+  return withScannedPaths(
+    {
+      ...params.report,
+      run: {
+        ...run,
+        plan: params.plan,
+        ...(preserveInventory === undefined ? {} : { preserveInventory }),
+        report:
+          params.report.run === undefined
+            ? transitionRunReportForRegradeReport(params.report)
+            : params.report.run.report,
+      },
     },
-  };
+    params.report.scannedPaths ?? []
+  );
 };
 
-const runGovernedSymbolRegrade = (params: {
-  readonly apply: boolean;
-  readonly includeEntries: RegradeInput['includeEntries'];
+const governedSymbolRegradeConfiguration = (params: {
   readonly plan: VocabularyRegradePlan;
   readonly preserveInventory: readonly VocabularyPreserveInventoryEntry[];
-  readonly rootDir: string;
-}): TrailsResult<RegradeReport | null, Error> => {
+}) => {
   const transition = vocabularyRegradeTransitionForInput(
     params.plan.from,
     params.plan.to
   );
   if (transition === undefined) {
-    return Result.ok(null);
+    return null;
   }
 
   const symbolCollection = vocabularySymbolCollection(params.plan.scope);
   if (symbolCollection === null) {
-    return Result.ok(null);
+    return null;
   }
-  return runRegrade({
-    apply: params.apply,
+  return {
     classes: createGovernedAstIdentifierRenameClasses(
       {
         ...transition,
@@ -1375,6 +1457,23 @@ const runGovernedSymbolRegrade = (params: {
       }
     ),
     ...(symbolCollection === undefined ? {} : { collection: symbolCollection }),
+  };
+};
+
+const runGovernedSymbolRegrade = (params: {
+  readonly apply: boolean;
+  readonly includeEntries: RegradeInput['includeEntries'];
+  readonly plan: VocabularyRegradePlan;
+  readonly preserveInventory: readonly VocabularyPreserveInventoryEntry[];
+  readonly rootDir: string;
+}): TrailsResult<RegradeReport | null, Error> => {
+  const configuration = governedSymbolRegradeConfiguration(params);
+  if (configuration === null) {
+    return Result.ok(null);
+  }
+  return runRegrade({
+    ...configuration,
+    apply: params.apply,
     includeEntries: params.includeEntries,
     root: params.rootDir,
   });
@@ -1571,11 +1670,104 @@ const buildRegradePlanArtifact = (params: {
   };
 };
 
+const normalizeAuthoredPlanPath = (path: string): string =>
+  posix.normalize(path.replaceAll('\\', '/'));
+
+const normalizeRegradePlanBodyPaths = (
+  plan: RegradePlanBody
+): RegradePlanBody => {
+  const scope =
+    plan.scope === undefined
+      ? undefined
+      : {
+          ...plan.scope,
+          ...(plan.scope.exclude === undefined
+            ? {}
+            : {
+                exclude: plan.scope.exclude.map(normalizeAuthoredPlanPath),
+              }),
+          ...(plan.scope.include === undefined
+            ? {}
+            : {
+                include: plan.scope.include.map(normalizeAuthoredPlanPath),
+              }),
+        };
+  if (plan.kind === 'class') {
+    return {
+      ...plan,
+      ...(scope === undefined ? {} : { scope }),
+    } as RegradePlanBody;
+  }
+  return {
+    ...plan,
+    ...(plan.fileRenames === undefined
+      ? {}
+      : {
+          fileRenames: plan.fileRenames.map((rename) => ({
+            ...rename,
+            from: normalizeAuthoredPlanPath(rename.from),
+            to: normalizeAuthoredPlanPath(rename.to),
+          })),
+        }),
+    ...(plan.preserve === undefined
+      ? {}
+      : {
+          preserve: plan.preserve.map((preserve) => ({
+            ...preserve,
+            ...(preserve.paths === undefined
+              ? {}
+              : {
+                  paths: preserve.paths.map(normalizeAuthoredPlanPath),
+                }),
+          })),
+        }),
+    ...(scope === undefined
+      ? {}
+      : {
+          scope: {
+            ...scope,
+            ...(plan.scope?.ignoredDirectories === undefined
+              ? {}
+              : {
+                  ignoredDirectories: plan.scope.ignoredDirectories.map(
+                    normalizeAuthoredPlanPath
+                  ),
+                }),
+            ...(plan.scope?.policyClassified === undefined
+              ? {}
+              : {
+                  policyClassified: plan.scope.policyClassified.map(
+                    (policy) => ({
+                      ...policy,
+                      paths: policy.paths.map(normalizeAuthoredPlanPath),
+                    })
+                  ),
+                }),
+            ...(plan.scope?.teachingSurfaces === undefined
+              ? {}
+              : {
+                  teachingSurfaces: plan.scope.teachingSurfaces.map(
+                    normalizeAuthoredPlanPath
+                  ),
+                }),
+          },
+        }),
+  } as RegradePlanBody;
+};
+
+const normalizeRegradePlanArtifactPaths = (
+  artifact: RegradePlanArtifact
+): RegradePlanArtifact => ({
+  ...artifact,
+  plan: normalizeRegradePlanBodyPaths(artifact.plan),
+});
+
 const writeRegradePlanArtifact = (
   rootDir: string,
   artifact: RegradePlanArtifact
 ): TrailsResult<RegradePlanArtifact, InternalError | ValidationError> => {
-  const parsed = regradePlanArtifactSchema.safeParse(artifact);
+  const normalizedArtifact = normalizeRegradePlanArtifactPaths(artifact);
+  const parsed = regradePlanArtifactSchema.safeParse(normalizedArtifact);
   if (!parsed.success) {
     return Result.err(
       new ValidationError('Invalid Regrade plan artifact.', {
@@ -1601,7 +1793,9 @@ const writeRegradePlanArtifact = (
 const validateRegradePlanArtifact = (
   artifact: RegradePlanArtifact
 ): TrailsResult<RegradePlanArtifact, ValidationError> => {
-  const parsed = regradePlanArtifactSchema.safeParse(artifact);
+  const parsed = regradePlanArtifactSchema.safeParse(
+    normalizeRegradePlanArtifactPaths(artifact)
+  );
   if (!parsed.success) {
     return Result.err(
       new ValidationError('Invalid Regrade plan artifact.', {
@@ -1637,7 +1831,11 @@ const readRegradePlanArtifact = (
       })
     );
   }
-  return Result.ok(parsed.data as unknown as RegradePlanArtifact);
+  return Result.ok(
+    normalizeRegradePlanArtifactPaths(
+      parsed.data as unknown as RegradePlanArtifact
+    )
+  );
 };
 
 /**
@@ -1897,7 +2095,7 @@ const withFileRenameEvidence = (params: {
   ]);
   const filePolicyCount = params.run.policyOccurrencePaths.length;
   const fileInScopeCount = params.run.occurrencePaths.length - filePolicyCount;
-  const projectedFileInScopeCount =
+  const derivedFileInScopeCount =
     params.run.report.rewritten + params.run.report.review;
   return {
     ...params.report,
@@ -1914,7 +2112,7 @@ const withFileRenameEvidence = (params: {
         scopeTiers: {
           'in-scope':
             params.report.run.report.scopeTiers['in-scope'] -
-            projectedFileInScopeCount +
+            derivedFileInScopeCount +
             fileInScopeCount,
           'policy-classified':
             params.report.run.report.scopeTiers['policy-classified'] +
@@ -2016,22 +2214,88 @@ const runPlanFileRenames = (
         vocabularyPlan: plan,
       });
 
-const runResolvedVocabularyPlan = (params: {
+interface PreparedVocabularyPlanRun {
+  readonly fileRenamePreflight: FileRenameRegradeRun | null;
+  readonly identity: PreparedRegradeRunIdentity;
+  readonly prose: PreparedVocabularyRegradeRun | null;
+  readonly proseReport: RegradeReport | null;
+  readonly preserveInventory: readonly VocabularyPreserveInventoryEntry[];
+  readonly symbol: PreparedRegradeRun | null;
+}
+
+const validatePreparedPlanIdentity = (
+  expected: PreparedRegradeRunIdentity,
+  actual: PreparedRegradeRunIdentity
+): TrailsResult<void, ValidationError> => {
+  for (const field of [
+    'planContentHash',
+    'policyHash',
+    'scopeHash',
+    'lockStateHash',
+    'toolVersion',
+  ] as const) {
+    if (expected[field] !== actual[field]) {
+      return Result.err(
+        new ValidationError(
+          `Prepared Regrade identity field \`${field}\` is stale.`,
+          {
+            context: {
+              actual: actual[field],
+              expected: expected[field],
+              field,
+            },
+          }
+        )
+      );
+    }
+  }
+  return Result.ok();
+};
+
+interface ResolvedVocabularyPlanParams {
   readonly apply: boolean;
+  readonly currentIdentity?: PreparedRegradeRunIdentity | undefined;
   readonly includeEntries: RegradeInput['includeEntries'];
   readonly plan: VocabularyRegradePlan;
+  readonly prepareIdentity?: PreparedRegradeRunIdentity | undefined;
+  readonly prepared?: PreparedVocabularyPlanRun | undefined;
+  readonly preparedResult?:
+    | { value?: PreparedVocabularyPlanRun | undefined }
+    | undefined;
   readonly preserveInventory: readonly VocabularyPreserveInventoryEntry[];
   readonly rootDir: string;
-}): TrailsResult<RegradeReport, Error> => {
-  const fileRenamePreflight = runPlanFileRenames(params.plan, {
-    apply: false,
-    includeEntries: params.includeEntries,
-    rootDir: params.rootDir,
-  });
+}
+
+interface VocabularyPlanExecution {
+  readonly fileRenamePreflight: FileRenameRegradeRun | null;
+  readonly prosePrepared: PreparedVocabularyRegradeRun | null;
+  readonly prosePreviewReport: RegradeReport | null;
+  readonly runProse: (
+    apply: boolean
+  ) => TrailsResult<RegradeReport | null, Error>;
+  readonly runSymbols: (
+    apply: boolean
+  ) => TrailsResult<RegradeReport | null, Error>;
+  readonly symbolPrepared: PreparedRegradeRun | null;
+  readonly symbolPreviewReport: RegradeReport | null;
+}
+
+const vocabularyPlanExecution = (
+  params: ResolvedVocabularyPlanParams
+): TrailsResult<VocabularyPlanExecution, Error> => {
+  const fileRenamePreflight =
+    params.prepared === undefined
+      ? runPlanFileRenames(params.plan, {
+          apply: false,
+          includeEntries: params.includeEntries,
+          rootDir: params.rootDir,
+        })
+      : Result.ok(params.prepared.fileRenamePreflight);
   if (fileRenamePreflight.isErr()) {
     return fileRenamePreflight;
   }
   const evidencePlan = vocabularyEvidencePlan(params.plan);
+  const includeCodeComments = classifiedCommentInventoryApplies(params.plan);
   const runProse = (
     apply: boolean
   ): TrailsResult<RegradeReport | null, Error> =>
@@ -2046,7 +2310,13 @@ const runResolvedVocabularyPlan = (params: {
             : { preserveInventory: params.preserveInventory }),
           root: params.rootDir,
           sourceFilter: (path) =>
-            vocabularyEvidenceSource(path, evidencePlan.scope),
+            vocabularyEvidenceSource(
+              path,
+              evidencePlan.scope,
+              includeCodeComments
+            ),
+          sourceKindForPath: (path) =>
+            vocabularyEvidenceSourceKind(path, evidencePlan),
         });
   const runSymbols = (
     apply: boolean
@@ -2058,47 +2328,244 @@ const runResolvedVocabularyPlan = (params: {
       preserveInventory: params.preserveInventory,
       rootDir: params.rootDir,
     });
-  const prosePreview = runProse(false);
+  const prosePrepared =
+    params.prepareIdentity === undefined || evidencePlan === null
+      ? Result.ok(null)
+      : prepareVocabularyRegradeRun({
+          identity: params.prepareIdentity,
+          includeEntries: params.includeEntries,
+          plan: evidencePlan,
+          ...(params.preserveInventory.length === 0
+            ? {}
+            : { preserveInventory: params.preserveInventory }),
+          root: params.rootDir,
+          sourceFilter: (path) =>
+            vocabularyEvidenceSource(
+              path,
+              evidencePlan.scope,
+              includeCodeComments
+            ),
+          sourceKindForPath: (path) =>
+            vocabularyEvidenceSourceKind(path, evidencePlan),
+        });
+  if (prosePrepared.isErr()) {
+    return prosePrepared;
+  }
+  let prosePreview: TrailsResult<RegradeReport | null, Error>;
+  if (params.prepared !== undefined) {
+    prosePreview = Result.ok(params.prepared.proseReport);
+  } else if (prosePrepared.value === null) {
+    prosePreview = runProse(false);
+  } else {
+    prosePreview = Result.ok(prosePrepared.value.report);
+  }
   if (prosePreview.isErr()) {
     return prosePreview;
   }
   const prosePreviewReport = withoutVocabularySourceFilterSkips(
     prosePreview.value
   );
-  const symbolPreview = runSymbols(false);
+  const symbolConfiguration = governedSymbolRegradeConfiguration({
+    plan: params.plan,
+    preserveInventory: params.preserveInventory,
+  });
+  const symbolPrepared =
+    params.prepareIdentity === undefined || symbolConfiguration === null
+      ? Result.ok(null)
+      : prepareRegradeRun({
+          ...symbolConfiguration,
+          identity: params.prepareIdentity,
+          includeEntries: params.includeEntries,
+          root: params.rootDir,
+        });
+  if (symbolPrepared.isErr()) {
+    return symbolPrepared;
+  }
+  // Apply reevaluates symbol work after prose because shared code comments can
+  // change source bytes and offsets. Initial preparation retains the original
+  // symbol source state solely for pre-mutation freshness validation.
+  const symbolPreview =
+    params.prepared !== undefined || symbolPrepared.value === null
+      ? runSymbols(false)
+      : Result.ok(symbolPrepared.value.report);
   if (symbolPreview.isErr()) {
     return symbolPreview;
   }
+  return Result.ok({
+    fileRenamePreflight: fileRenamePreflight.value,
+    prosePrepared: prosePrepared.value,
+    prosePreviewReport,
+    runProse,
+    runSymbols,
+    symbolPrepared: symbolPrepared.value,
+    symbolPreviewReport: symbolPreview.value,
+  });
+};
+
+const previewResolvedVocabularyPlan = (
+  params: ResolvedVocabularyPlanParams,
+  execution: VocabularyPlanExecution
+): TrailsResult<RegradeReport, Error> => {
+  if (
+    execution.prosePreviewReport?.scanned === 0 &&
+    execution.symbolPreviewReport === null &&
+    execution.fileRenamePreflight === null &&
+    !vocabularyProseEngineApplies(params.plan.scope)
+  ) {
+    return regradeNoEngineForScope();
+  }
+  const report = combineVocabularyReports({
+    fileRenameRun: execution.fileRenamePreflight,
+    plan: params.plan,
+    preserveInventory: params.preserveInventory,
+    proseReport: execution.prosePreviewReport,
+    symbolReport: execution.symbolPreviewReport,
+  });
+  if (
+    report.isOk() &&
+    params.prepareIdentity !== undefined &&
+    params.preparedResult !== undefined
+  ) {
+    params.preparedResult.value = {
+      fileRenamePreflight: execution.fileRenamePreflight,
+      identity: params.prepareIdentity,
+      preserveInventory: params.preserveInventory,
+      prose: execution.prosePrepared,
+      proseReport: execution.prosePreviewReport,
+      symbol: execution.symbolPrepared,
+    };
+  }
+  return report;
+};
+
+export const validatePreparedFileRenameSourceState = (params: {
+  readonly includeEntries: RegradeInput['includeEntries'];
+  readonly plan: VocabularyRegradePlan;
+  readonly prepared: FileRenameRegradeRun | null;
+  readonly rootDir: string;
+}): TrailsResult<void, Error> => {
+  if (params.prepared === null) {
+    return Result.ok();
+  }
+  const current = runPlanFileRenames(params.plan, {
+    apply: false,
+    includeEntries: params.includeEntries,
+    rootDir: params.rootDir,
+  });
+  if (current.isErr()) {
+    return current;
+  }
+  if (current.value === null) {
+    return Result.err(
+      new InternalError('Prepared Regrade file rename set changed.')
+    );
+  }
+  if (current.value.sourceStateHash !== params.prepared.sourceStateHash) {
+    return Result.err(
+      new ValidationError(
+        'Prepared Regrade file rename source state is stale.',
+        {
+          context: {
+            actual: current.value.sourceStateHash,
+            expected: params.prepared.sourceStateHash,
+          },
+        }
+      )
+    );
+  }
+  return Result.ok();
+};
+
+const validatePreparedVocabularyPlanState = (params: {
+  readonly currentIdentity: PreparedRegradeRunIdentity;
+  readonly execution: VocabularyPlanExecution;
+  readonly includeEntries: RegradeInput['includeEntries'];
+  readonly plan: VocabularyRegradePlan;
+  readonly prepared: PreparedVocabularyPlanRun;
+  readonly rootDir: string;
+}): TrailsResult<void, Error> => {
+  const identity = validatePreparedPlanIdentity(
+    params.prepared.identity,
+    params.currentIdentity
+  );
+  if (identity.isErr()) {
+    return identity;
+  }
+  const fileRenameState = validatePreparedFileRenameSourceState({
+    includeEntries: params.includeEntries,
+    plan: params.plan,
+    prepared: params.execution.fileRenamePreflight,
+    rootDir: params.rootDir,
+  });
+  if (fileRenameState.isErr() || params.prepared.symbol === null) {
+    return fileRenameState;
+  }
+  return validatePreparedRegradeRun(
+    params.prepared.symbol,
+    params.currentIdentity
+  );
+};
+
+/**
+ * Prepared vocabulary lifecycle seam for focused conformance tests.
+ *
+ * @internal
+ */
+export const runResolvedVocabularyPlan = (
+  params: ResolvedVocabularyPlanParams
+): TrailsResult<RegradeReport, Error> => {
+  const execution = vocabularyPlanExecution(params);
+  if (execution.isErr()) {
+    return execution;
+  }
   if (!params.apply) {
-    if (
-      prosePreviewReport?.scanned === 0 &&
-      symbolPreview.value === null &&
-      fileRenamePreflight.value === null &&
-      !vocabularyProseEngineApplies(params.plan.scope)
-    ) {
-      return regradeNoEngineForScope();
+    return previewResolvedVocabularyPlan(params, execution.value);
+  }
+
+  let { currentIdentity } = params;
+  if (params.prepared !== undefined) {
+    if (currentIdentity === undefined) {
+      return Result.err(
+        new InternalError('Prepared Regrade apply is missing current identity.')
+      );
     }
-    return combineVocabularyReports({
-      fileRenameRun: fileRenamePreflight.value,
+    const preparedState = validatePreparedVocabularyPlanState({
+      currentIdentity,
+      execution: execution.value,
+      includeEntries: params.includeEntries,
       plan: params.plan,
-      preserveInventory: params.preserveInventory,
-      proseReport: prosePreviewReport,
-      symbolReport: symbolPreview.value,
+      prepared: params.prepared,
+      rootDir: params.rootDir,
     });
+    if (preparedState.isErr()) {
+      return preparedState;
+    }
   }
 
   const snapshots = snapshotRegradeSources({
-    reports: [prosePreviewReport, symbolPreview.value],
+    reports: [
+      execution.value.prosePreviewReport,
+      execution.value.symbolPreviewReport,
+    ],
     rootDir: params.rootDir,
   });
   if (snapshots.isErr()) {
     return snapshots;
   }
-  const reportResult = runProse(true);
+  let reportResult: TrailsResult<RegradeReport | null, Error>;
+  if (params.prepared?.prose === undefined || params.prepared.prose === null) {
+    reportResult = execution.value.runProse(true);
+  } else {
+    currentIdentity ??= params.prepared.identity;
+    reportResult = applyPreparedVocabularyRegradeRun(
+      params.prepared.prose,
+      currentIdentity
+    );
+  }
   if (reportResult.isErr()) {
     return regradeApplyErrorAfterRollback(reportResult.error, snapshots.value);
   }
-  const symbolReportResult = runSymbols(true);
+  const symbolReportResult = execution.value.runSymbols(true);
   if (symbolReportResult.isErr()) {
     return regradeApplyErrorAfterRollback(
       symbolReportResult.error,
@@ -2247,6 +2714,131 @@ const runPlanArtifactDryRun = async (params: {
   });
 };
 
+interface PreparedClassPlanRun {
+  readonly identity: PreparedRegradeRunIdentity;
+  readonly run: PreparedRegradeRun;
+}
+
+type PreparedPlanRun =
+  | { readonly kind: 'class'; readonly prepared: PreparedClassPlanRun }
+  | {
+      readonly kind: 'vocabulary';
+      readonly prepared: PreparedVocabularyPlanRun;
+    };
+
+const preparePlanArtifactRun = async (params: {
+  readonly artifact: RegradePlanArtifact;
+  readonly includeEntries: RegradePlanReferenceInput['includeEntries'];
+  readonly rootDir: string;
+}): Promise<
+  TrailsResult<
+    { readonly prepared: PreparedPlanRun; readonly report: RegradeReport },
+    Error
+  >
+> => {
+  const planBody = params.artifact.plan;
+  if (planBody.kind === 'class') {
+    const classSet = await loadWardenRegradeClasses(params.rootDir);
+    if (classSet.diagnostics.length > 0) {
+      return Result.err(
+        new InternalError('Failed to load Regrade project Warden rules.', {
+          context: {
+            diagnostics: classSet.diagnostics,
+            rootDir: params.rootDir,
+          },
+        })
+      );
+    }
+    const identity = preparedRegradeRunIdentity({
+      artifact: params.artifact,
+      classIds: classSet.classes.map((regradeClass) => regradeClass.id),
+      classes: classSet.classes,
+      includeEntries: params.includeEntries,
+      rootDir: params.rootDir,
+    });
+    if (identity.isErr()) {
+      return identity;
+    }
+    const prepared = prepareRegradeRun({
+      classes: classSet.classes,
+      ...(planBody.scope === undefined
+        ? {}
+        : {
+            collection: {
+              ...(planBody.scope.exclude === undefined
+                ? {}
+                : { exclude: planBody.scope.exclude }),
+              ...(planBody.scope.extensions === undefined
+                ? {}
+                : { extensions: planBody.scope.extensions }),
+              ...(planBody.scope.include === undefined
+                ? {}
+                : { include: planBody.scope.include }),
+            },
+          }),
+      identity: identity.value,
+      includeEntries: params.includeEntries,
+      root: params.rootDir,
+      selection: { classIds: planBody.classIds },
+    });
+    if (prepared.isErr()) {
+      return prepared;
+    }
+    if (prepared.value === null) {
+      return regradeRootNotFound(params.rootDir);
+    }
+    const report = validateRegradeReport(prepared.value.report);
+    if (report.isErr()) {
+      return report;
+    }
+    return Result.ok({
+      prepared: {
+        kind: 'class',
+        prepared: { identity: identity.value, run: prepared.value },
+      },
+      report: report.value,
+    });
+  }
+
+  const preserveResult = await deriveLiveApiPreserveInventory(
+    planBody,
+    params.rootDir
+  );
+  if (preserveResult.isErr()) {
+    return preserveResult;
+  }
+  const identity = preparedRegradeRunIdentity({
+    artifact: params.artifact,
+    includeEntries: params.includeEntries,
+    rootDir: params.rootDir,
+  });
+  if (identity.isErr()) {
+    return identity;
+  }
+  const preparedResult: { value?: PreparedVocabularyPlanRun } = {};
+  const report = runResolvedVocabularyPlan({
+    apply: false,
+    includeEntries: params.includeEntries,
+    plan: planBody,
+    prepareIdentity: identity.value,
+    preparedResult,
+    preserveInventory: preserveResult.value,
+    rootDir: params.rootDir,
+  });
+  if (report.isErr()) {
+    return report;
+  }
+  if (preparedResult.value === undefined) {
+    return Result.err(
+      new InternalError('Regrade vocabulary run was not prepared.')
+    );
+  }
+  return Result.ok({
+    prepared: { kind: 'vocabulary', prepared: preparedResult.value },
+    report: report.value,
+  });
+};
+
 const runLegacyVocabularyRecordRegrade = (
   input: RegradeInput,
   rootDir: string,
@@ -3054,12 +3646,13 @@ const loadPlanForInput = async (
 
 const reportWithCheckedHistorySummary = (
   report: RegradeReport,
-  historyPath: string
+  historyPath: string,
+  schemaVersion: number
 ): RegradeReport => ({
   ...report,
   history: {
     path: historyPath,
-    schemaVersion: REGRADE_HISTORY_SCHEMA_VERSION,
+    schemaVersion,
     status: 'checked',
   },
 });
@@ -3089,7 +3682,11 @@ const checkGraduatedRegradeHistory = (
     );
   }
   return validateRegradeReport(
-    reportWithCheckedHistorySummary(lastRun.report, artifact.value.path)
+    reportWithCheckedHistorySummary(
+      lastRun.report,
+      artifact.value.path,
+      artifact.value.schemaVersion
+    )
   );
 };
 
@@ -3104,6 +3701,7 @@ const runCheckRegradePlan = async (
       if (historyPath.isOk()) {
         return checkGraduatedRegradeHistory(historyPath.value);
       }
+      return historyPath;
     }
     return planPath;
   }
@@ -3114,24 +3712,17 @@ const runCheckRegradePlan = async (
   const loaded = {
     value: { artifact: artifact.value, path: planPath.value },
   };
-  const report = await runPlanArtifactDryRun({
+  const prepared = await preparePlanArtifactRun({
     artifact: loaded.value.artifact,
     includeEntries: input.includeEntries,
     rootDir,
   });
-  if (report.isErr()) {
-    return report;
+  if (prepared.isErr()) {
+    return prepared;
   }
-  const status = planStatusForReport(
-    loaded.value.artifact,
-    report.value,
-    rootDir
-  );
-  const checked = reportWithPlanSummary(
-    report.value,
-    loaded.value.artifact,
-    status
-  );
+  const { report } = prepared.value;
+  const status = planStatusForReport(loaded.value.artifact, report, rootDir);
+  const checked = reportWithPlanSummary(report, loaded.value.artifact, status);
   if (status === 'stale') {
     return Result.err(
       new ValidationError(
@@ -3164,29 +3755,32 @@ const runPreviewRegradePlan = async (
   if (loaded.isErr()) {
     return loaded;
   }
-  const report = await runPlanArtifactDryRun({
+  const prepared = await preparePlanArtifactRun({
     artifact: loaded.value.artifact,
     includeEntries: input.includeEntries,
     rootDir,
   });
-  if (report.isErr()) {
-    return report;
+  if (prepared.isErr()) {
+    return prepared;
   }
+  const { report } = prepared.value;
   return validateRegradeReport(
     reportWithPlanSummary(
-      report.value,
+      report,
       loaded.value.artifact,
-      planStatusForReport(loaded.value.artifact, report.value, rootDir)
+      planStatusForReport(loaded.value.artifact, report, rootDir)
     )
   );
 };
 
 const writeRegradeHistory = (params: {
   readonly artifact: RegradePlanArtifact;
+  readonly changedFiles: readonly RegradeChangedFileEvidence[];
   readonly completedReport: RegradeReport;
   readonly planPath: string;
   readonly report: RegradeReport;
   readonly rootDir: string;
+  readonly sourceRevision: string;
 }): TrailsResult<RegradeHistorySummary, Error> => {
   const absolutePath = regradeHistoryPathForPlan(
     params.rootDir,
@@ -3207,37 +3801,27 @@ const writeRegradeHistory = (params: {
   }
   const appended = appendRegradeHistoryRun({
     artifact: params.artifact,
+    changedFiles: params.changedFiles,
     completedReport: params.completedReport,
     report: params.report,
     rootDir: params.rootDir,
+    sourceRevision: params.sourceRevision,
   });
   if (appended.isErr()) {
     return appended;
   }
-  try {
-    // Apply always consumes the active plan, replay included: the plan is a
-    // single-use apply intent, and the consolidated history already records
-    // the run the replay repeats.
-    rmSync(params.planPath, { force: true });
-  } catch (error) {
-    try {
-      if (priorHistoryBytes === undefined) {
-        rmSync(absolutePath, { force: true });
-      } else {
-        writeFileSync(absolutePath, priorHistoryBytes);
-      }
-    } catch {
-      // Best-effort rollback; the surfaced error below preserves the primary failure.
-    }
-    return Result.err(
-      new InternalError('Failed to remove active Regrade plan.', {
-        ...(error instanceof Error ? { cause: error } : {}),
-        context: {
-          history: appended.value.path,
-          plan: rootRelativePath(params.rootDir, params.planPath),
-        },
-      })
-    );
+  // Apply always consumes the active plan, replay included: the plan is a
+  // single-use apply intent, and the consolidated history already records
+  // the run the replay repeats.
+  const consumed = consumeActiveRegradePlanAfterHistoryWrite({
+    absoluteHistoryPath: absolutePath,
+    absolutePlanPath: params.planPath,
+    historyPath: appended.value.path,
+    planPath: rootRelativePath(params.rootDir, params.planPath),
+    priorHistoryBytes,
+  });
+  if (consumed.isErr()) {
+    return consumed;
   }
   return appended;
 };
@@ -3260,6 +3844,87 @@ const historyReportForAppliedPlan = (
       }),
 });
 
+/**
+ * Re-read the active plan after preparation and before mutation.
+ *
+ * @internal
+ */
+export const reloadPreparedRegradePlan = async (params: {
+  readonly input: RegradeApplyPlanInput;
+  readonly loaded: {
+    readonly artifact: RegradePlanArtifact;
+    readonly path: string;
+  };
+  readonly rootDir: string;
+}): Promise<TrailsResult<RegradePlanArtifact, Error>> => {
+  const current = await loadPlanForInput(params.input, params.rootDir);
+  if (current.isErr()) {
+    return current;
+  }
+  const unchanged = validatePreparedRegradePlanArtifact({
+    current: current.value.artifact,
+    currentPath: current.value.path,
+    expected: params.loaded.artifact,
+    expectedPath: params.loaded.path,
+  });
+  return unchanged.isErr() ? unchanged : Result.ok(current.value.artifact);
+};
+
+const applyPreparedPlanRun = async (params: {
+  readonly artifact: RegradePlanArtifact;
+  readonly includeEntries: RegradeInput['includeEntries'];
+  readonly prepared: PreparedPlanRun;
+  readonly rootDir: string;
+}): Promise<TrailsResult<RegradeReport, Error>> => {
+  if (params.artifact.plan.kind === 'class') {
+    if (params.prepared.kind !== 'class') {
+      return Result.err(new InternalError('Prepared Regrade kind changed.'));
+    }
+    const classSet = await loadWardenRegradeClasses(params.rootDir);
+    if (classSet.diagnostics.length > 0) {
+      return Result.err(
+        new InternalError('Failed to load Regrade project Warden rules.', {
+          context: {
+            diagnostics: classSet.diagnostics,
+            rootDir: params.rootDir,
+          },
+        })
+      );
+    }
+    const identity = preparedRegradeRunIdentity({
+      artifact: params.artifact,
+      classIds: classSet.classes.map((regradeClass) => regradeClass.id),
+      classes: classSet.classes,
+      includeEntries: params.includeEntries,
+      rootDir: params.rootDir,
+    });
+    return identity.isErr()
+      ? identity
+      : applyPreparedRegradeRun(params.prepared.prepared.run, identity.value);
+  }
+  if (params.prepared.kind !== 'vocabulary') {
+    return Result.err(new InternalError('Prepared Regrade kind changed.'));
+  }
+  const identity = preparedRegradeRunIdentity({
+    artifact: params.artifact,
+    includeEntries: params.includeEntries,
+    rootDir: params.rootDir,
+  });
+  if (identity.isErr()) {
+    return identity;
+  }
+  const { prepared } = params.prepared;
+  return runResolvedVocabularyPlan({
+    apply: true,
+    currentIdentity: identity.value,
+    includeEntries: params.includeEntries,
+    plan: params.artifact.plan,
+    prepared,
+    preserveInventory: prepared.preserveInventory,
+    rootDir: params.rootDir,
+  });
+};
+
 const runApplyRegradePlan = async (
   input: RegradeApplyPlanInput,
   rootDir: string,
@@ -3275,17 +3940,18 @@ const runApplyRegradePlan = async (
   if (governedPlanValidation.isErr()) {
     return governedPlanValidation;
   }
-  const dryRunReport = await runPlanArtifactDryRun({
+  const preparedRun = await preparePlanArtifactRun({
     artifact: loaded.value.artifact,
     includeEntries: input.includeEntries,
     rootDir,
   });
-  if (dryRunReport.isErr()) {
-    return dryRunReport;
+  if (preparedRun.isErr()) {
+    return preparedRun;
   }
+  const dryRunReport = preparedRun.value.report;
   const status = planStatusForReport(
     loaded.value.artifact,
-    dryRunReport.value,
+    dryRunReport,
     rootDir
   );
   if (status === 'stale') {
@@ -3300,62 +3966,99 @@ const runApplyRegradePlan = async (
   }
   if (shouldDryRun) {
     return validateRegradeReport(
-      reportWithPlanSummary(dryRunReport.value, loaded.value.artifact, status)
+      reportWithPlanSummary(dryRunReport, loaded.value.artifact, status)
     );
   }
 
-  const planBody = loaded.value.artifact.plan;
-  let applied: TrailsResult<RegradeReport, Error>;
-  if (planBody.kind === 'class') {
-    applied = await runClassPlanRegradeRun({
-      apply: true,
-      includeEntries: input.includeEntries,
-      plan: planBody,
-      rootDir,
-    });
-  } else {
-    const preserveResult = await deriveLiveApiPreserveInventory(
-      planBody,
-      rootDir
-    );
-    if (preserveResult.isErr()) {
-      return preserveResult;
-    }
-    applied = runResolvedVocabularyPlan({
-      apply: true,
-      includeEntries: input.includeEntries,
-      plan: planBody,
-      preserveInventory: preserveResult.value,
-      rootDir,
-    });
+  const currentPlan = await reloadPreparedRegradePlan({
+    input,
+    loaded: loaded.value,
+    rootDir,
+  });
+  if (currentPlan.isErr()) {
+    return currentPlan;
+  }
+  const activeArtifact = currentPlan.value;
+
+  // Receipt persistence is mandatory for apply. Resolve its Git-owned source
+  // identity before mutating any source so failure leaves the tree untouched.
+  const receiptPlan = validateRegradeReceiptPlan(activeArtifact);
+  if (receiptPlan.isErr()) {
+    return receiptPlan;
+  }
+  const sourceRevision = resolveRegradeSourceRevision(rootDir);
+  if (sourceRevision.isErr()) {
+    return sourceRevision;
   }
+
+  const beforeChangedFiles = captureRegradeChangedFilesBefore({
+    artifact: activeArtifact,
+    report: dryRunReport,
+    rootDir,
+  });
+  if (beforeChangedFiles.isErr()) {
+    return beforeChangedFiles;
+  }
+
+  const planBody = activeArtifact.plan;
+  const sourceSnapshots = snapshotRegradeSources({
+    optionalPaths:
+      planBody.kind === 'vocabulary'
+        ? (planBody.fileRenames ?? []).flatMap((rename) => [
+            rename.from,
+            rename.to,
+          ])
+        : [],
+    reports: [dryRunReport],
+    rootDir,
+  });
+  if (sourceSnapshots.isErr()) {
+    return sourceSnapshots;
+  }
+  const rollbackApplyError = (error: Error): TrailsResult<never, Error> =>
+    regradeApplyErrorAfterRollback(error, sourceSnapshots.value);
+  const applied = await applyPreparedPlanRun({
+    artifact: activeArtifact,
+    includeEntries: input.includeEntries,
+    prepared: preparedRun.value.prepared,
+    rootDir,
+  });
   if (applied.isErr()) {
-    return applied;
+    return rollbackApplyError(applied.error);
+  }
+  const changedFiles = completeRegradeChangedFiles({
+    before: beforeChangedFiles.value,
+    rootDir,
+  });
+  if (changedFiles.isErr()) {
+    return rollbackApplyError(changedFiles.error);
   }
   const completionReport = await runPlanArtifactDryRun({
-    artifact: loaded.value.artifact,
+    artifact: activeArtifact,
     includeEntries: input.includeEntries,
     rootDir,
   });
   if (completionReport.isErr()) {
-    return completionReport;
+    return rollbackApplyError(completionReport.error);
   }
   // Keep the pre-apply occurrence evidence that explains what this run changed,
   // while carrying the completed counters and a separate post-apply source
   // stamp so a later no-op apply can still be recognized as a replay.
   const history = writeRegradeHistory({
-    artifact: loaded.value.artifact,
+    artifact: activeArtifact,
+    changedFiles: changedFiles.value,
     completedReport: completionReport.value,
     planPath: loaded.value.path,
-    report: historyReportForAppliedPlan(dryRunReport.value, applied.value),
+    report: historyReportForAppliedPlan(dryRunReport, applied.value),
     rootDir,
+    sourceRevision: sourceRevision.value,
   });
   if (history.isErr()) {
-    return history;
+    return rollbackApplyError(history.error);
   }
   return validateRegradeReport(
     reportWithHistorySummary(
-      reportWithPlanSummary(applied.value, loaded.value.artifact, status),
+      reportWithPlanSummary(applied.value, activeArtifact, status),
       history.value
     )
   );
@@ -3542,30 +4245,37 @@ export const planRegradeTrail = trail('plan.regrade', {
   cli: { path: ['regrade', 'plan'] },
   description: 'Write or update a reviewed Regrade plan',
   implementation: async (input, ctx) => {
-    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    const lifecycle = new RegradeLifecycleTracker({ progress: ctx.progress });
+    const rootDirResult = await lifecycle.run('resolve-root', () =>
+      resolveTrailRootDir(input.rootDir, ctx.cwd)
+    );
     if (rootDirResult.isErr()) {
-      return rootDirResult;
+      return Result.err(rootDirResult.error);
     }
 
-    const configResult = await loadRegradeConfig({
-      ...(input.configPath === undefined
-        ? {}
-        : { configPath: input.configPath }),
-      env: ctx.env,
-      rootDir: rootDirResult.value,
-    });
+    const configResult = await lifecycle.run('load-config', () =>
+      loadRegradeConfig({
+        ...(input.configPath === undefined
+          ? {}
+          : { configPath: input.configPath }),
+        env: ctx.env,
+        rootDir: rootDirResult.value,
+      })
+    );
     if (configResult.isErr()) {
-      return configResult;
+      return Result.err(configResult.error);
     }
 
-    const result = await runPlanRegrade(
-      input,
-      rootDirResult.value,
-      configResult.value.config?.scope,
-      ctx.dryRun === true
+    const result = await lifecycle.run('derive-plan', () =>
+      runPlanRegrade(
+        input,
+        rootDirResult.value,
+        configResult.value.config?.scope,
+        ctx.dryRun === true
+      )
     );
     if (result.isErr()) {
-      return result;
+      return Result.err(result.error);
     }
     const output = regradePlanArtifactSchema.safeParse(result.value);
     if (!output.success) {
@@ -3575,11 +4285,11 @@ export const planRegradeTrail = trail('plan.regrade', {
         })
       );
     }
-    return Result.ok(output.data);
+    return Result.ok({ ...output.data, lifecycle: lifecycle.summary() });
   },
   input: regradePlanInputSchema,
   intent: 'write',
-  output: regradePlanArtifactSchema,
+  output: regradePlanCommandOutputSchema,
   permit: 'public',
 });
 
@@ -3650,13 +4360,18 @@ export const checkRegradeTrail = trail('check.regrade', {
   cli: { path: ['regrade', 'check'] },
   description: 'Check a saved Regrade plan gate without writing source',
   implementation: async (input, ctx) => {
-    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    const lifecycle = new RegradeLifecycleTracker({ progress: ctx.progress });
+    const rootDirResult = await lifecycle.run('resolve-root', () =>
+      resolveTrailRootDir(input.rootDir, ctx.cwd)
+    );
     if (rootDirResult.isErr()) {
-      return rootDirResult;
+      return Result.err(rootDirResult.error);
     }
-    const result = await runCheckRegradePlan(input, rootDirResult.value);
+    const result = await lifecycle.run('check-plan', () =>
+      runCheckRegradePlan(input, rootDirResult.value)
+    );
     if (result.isErr()) {
-      return result;
+      return Result.err(result.error);
     }
     const checked = {
       ...result.value,
@@ -3668,6 +4383,7 @@ export const checkRegradeTrail = trail('check.regrade', {
           '',
         status: 'passed' as const,
       },
+      lifecycle: lifecycle.summary(),
     };
     const output = validateOutput(regradeCheckOutputSchema, checked);
     if (output.isErr()) {
@@ -3685,15 +4401,23 @@ export const previewRegradeTrail = trail('preview.regrade', {
   cli: { path: ['regrade', 'preview'] },
   description: 'Preview a saved Regrade plan without writing source',
   implementation: async (input, ctx) => {
-    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    const lifecycle = new RegradeLifecycleTracker({ progress: ctx.progress });
+    const rootDirResult = await lifecycle.run('resolve-root', () =>
+      resolveTrailRootDir(input.rootDir, ctx.cwd)
+    );
     if (rootDirResult.isErr()) {
-      return rootDirResult;
+      return Result.err(rootDirResult.error);
     }
-    const result = await runPreviewRegradePlan(input, rootDirResult.value);
+    const result = await lifecycle.run('preview-plan', () =>
+      runPreviewRegradePlan(input, rootDirResult.value)
+    );
     if (result.isErr()) {
-      return result;
+      return Result.err(result.error);
     }
-    const output = validateOutput(regradeReportOutput, result.value);
+    const output = validateOutput(regradeLifecycleReportOutputSchema, {
+      ...result.value,
+      lifecycle: lifecycle.summary(),
+    });
     if (output.isErr()) {
       return Result.err(output.error);
     }
@@ -3701,7 +4425,7 @@ export const previewRegradeTrail = trail('preview.regrade', {
   },
   input: regradePlanReferenceInputSchema,
   intent: 'read',
-  output: regradeReportOutput,
+  output: regradeLifecycleReportOutputSchema,
   permit: 'public',
 });
 
@@ -3709,19 +4433,23 @@ export const applyRegradeTrail = trail('apply.regrade', {
   cli: { path: ['regrade', 'apply'] },
   description: 'Apply a saved Regrade plan and move it to history',
   implementation: async (input, ctx) => {
-    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    const lifecycle = new RegradeLifecycleTracker({ progress: ctx.progress });
+    const rootDirResult = await lifecycle.run('resolve-root', () =>
+      resolveTrailRootDir(input.rootDir, ctx.cwd)
+    );
     if (rootDirResult.isErr()) {
-      return rootDirResult;
+      return Result.err(rootDirResult.error);
     }
-    const result = await runApplyRegradePlan(
-      input,
-      rootDirResult.value,
-      ctx.dryRun === true
+    const result = await lifecycle.run('apply-plan', () =>
+      runApplyRegradePlan(input, rootDirResult.value, ctx.dryRun === true)
     );
     if (result.isErr()) {
-      return result;
+      return Result.err(result.error);
     }
-    const output = validateOutput(regradeReportOutput, result.value);
+    const output = validateOutput(regradeLifecycleReportOutputSchema, {
+      ...result.value,
+      lifecycle: lifecycle.summary(),
+    });
     if (output.isErr()) {
       return Result.err(output.error);
     }
@@ -3729,7 +4457,7 @@ export const applyRegradeTrail = trail('apply.regrade', {
   },
   input: regradeApplyPlanInputSchema,
   intent: 'write',
-  output: regradeReportOutput,
+  output: regradeLifecycleReportOutputSchema,
   permit: 'public',
 });
 
@@ -3739,17 +4467,18 @@ export const adjustRegradeTrail = trail('adjust.regrade', {
   description:
     'Pull a graduated Regrade transition back to an active plan for adjustment',
   implementation: async (input, ctx) => {
-    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    const lifecycle = new RegradeLifecycleTracker({ progress: ctx.progress });
+    const rootDirResult = await lifecycle.run('resolve-root', () =>
+      resolveTrailRootDir(input.rootDir, ctx.cwd)
+    );
     if (rootDirResult.isErr()) {
-      return rootDirResult;
+      return Result.err(rootDirResult.error);
     }
-    const result = await runAdjustRegrade(
-      input,
-      rootDirResult.value,
-      ctx.dryRun === true
+    const result = await lifecycle.run('adjust-plan', () =>
+      runAdjustRegrade(input, rootDirResult.value, ctx.dryRun === true)
     );
     if (result.isErr()) {
-      return result;
+      return Result.err(result.error);
     }
     const output = regradePlanArtifactSchema.safeParse(result.value);
     if (!output.success) {
@@ -3759,10 +4488,10 @@ export const adjustRegradeTrail = trail('adjust.regrade', {
         })
       );
     }
-    return Result.ok(output.data);
+    return Result.ok({ ...output.data, lifecycle: lifecycle.summary() });
   },
   input: regradeAdjustInputSchema,
   intent: 'write',
-  output: regradePlanArtifactSchema,
+  output: regradePlanCommandOutputSchema,
   permit: 'public',
 });