@ontrails/trails 1.0.0-beta.42 → 1.0.0-beta.43

package/src/trails/regrade.ts

@@ -15,19 +15,21 @@ import {
 import type { PathScope, Result as TrailsResult } from '@ontrails/core';
 import {
   createGovernedAstIdentifierRenameClasses,
-  listVocabularyRegradePlansFromRegistry,
   loadWardenRegradeClasses,
   readVocabularyTransitionRecord,
   regradeReportOutput,
+  runFileRenameRegrade,
   runRegrade,
   runVocabularyRegrade,
   transitionRecordReportWithSummary,
   vocabularyRegradeTransitionForInput,
   vocabularyDispositionValues,
   vocabularyRegradePlanSchema,
+  vocabularyRegradePlanForInput,
   writeVocabularyTransitionRecord,
 } from '@ontrails/regrade';
 import type {
+  FileRenameRegradeRun,
   RegradeApplySummary,
   RegradeReport,
   RegradeReportEntry,
@@ -37,6 +39,7 @@ import type {
   VocabularyRegradePlan,
   VocabularyPreserveInventoryEntry,
 } from '@ontrails/regrade';
+import { listGovernedVocabularyTransitions } from '@ontrails/warden';
 import { execFileSync } from 'node:child_process';
 import {
   existsSync,
@@ -47,9 +50,14 @@ import {
   writeFileSync,
 } from 'node:fs';
 import type { Dirent } from 'node:fs';
-import { basename, dirname, isAbsolute, join } from 'node:path';
+import { basename, dirname, extname, isAbsolute, join, posix } from 'node:path';
 import { z } from 'zod';
 
+import {
+  auditRegradeHistory,
+  regradeAuditInputSchema,
+  regradeAuditOutputSchema,
+} from '../regrade/audit.js';
 import { loadRegradeConfig } from '../regrade/config.js';
 import {
   REGRADE_HISTORY_SCHEMA_VERSION,
@@ -57,16 +65,24 @@ import {
   readRegradeHistoryArtifact,
   regradeHistoryPathForPlan,
   resolveRegradeHistoryPath,
+  validateGovernedRegradePlan,
   verifyRegradeHistoryRuns,
 } from '../regrade/history.js';
 import type { RegradeHistorySummary } from '../regrade/history.js';
 import { deriveLiveApiPreserveInventory } from '../regrade/live-api-preserve.js';
+import { deriveRegradePlanDerivation } from '../regrade/plan-derivation.js';
+import {
+  regradeApplyErrorAfterRollback,
+  snapshotRegradeSources,
+} from '../regrade/source-transaction.js';
 import {
   REGRADE_PLAN_SCHEMA_VERSION,
+  canonicalJsonStringify,
+  currentRegradeSourceHashMatches,
+  isGeneratedRegradeArtifactPath,
   regradePlanArtifactSchema,
   regradePlanPathForPlan,
   regradeSourceHash,
-  regradeSourceHashMatches,
   rootRelativePath,
 } from '../regrade/plan-artifact.js';
 import type {
@@ -88,6 +104,21 @@ const regradePathScopeInputSchema = pathScopeSchema.extend({
   include: pathScopeSchema.shape.include.describe(
     'Root-relative path patterns to include in vocabulary regrade mode'
   ),
+  policyClassified: z
+    .array(
+      z.object({
+        disposition: z.enum(vocabularyDispositionValues),
+        expectMatches: z.boolean().optional(),
+        paths: z.array(z.string().min(1)).min(1),
+        reason: z.string().min(1),
+      })
+    )
+    .optional()
+    .describe('Protected paths scanned and counted without default rewrites'),
+  teachingSurfaces: z
+    .array(z.string().min(1))
+    .optional()
+    .describe('Expected current teaching-surface path patterns'),
 });
 
 const regradePreserveRuleInputSchema = z.object({
@@ -112,6 +143,11 @@ const regradePreserveInputSchema = z.union([
   regradePreserveRuleInputSchema,
 ]);
 
+const regradeFileRenameInputSchema = z.object({
+  from: z.string().min(1).describe('Root-relative source file path'),
+  to: z.string().min(1).describe('Root-relative target file path'),
+});
+
 const regradeInputSchema = regradePathScopeInputSchema.extend({
   apply: z
     .boolean()
@@ -131,6 +167,10 @@ const regradeInputSchema = regradePathScopeInputSchema.extend({
     .string()
     .optional()
     .describe('Path to a Trails config file with regrade defaults'),
+  fileRenames: z
+    .array(regradeFileRenameInputSchema)
+    .optional()
+    .describe('Governed file moves with references derived from scope'),
   from: z
     .string()
     .min(1)
@@ -227,6 +267,10 @@ const regradePlanInputSchema = regradePathScopeInputSchema.extend({
     .boolean()
     .default(false)
     .describe('Stage wide-net review candidates in the saved plan'),
+  fileRenames: z
+    .array(regradeFileRenameInputSchema)
+    .optional()
+    .describe('Governed file moves with references derived from scope'),
   fresh: z
     .boolean()
     .default(false)
@@ -297,7 +341,7 @@ const regradeAdjustInputSchema = z.object({
   transition: z
     .string()
     .min(1)
-    .describe('Graduated transition name, e.g. facet-to-trailhead'),
+    .describe('Graduated transition name, e.g. <transition-name>'),
 });
 
 type RegradePlanInput = z.output<typeof regradePlanInputSchema>;
@@ -308,6 +352,7 @@ type RegradeApplyPlanInput = z.output<typeof regradeApplyPlanInputSchema>;
 type RegradeAdjustInput = z.output<typeof regradeAdjustInputSchema>;
 
 const hasVocabularyInput = (input: RegradeInput) =>
+  input.fileRenames !== undefined ||
   input.from !== undefined ||
   input.check ||
   input.include !== undefined ||
@@ -315,6 +360,8 @@ const hasVocabularyInput = (input: RegradeInput) =>
   input.overrides !== undefined ||
   input.planRecord !== undefined ||
   input.preserve !== undefined ||
+  input.policyClassified !== undefined ||
+  input.teachingSurfaces !== undefined ||
   input.to !== undefined;
 
 const classModeCollection = (
@@ -376,6 +423,15 @@ const vocabularyProseExtensions: readonly string[] = [
   '.txt',
 ] as const;
 
+const vocabularyEvidenceExtensions: readonly string[] = [
+  ...symbolSourceExtensions,
+  ...vocabularyProseExtensions,
+  '.json',
+  '.jsonc',
+  '.yaml',
+  '.yml',
+] as const;
+
 const normalizeExtension = (extension: string): string =>
   extension === '' || extension.startsWith('.') ? extension : `.${extension}`;
 
@@ -457,6 +513,14 @@ const symbolOccurrenceIsPreserved = (
     preserveRuleMatchesSymbolOccurrence(rule, occurrence)
   ) ?? false;
 
+const symbolOccurrenceIsPolicyClassified = (
+  scope: VocabularyRegradePlan['scope'] | undefined,
+  path: string
+): boolean =>
+  scope?.policyClassified?.some((policy) =>
+    matchesAnyPathGlob(path, policy.paths)
+  ) ?? false;
+
 const vocabularyScopeFromConfig = (
   scope: RegradeConfigScope | undefined
 ): VocabularyRegradePlan['scope'] | undefined =>
@@ -492,9 +556,9 @@ const vocabularyPreserveFromInput = (
 const vocabularyRegistryPlanForInput = (
   input: RegradeInput
 ): VocabularyRegradePlan | undefined =>
-  listVocabularyRegradePlansFromRegistry().find(
-    (plan) => plan.from === input.from && plan.to === input.to
-  );
+  input.from === undefined || input.to === undefined
+    ? undefined
+    : (vocabularyRegradePlanForInput(input.from, input.to) ?? undefined);
 
 const uniqueSorted = (values: readonly string[]): readonly string[] =>
   [...new Set(values)].toSorted((left, right) => left.localeCompare(right));
@@ -511,10 +575,22 @@ const mergeScopeList = (
   return merged.length === 0 ? undefined : merged;
 };
 
+const scopePathsOverlap = (left: string, right: string): boolean =>
+  left === right ||
+  matchesAnyPathGlob(left, [right]) ||
+  matchesAnyPathGlob(right, [left]);
+
 const mergeVocabularyScope = (
   registryScope: VocabularyRegradePlan['scope'] | undefined,
   configScope: VocabularyRegradePlan['scope'] | undefined,
-  input: Pick<RegradeInput, 'exclude' | 'extensions' | 'include'>
+  input: Pick<
+    RegradeInput,
+    | 'exclude'
+    | 'extensions'
+    | 'include'
+    | 'policyClassified'
+    | 'teachingSurfaces'
+  >
 ): VocabularyRegradePlan['scope'] | undefined => {
   const callerExclude = input.exclude ?? configScope?.exclude;
   const callerInclude = input.include ?? configScope?.include;
@@ -522,20 +598,37 @@ const mergeVocabularyScope = (
     input.extensions ?? configScope?.extensions ?? registryScope?.extensions;
   const exclude = mergeScopeList(registryScope?.exclude, callerExclude);
   const include = mergeScopeList(registryScope?.include, callerInclude);
+  const policyClassified = [
+    ...(registryScope?.policyClassified ?? [])
+      .map((policy) => ({
+        ...policy,
+        paths: policy.paths.filter(
+          (path) =>
+            !callerExclude?.some((excludedPath) =>
+              scopePathsOverlap(path, excludedPath)
+            )
+        ),
+      }))
+      .filter((policy) => policy.paths.length > 0),
+    ...(input.policyClassified ?? []),
+  ];
+  const teachingSurfaces = mergeScopeList(
+    registryScope?.teachingSurfaces,
+    input.teachingSurfaces
+  );
 
-  if (
-    exclude === undefined &&
-    extensions === undefined &&
-    include === undefined
-  ) {
-    return undefined;
-  }
-
-  return {
-    ...(exclude === undefined ? {} : { exclude }),
-    ...(extensions === undefined ? {} : { extensions }),
-    ...(include === undefined ? {} : { include }),
+  const fields = {
+    exclude,
+    extensions,
+    include,
+    policyClassified:
+      policyClassified.length === 0 ? undefined : policyClassified,
+    teachingSurfaces,
   };
+  const scope = Object.fromEntries(
+    Object.entries(fields).filter(([, value]) => value !== undefined)
+  ) as NonNullable<VocabularyRegradePlan['scope']>;
+  return Object.keys(scope).length === 0 ? undefined : scope;
 };
 
 const mergeNumericRecords = (
@@ -723,11 +816,16 @@ const transitionRunReportForRegradeReport = (
       reasons,
       remaining: open,
       remainingByDisposition,
-      status: open === 0 ? 'green' : 'open',
+      status: open === 0 && reasons.length === 0 ? 'green' : 'open',
     },
     modified,
     open,
+    scopeTiers: {
+      'in-scope': report.rewritten + report.review,
+      'policy-classified': 0,
+    },
     skipped: report.skipped,
+    teachingSurfaces: { expected: [], missing: [], touched: [] },
   };
 };
 
@@ -760,11 +858,20 @@ const mergeTransitionRunReportWithSymbol = (
       reasons,
       remaining: open,
       remainingByDisposition,
-      status: open === 0 ? 'green' : 'open',
+      status: open === 0 && reasons.length === 0 ? 'green' : 'open',
     },
     modified,
     open,
+    scopeTiers: {
+      'in-scope':
+        vocabularyReport.scopeTiers['in-scope'] +
+        symbolRunReport.scopeTiers['in-scope'],
+      'policy-classified':
+        vocabularyReport.scopeTiers['policy-classified'] +
+        symbolRunReport.scopeTiers['policy-classified'],
+    },
     skipped: vocabularyReport.skipped + symbolRunReport.skipped,
+    teachingSurfaces: vocabularyReport.teachingSurfaces,
   };
 };
 
@@ -877,18 +984,18 @@ const vocabularySymbolCollection = (
   };
 };
 
-const vocabularyProseScope = (
+const vocabularyEvidenceScope = (
   scope: VocabularyRegradePlan['scope'] | undefined
 ): NonNullable<VocabularyRegradePlan['scope']> | null => {
   const explicitExtensions = scope?.extensions !== undefined;
   const extensions =
     scope?.extensions === undefined
-      ? vocabularyProseExtensions
+      ? vocabularyEvidenceExtensions
       : uniqueSorted(
           scope.extensions
             .map(normalizeExtension)
             .filter((extension) =>
-              vocabularyProseExtensions.includes(extension)
+              vocabularyEvidenceExtensions.includes(extension)
             )
         );
 
@@ -903,13 +1010,19 @@ const vocabularyProseScope = (
       ? {}
       : { ignoredDirectories: scope.ignoredDirectories }),
     ...(scope?.include === undefined ? {} : { include: scope.include }),
+    ...(scope?.policyClassified === undefined
+      ? {}
+      : { policyClassified: scope.policyClassified }),
+    ...(scope?.teachingSurfaces === undefined
+      ? {}
+      : { teachingSurfaces: scope.teachingSurfaces }),
   };
 };
 
-const vocabularyProsePlan = (
+const vocabularyEvidencePlan = (
   plan: VocabularyRegradePlan
 ): VocabularyRegradePlan | null => {
-  const scope = vocabularyProseScope(plan.scope);
+  const scope = vocabularyEvidenceScope(plan.scope);
   if (scope === null) {
     return null;
   }
@@ -917,6 +1030,65 @@ const vocabularyProsePlan = (
   return { ...plan, scope };
 };
 
+const withoutNotSelectedSourceCount = (
+  counts: Readonly<Record<string, number>>
+): Readonly<Record<string, number>> =>
+  Object.fromEntries(
+    Object.entries(counts).filter(
+      ([reason]) => reason !== 'not-selected-source'
+    )
+  );
+
+const withoutVocabularySourceFilterSkips = (
+  report: RegradeReport | null
+): RegradeReport | null => {
+  const rejected = report?.skipsByReason['not-selected-source'] ?? 0;
+  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
+      ),
+    },
+    skipped: Math.max(0, report.skipped - rejected),
+    skipsByReason: withoutNotSelectedSourceCount(report.skipsByReason),
+  };
+};
+
+const vocabularyEvidenceSource = (
+  path: string,
+  scope: VocabularyRegradePlan['scope'] | undefined
+): boolean =>
+  vocabularyProseExtensions.includes(extname(path)) ||
+  symbolOccurrenceIsPolicyClassified(scope, path);
+
+const vocabularyProseEngineApplies = (
+  scope: VocabularyRegradePlan['scope'] | undefined
+): boolean =>
+  scope?.extensions === undefined ||
+  scope.extensions.some((extension) =>
+    vocabularyProseExtensions.includes(normalizeExtension(extension))
+  );
+
 const mergeVocabularyOverrides = (
   registryPlan: VocabularyRegradePlan | undefined,
   input: z.output<typeof regradeInputSchema>
@@ -946,9 +1118,67 @@ const vocabularyIntentForInput = (
   return registryPlan?.intent;
 };
 
+const classifiedOverrideError = (
+  input: RegradeInput & { readonly from: string; readonly to: string }
+): ValidationError | undefined => {
+  const transition = vocabularyRegradeTransitionForInput(input.from, input.to);
+  return transition?.target.kind === 'classified' &&
+    input.overrides !== undefined
+    ? new ValidationError(
+        'Classified governed vocabulary transitions are review-only and cannot accept rewrite overrides.'
+      )
+    : undefined;
+};
+
+const governedTargetError = (
+  input: RegradeInput & { readonly from: string; readonly to: string }
+): ValidationError | undefined => {
+  const governedFormTransition = listGovernedVocabularyTransitions().find(
+    (candidate) =>
+      candidate.from !== input.from &&
+      (candidate.oldForms.includes(input.from) ||
+        candidate.reviewForms.includes(input.from))
+  );
+  if (governedFormTransition !== undefined) {
+    return new ValidationError(
+      `Governed vocabulary form "${input.from}" belongs to transition "${governedFormTransition.id}". Plan from its canonical source "${governedFormTransition.from}" instead.`
+    );
+  }
+  const transition = listGovernedVocabularyTransitions().find(
+    (candidate) => candidate.from === input.from
+  );
+  if (
+    transition === undefined ||
+    vocabularyRegradeTransitionForInput(input.from, input.to) !== undefined
+  ) {
+    return undefined;
+  }
+  const expectedTargets =
+    transition.target.kind === 'single'
+      ? [transition.target.to]
+      : transition.target.options.map((option) => option.to);
+  return new ValidationError(
+    `Governed vocabulary transition "${transition.id}" does not define target "${input.to}". Expected ${expectedTargets.map((target) => `"${target}"`).join(' or ')}`
+  );
+};
+
+const registryFileRenamesForRoot = (
+  registryPlan: VocabularyRegradePlan | undefined,
+  rootDir: string | undefined
+): VocabularyRegradePlan['fileRenames'] | undefined => {
+  const fileRenames = registryPlan?.fileRenames?.filter(
+    (rename) =>
+      rootDir === undefined ||
+      existsSync(join(rootDir, rename.from)) ||
+      existsSync(join(rootDir, rename.to))
+  );
+  return fileRenames?.length === 0 ? undefined : fileRenames;
+};
+
 const buildVocabularyPlan = (
   input: RegradeInput,
-  configScope?: VocabularyRegradePlan['scope']
+  configScope?: VocabularyRegradePlan['scope'],
+  rootDir?: string
 ): TrailsResult<VocabularyRegradePlan, ValidationError> => {
   if (input.from === undefined || input.to === undefined) {
     return Result.err(
@@ -964,11 +1194,29 @@ const buildVocabularyPlan = (
   }
 
   const preserve = vocabularyPreserveFromInput(input.preserve);
+  const targetError = governedTargetError({
+    ...input,
+    from: input.from,
+    to: input.to,
+  });
+  if (targetError !== undefined) {
+    return Result.err(targetError);
+  }
   const registryPlan = vocabularyRegistryPlanForInput(input);
+  const overrideError = classifiedOverrideError({
+    ...input,
+    from: input.from,
+    to: input.to,
+  });
+  if (overrideError !== undefined) {
+    return Result.err(overrideError);
+  }
   const intent = vocabularyIntentForInput(input, registryPlan);
   const overrides = mergeVocabularyOverrides(registryPlan, input);
   const preserveRules = mergeVocabularyPreserveRules(registryPlan, preserve);
   const scope = mergeVocabularyScope(registryPlan?.scope, configScope, input);
+  const fileRenames =
+    input.fileRenames ?? registryFileRenamesForRoot(registryPlan, rootDir);
 
   return Result.ok({
     ...(registryPlan?.caseSensitive === undefined
@@ -977,6 +1225,7 @@ const buildVocabularyPlan = (
     ...(registryPlan?.deferForms === undefined
       ? {}
       : { deferForms: registryPlan.deferForms }),
+    ...(fileRenames === undefined ? {} : { fileRenames }),
     from: input.from,
     id: registryPlan?.id ?? `vocabulary:${input.from}->${input.to}`,
     kind: 'vocabulary',
@@ -988,6 +1237,33 @@ const buildVocabularyPlan = (
   });
 };
 
+const withDerivedTeachingSurfaceInventory = (params: {
+  readonly plan: VocabularyRegradePlan;
+  readonly report: RegradeReport;
+}): VocabularyRegradePlan => {
+  const expected = params.plan.scope?.teachingSurfaces;
+  if (expected === undefined) {
+    return params.plan;
+  }
+  const teachingSurfaces = uniqueSorted(
+    (params.report.run?.ledger.occurrences ?? [])
+      .filter(
+        (occurrence) =>
+          occurrence.scopeTier === 'in-scope' &&
+          !isGeneratedRegradeArtifactPath(occurrence.path) &&
+          matchesAnyPathGlob(occurrence.path, expected)
+      )
+      .map((occurrence) => occurrence.path)
+  );
+  const scope = { ...params.plan.scope };
+  if (teachingSurfaces.length === 0) {
+    delete scope.teachingSurfaces;
+  } else {
+    scope.teachingSurfaces = teachingSurfaces;
+  }
+  return { ...params.plan, scope };
+};
+
 const regradeRootNotFound = (rootDir: string) =>
   Result.err(
     new NotFoundError(
@@ -1078,6 +1354,10 @@ const runGovernedSymbolRegrade = (params: {
       },
       {
         shouldPreserve: (occurrence) =>
+          symbolOccurrenceIsPolicyClassified(
+            params.plan.scope,
+            occurrence.path
+          ) ||
           symbolOccurrenceIsPreserved(params.plan.preserve, {
             end: occurrence.end,
             form: occurrence.from,
@@ -1157,7 +1437,11 @@ const reportWithHistorySummary = (
 ): RegradeReport => ({
   ...report,
   history: {
+    id: params.id,
     path: params.path,
+    ...(params.provenance === undefined
+      ? {}
+      : { provenance: params.provenance }),
     schemaVersion: params.schemaVersion,
     status: params.status,
   },
@@ -1166,6 +1450,7 @@ const reportWithHistorySummary = (
 const authoredPlanFieldKeys = [
   'caseSensitive',
   'deferForms',
+  'fileRenames',
   'id',
   'intent',
   'overrides',
@@ -1179,6 +1464,7 @@ const isAuthoredPlanField = (
 ): boolean => {
   switch (key) {
     case 'intent':
+    case 'fileRenames':
     case 'overrides':
     case 'preserve': {
       return input[key] !== undefined;
@@ -1187,7 +1473,9 @@ const isAuthoredPlanField = (
       return (
         input.exclude !== undefined ||
         input.extensions !== undefined ||
-        input.include !== undefined
+        input.include !== undefined ||
+        input.policyClassified !== undefined ||
+        input.teachingSurfaces !== undefined
       );
     }
     default: {
@@ -1209,6 +1497,7 @@ const regradePlanProvenanceForInput = (
   for (const key of [
     'caseSensitive',
     'deferForms',
+    'fileRenames',
     'id',
     'intent',
     'overrides',
@@ -1256,6 +1545,7 @@ const preserveAuthoredPlanProvenance = (
 };
 
 const buildRegradePlanArtifact = (params: {
+  readonly derivation?: RegradePlanArtifact['derivation'];
   readonly expansion?: RegradePlanArtifact['expansion'];
   readonly input: RegradePlanInput;
   readonly plan: VocabularyRegradePlan;
@@ -1265,6 +1555,9 @@ const buildRegradePlanArtifact = (params: {
 }): RegradePlanArtifact => {
   const absolutePath = regradePlanPathForPlan(params.rootDir, params.plan);
   return {
+    ...(params.derivation === undefined
+      ? {}
+      : { derivation: params.derivation }),
     ...(params.expansion === undefined ? {} : { expansion: params.expansion }),
     kind: 'regrade-plan',
     path: rootRelativePath(params.rootDir, absolutePath),
@@ -1479,9 +1772,27 @@ const resolveRegradePlanPath = (
 
 const planStatusForReport = (
   artifact: RegradePlanArtifact,
-  report: RegradeReport
-): 'active' | 'stale' =>
-  regradeSourceHashMatches(artifact.sourceHash, report) ? 'active' : 'stale';
+  report: RegradeReport,
+  rootDir: string
+): 'active' | 'stale' => {
+  if (!currentRegradeSourceHashMatches(artifact.sourceHash, report)) {
+    return 'stale';
+  }
+  if (artifact.plan.kind === 'class' || artifact.derivation === undefined) {
+    return 'active';
+  }
+  const current = deriveRegradePlanDerivation({
+    plan: artifact.plan,
+    preserveInventory: report.run?.preserveInventory ?? [],
+    provenance: artifact.provenance,
+    report,
+    rootDir,
+  });
+  return canonicalJsonStringify(current) ===
+    canonicalJsonStringify(artifact.derivation)
+    ? 'active'
+    : 'stale';
+};
 
 const regradePlanGateContext = (
   report: RegradeReport
@@ -1529,6 +1840,182 @@ const persistVocabularyRecord = (params: {
   );
 };
 
+const withFileRenameEvidence = (params: {
+  readonly plan: VocabularyRegradePlan;
+  readonly report: RegradeReport & {
+    readonly run: NonNullable<RegradeReport['run']>;
+  };
+  readonly run: FileRenameRegradeRun;
+}): RegradeReport => {
+  const vocabularyPaths = params.report.run.ledger.occurrences
+    .filter((occurrence) => occurrence.scopeTier === 'in-scope')
+    .map((occurrence) => occurrence.path);
+  const remainingPolicyPaths = new Map<string, number>();
+  for (const path of params.run.policyOccurrencePaths) {
+    remainingPolicyPaths.set(path, (remainingPolicyPaths.get(path) ?? 0) + 1);
+  }
+  const fileInScopePaths = params.run.occurrencePaths.filter((path) => {
+    const remaining = remainingPolicyPaths.get(path) ?? 0;
+    if (remaining === 0) {
+      return true;
+    }
+    remainingPolicyPaths.set(path, remaining - 1);
+    return false;
+  });
+  const evidencePaths = [...vocabularyPaths, ...fileInScopePaths];
+  const expected = uniqueSorted(params.plan.scope?.teachingSurfaces ?? []);
+  const touched = expected.filter((pattern) =>
+    evidencePaths.some((path) => matchesAnyPathGlob(path, [pattern]))
+  );
+  const missing = expected.filter((pattern) => !touched.includes(pattern));
+  const vocabularyPolicyPaths = params.report.run.ledger.occurrences
+    .filter((occurrence) => occurrence.scopeTier === 'policy-classified')
+    .map((occurrence) => occurrence.path);
+  const policyPaths = [
+    ...vocabularyPolicyPaths,
+    ...params.run.policyOccurrencePaths,
+  ];
+  const policyEvidenceMissing =
+    params.plan.scope?.policyClassified?.some(
+      (policy) =>
+        policy.expectMatches === true &&
+        !policyPaths.some((path) => matchesAnyPathGlob(path, policy.paths))
+    ) ?? false;
+  const evidenceReasons = [
+    ...(policyEvidenceMissing
+      ? ['expected-policy-classified-evidence-missing']
+      : []),
+    ...(missing.length === 0 ? [] : ['expected-teaching-surfaces-missing']),
+  ];
+  const reasons = uniqueSorted([
+    ...params.report.run.report.gate.reasons.filter(
+      (reason) =>
+        reason !== 'expected-policy-classified-evidence-missing' &&
+        reason !== 'expected-teaching-surfaces-missing'
+    ),
+    ...evidenceReasons,
+  ]);
+  const filePolicyCount = params.run.policyOccurrencePaths.length;
+  const fileInScopeCount = params.run.occurrencePaths.length - filePolicyCount;
+  const projectedFileInScopeCount =
+    params.run.report.rewritten + params.run.report.review;
+  return {
+    ...params.report,
+    run: {
+      ...params.report.run,
+      report: {
+        ...params.report.run.report,
+        fileRenames: params.run.evidence,
+        gate: {
+          ...params.report.run.report.gate,
+          reasons,
+          status: reasons.length === 0 ? 'green' : 'open',
+        },
+        scopeTiers: {
+          'in-scope':
+            params.report.run.report.scopeTiers['in-scope'] -
+            projectedFileInScopeCount +
+            fileInScopeCount,
+          'policy-classified':
+            params.report.run.report.scopeTiers['policy-classified'] +
+            filePolicyCount,
+        },
+        teachingSurfaces: { expected, missing, touched },
+      },
+    },
+  };
+};
+
+const combineVocabularyReports = (params: {
+  readonly fileRenameRun: FileRenameRegradeRun | null;
+  readonly plan: VocabularyRegradePlan;
+  readonly preserveInventory: readonly VocabularyPreserveInventoryEntry[];
+  readonly proseReport: RegradeReport | null;
+  readonly symbolReport: RegradeReport | null;
+}): TrailsResult<RegradeReport, Error> => {
+  const baseReport =
+    params.proseReport ?? params.symbolReport ?? params.fileRenameRun?.report;
+  if (baseReport === undefined) {
+    return regradeNoEngineForScope();
+  }
+  let combined = reportWithVocabularyTransitionRun({
+    plan: params.plan,
+    preserveInventory: params.preserveInventory,
+    report: baseReport,
+  });
+  if (params.proseReport !== null && params.symbolReport !== null) {
+    combined = mergeRegradeReports(combined, params.symbolReport);
+  }
+  if (
+    params.fileRenameRun !== null &&
+    baseReport !== params.fileRenameRun.report
+  ) {
+    combined = mergeRegradeReports(combined, params.fileRenameRun.report);
+  }
+  if (params.fileRenameRun !== null && combined.run !== undefined) {
+    combined = withFileRenameEvidence({
+      plan: params.plan,
+      report: { ...combined, run: combined.run },
+      run: params.fileRenameRun,
+    });
+  }
+  if (combined.apply !== undefined && params.fileRenameRun !== null) {
+    const movedPaths = new Map(
+      (params.plan.fileRenames ?? []).map((rename) => [
+        posix.normalize(rename.from.replaceAll('\\', '/')),
+        posix.normalize(rename.to.replaceAll('\\', '/')),
+      ])
+    );
+    const changedPaths = new Set(params.fileRenameRun.changedPaths);
+    for (const entry of combined.entries) {
+      if (entry.outcome !== 'rewrite') {
+        continue;
+      }
+      const normalizedEntryPath = posix.normalize(entry.path);
+      const movedPath = movedPaths.get(normalizedEntryPath);
+      changedPaths.add(
+        movedPath !== undefined && changedPaths.has(movedPath)
+          ? movedPath
+          : normalizedEntryPath
+      );
+    }
+    const filesChanged = changedPaths.size;
+    combined = {
+      ...combined,
+      apply: { ...combined.apply, filesChanged },
+      ...(combined.run === undefined
+        ? {}
+        : {
+            run: {
+              ...combined.run,
+              report: { ...combined.run.report, filesChanged },
+            },
+          }),
+    };
+  }
+  return validateRegradeReport(combined);
+};
+
+const runPlanFileRenames = (
+  plan: VocabularyRegradePlan,
+  params: {
+    readonly apply: boolean;
+    readonly includeEntries: RegradeInput['includeEntries'];
+    readonly rootDir: string;
+  }
+): TrailsResult<FileRenameRegradeRun | null, Error> =>
+  plan.fileRenames === undefined || plan.fileRenames.length === 0
+    ? Result.ok(null)
+    : runFileRenameRegrade({
+        apply: params.apply,
+        excludeGeneratedArtifacts: true,
+        includeEntries: params.includeEntries,
+        renames: plan.fileRenames,
+        root: params.rootDir,
+        ...(plan.scope === undefined ? {} : { scope: plan.scope }),
+        vocabularyPlan: plan,
+      });
+
 const runResolvedVocabularyPlan = (params: {
   readonly apply: boolean;
   readonly includeEntries: RegradeInput['includeEntries'];
@@ -1536,70 +2023,117 @@ const runResolvedVocabularyPlan = (params: {
   readonly preserveInventory: readonly VocabularyPreserveInventoryEntry[];
   readonly rootDir: string;
 }): TrailsResult<RegradeReport, Error> => {
-  const prosePlan = vocabularyProsePlan(params.plan);
-  const reportResult: TrailsResult<RegradeReport | null, Error> =
-    prosePlan === null
+  const fileRenamePreflight = runPlanFileRenames(params.plan, {
+    apply: false,
+    includeEntries: params.includeEntries,
+    rootDir: params.rootDir,
+  });
+  if (fileRenamePreflight.isErr()) {
+    return fileRenamePreflight;
+  }
+  const evidencePlan = vocabularyEvidencePlan(params.plan);
+  const runProse = (
+    apply: boolean
+  ): TrailsResult<RegradeReport | null, Error> =>
+    evidencePlan === null
       ? Result.ok(null)
       : runVocabularyRegrade({
-          apply: params.apply,
+          apply,
           includeEntries: params.includeEntries,
-          plan: prosePlan,
+          plan: evidencePlan,
           ...(params.preserveInventory.length === 0
             ? {}
             : { preserveInventory: params.preserveInventory }),
           root: params.rootDir,
+          sourceFilter: (path) =>
+            vocabularyEvidenceSource(path, evidencePlan.scope),
         });
-  if (reportResult.isErr()) {
-    return reportResult;
+  const runSymbols = (
+    apply: boolean
+  ): TrailsResult<RegradeReport | null, Error> =>
+    runGovernedSymbolRegrade({
+      apply,
+      includeEntries: params.includeEntries,
+      plan: params.plan,
+      preserveInventory: params.preserveInventory,
+      rootDir: params.rootDir,
+    });
+  const prosePreview = runProse(false);
+  if (prosePreview.isErr()) {
+    return prosePreview;
+  }
+  const prosePreviewReport = withoutVocabularySourceFilterSkips(
+    prosePreview.value
+  );
+  const symbolPreview = runSymbols(false);
+  if (symbolPreview.isErr()) {
+    return symbolPreview;
+  }
+  if (!params.apply) {
+    if (
+      prosePreviewReport?.scanned === 0 &&
+      symbolPreview.value === null &&
+      fileRenamePreflight.value === null &&
+      !vocabularyProseEngineApplies(params.plan.scope)
+    ) {
+      return regradeNoEngineForScope();
+    }
+    return combineVocabularyReports({
+      fileRenameRun: fileRenamePreflight.value,
+      plan: params.plan,
+      preserveInventory: params.preserveInventory,
+      proseReport: prosePreviewReport,
+      symbolReport: symbolPreview.value,
+    });
   }
 
-  const symbolReportResult = runGovernedSymbolRegrade({
-    apply: params.apply,
-    includeEntries: params.includeEntries,
-    plan: params.plan,
-    preserveInventory: params.preserveInventory,
+  const snapshots = snapshotRegradeSources({
+    reports: [prosePreviewReport, symbolPreview.value],
     rootDir: params.rootDir,
   });
+  if (snapshots.isErr()) {
+    return snapshots;
+  }
+  const reportResult = runProse(true);
+  if (reportResult.isErr()) {
+    return regradeApplyErrorAfterRollback(reportResult.error, snapshots.value);
+  }
+  const symbolReportResult = runSymbols(true);
   if (symbolReportResult.isErr()) {
-    return symbolReportResult;
+    return regradeApplyErrorAfterRollback(
+      symbolReportResult.error,
+      snapshots.value
+    );
   }
-
-  const report = reportResult.value;
-  const symbolReport = symbolReportResult.value;
-  if (report === null) {
-    if (symbolReport === null) {
-      return regradeNoEngineForScope();
-    }
-    return validateRegradeReport(
-      reportWithVocabularyTransitionRun({
-        plan: params.plan,
-        preserveInventory: params.preserveInventory,
-        report: symbolReport,
-      })
+  const fileRenameResult = runPlanFileRenames(params.plan, {
+    apply: true,
+    includeEntries: params.includeEntries,
+    rootDir: params.rootDir,
+  });
+  if (fileRenameResult.isErr()) {
+    return regradeApplyErrorAfterRollback(
+      fileRenameResult.error,
+      snapshots.value
     );
   }
 
-  const validated = validateRegradeReport(
-    reportWithVocabularyTransitionRun({
-      plan: params.plan,
-      preserveInventory: params.preserveInventory,
-      report,
-    })
-  );
-  if (validated.isErr()) {
-    return validated;
-  }
-  if (symbolReport === null) {
-    return Result.ok(validated.value);
+  const report = withoutVocabularySourceFilterSkips(reportResult.value);
+  const symbolReport = symbolReportResult.value;
+  if (
+    report?.scanned === 0 &&
+    symbolReport === null &&
+    fileRenameResult.value === null &&
+    !vocabularyProseEngineApplies(params.plan.scope)
+  ) {
+    return regradeNoEngineForScope();
   }
-
-  return validateRegradeReport(
-    reportWithVocabularyTransitionRun({
-      plan: params.plan,
-      preserveInventory: params.preserveInventory,
-      report: mergeRegradeReports(report, symbolReport),
-    })
-  );
+  return combineVocabularyReports({
+    fileRenameRun: fileRenameResult.value,
+    plan: params.plan,
+    preserveInventory: params.preserveInventory,
+    proseReport: report,
+    symbolReport,
+  });
 };
 
 interface ClassRegradeCoreParams {
@@ -1697,12 +2231,18 @@ const runPlanArtifactDryRun = async (params: {
       rootDir: params.rootDir,
     });
   }
-  const preserveInventory = await deriveLiveApiPreserveInventory(planBody);
+  const preserveResult = await deriveLiveApiPreserveInventory(
+    planBody,
+    params.rootDir
+  );
+  if (preserveResult.isErr()) {
+    return preserveResult;
+  }
   return runResolvedVocabularyPlan({
     apply: false,
     includeEntries: params.includeEntries,
     plan: planBody,
-    preserveInventory,
+    preserveInventory: preserveResult.value,
     rootDir: params.rootDir,
   });
 };
@@ -1816,7 +2356,8 @@ const runVocabularyCommandRegrade = async (
 
   const planResult = buildVocabularyPlan(
     input,
-    vocabularyScopeFromConfig(configScope)
+    vocabularyScopeFromConfig(configScope),
+    rootDir
   );
   if (planResult.isErr()) {
     return planResult;
@@ -1825,14 +2366,18 @@ const runVocabularyCommandRegrade = async (
     return regradeRootNotFound(rootDir);
   }
 
-  const preserveInventory = await deriveLiveApiPreserveInventory(
-    planResult.value
+  const preserveResult = await deriveLiveApiPreserveInventory(
+    planResult.value,
+    rootDir
   );
+  if (preserveResult.isErr()) {
+    return preserveResult;
+  }
   const report = runResolvedVocabularyPlan({
     apply: input.apply,
     includeEntries: input.includeEntries,
     plan: planResult.value,
-    preserveInventory,
+    preserveInventory: preserveResult.value,
     rootDir,
   });
   if (report.isErr() || !input.writeRecord) {
@@ -1935,6 +2480,7 @@ const expansionForReport = (
         },
       ],
       kind: 'form',
+      provenance: 'derived',
       status: 'pending',
       suggestedClassification: occurrence.disposition,
       value: occurrence.form,
@@ -1966,6 +2512,7 @@ const expansionForReport = (
           },
         ],
         kind: 'form',
+        provenance: 'derived',
         status: 'pending',
         suggestedClassification: entry.reason ?? detail.reason,
         value: detail.symbol,
@@ -2119,6 +2666,11 @@ const validateClassPlanInput = (
       '`type: vocabulary` cannot be combined with `classIds`.'
     );
   }
+  if (input.fileRenames !== undefined && input.fileRenames.length > 0) {
+    return new ValidationError(
+      '`fileRenames` is not supported for class-mode plans; governed file moves require a vocabulary plan.'
+    );
+  }
   if (input.expand) {
     return new ValidationError(
       '`expand` stages vocabulary review candidates and is not supported for class-mode plans.'
@@ -2339,6 +2891,84 @@ const readCurrentVocabularyPlanArtifact = (
   return Result.ok({ ...candidate, plan: candidate.plan });
 };
 
+const finishVocabularyPlanArtifact = (params: {
+  readonly current?: VocabularyRegradePlanArtifact | undefined;
+  readonly currentPath: string;
+  readonly input: RegradePlanInput;
+  readonly plan: VocabularyRegradePlan;
+  readonly preserveInventory: readonly VocabularyPreserveInventoryEntry[];
+  readonly rootDir: string;
+  readonly shouldDryRun: boolean;
+}): TrailsResult<RegradePlanArtifact, Error> => {
+  const initialReport = runResolvedVocabularyPlan({
+    apply: false,
+    includeEntries: params.input.includeEntries,
+    plan: params.plan,
+    preserveInventory: params.preserveInventory,
+    rootDir: params.rootDir,
+  });
+  if (initialReport.isErr()) {
+    return initialReport;
+  }
+  const initialProvenance = regradePlanProvenanceForInput(
+    params.input,
+    params.plan
+  );
+  const scopeIsAuthored =
+    initialProvenance.fields['scope'] === 'authored' ||
+    params.current?.provenance.fields['scope'] === 'authored';
+  const plan = scopeIsAuthored
+    ? params.plan
+    : withDerivedTeachingSurfaceInventory({
+        plan: params.plan,
+        report: initialReport.value,
+      });
+  const report =
+    plan === params.plan
+      ? initialReport
+      : runResolvedVocabularyPlan({
+          apply: false,
+          includeEntries: params.input.includeEntries,
+          plan,
+          preserveInventory: params.preserveInventory,
+          rootDir: params.rootDir,
+        });
+  if (report.isErr()) {
+    return report;
+  }
+  const expansion = mergeRegradePlanExpansion(
+    params.current?.expansion,
+    params.input.expand ? expansionForReport(report.value) : undefined,
+    plan
+  );
+  const transitionId = priorTransitionId(params.currentPath, 'vocabulary');
+  const derivedProvenance = regradePlanProvenanceForInput(params.input, plan);
+  const provenance =
+    params.current === undefined
+      ? derivedProvenance
+      : preserveAuthoredPlanProvenance(params.current, derivedProvenance);
+  const artifact = buildRegradePlanArtifact({
+    derivation: deriveRegradePlanDerivation({
+      plan,
+      preserveInventory: params.preserveInventory,
+      provenance,
+      report: report.value,
+      rootDir: params.rootDir,
+    }),
+    ...(expansion === undefined ? {} : { expansion }),
+    input: params.input,
+    plan,
+    report: report.value,
+    rootDir: params.rootDir,
+    ...(transitionId === undefined ? {} : { transitionId }),
+  });
+  const mergedArtifact =
+    params.current === undefined ? artifact : { ...artifact, provenance };
+  return params.shouldDryRun
+    ? validateRegradePlanArtifact(mergedArtifact)
+    : writeRegradePlanArtifact(params.rootDir, mergedArtifact);
+};
+
 const runPlanRegrade = async (
   input: RegradePlanInput,
   rootDir: string,
@@ -2368,7 +2998,8 @@ const runPlanRegrade = async (
   };
   const planResult = buildVocabularyPlan(
     planInput,
-    vocabularyScopeFromConfig(configScope)
+    vocabularyScopeFromConfig(configScope),
+    rootDir
   );
   if (planResult.isErr()) {
     return planResult;
@@ -2386,45 +3017,19 @@ const runPlanRegrade = async (
     current === undefined
       ? planResult.value
       : mergeAuthoredPlanFields(current, planResult.value);
-  const preserveInventory = await deriveLiveApiPreserveInventory(plan);
-  const report = runResolvedVocabularyPlan({
-    apply: false,
-    includeEntries: input.includeEntries,
-    plan,
-    preserveInventory,
-    rootDir,
-  });
-  if (report.isErr()) {
-    return report;
+  const preserveResult = await deriveLiveApiPreserveInventory(plan, rootDir);
+  if (preserveResult.isErr()) {
+    return preserveResult;
   }
-  const expansion = mergeRegradePlanExpansion(
-    current?.expansion,
-    input.expand ? expansionForReport(report.value) : undefined,
-    plan
-  );
-  const transitionId = priorTransitionId(currentPath, 'vocabulary');
-  const artifact = buildRegradePlanArtifact({
-    ...(expansion === undefined ? {} : { expansion }),
+  return finishVocabularyPlanArtifact({
+    current,
+    currentPath,
     input,
     plan,
-    report: report.value,
+    preserveInventory: preserveResult.value,
     rootDir,
-    ...(transitionId === undefined ? {} : { transitionId }),
+    shouldDryRun,
   });
-  const mergedArtifact =
-    current === undefined
-      ? artifact
-      : {
-          ...artifact,
-          provenance: preserveAuthoredPlanProvenance(
-            current,
-            artifact.provenance
-          ),
-        };
-  if (shouldDryRun) {
-    return validateRegradePlanArtifact(mergedArtifact);
-  }
-  return writeRegradePlanArtifact(rootDir, mergedArtifact);
 };
 
 const loadPlanForInput = async (
@@ -2517,7 +3122,11 @@ const runCheckRegradePlan = async (
   if (report.isErr()) {
     return report;
   }
-  const status = planStatusForReport(loaded.value.artifact, report.value);
+  const status = planStatusForReport(
+    loaded.value.artifact,
+    report.value,
+    rootDir
+  );
   const checked = reportWithPlanSummary(
     report.value,
     loaded.value.artifact,
@@ -2567,7 +3176,7 @@ const runPreviewRegradePlan = async (
     reportWithPlanSummary(
       report.value,
       loaded.value.artifact,
-      planStatusForReport(loaded.value.artifact, report.value)
+      planStatusForReport(loaded.value.artifact, report.value, rootDir)
     )
   );
 };
@@ -2660,6 +3269,12 @@ const runApplyRegradePlan = async (
   if (loaded.isErr()) {
     return loaded;
   }
+  const governedPlanValidation = validateGovernedRegradePlan(
+    loaded.value.artifact
+  );
+  if (governedPlanValidation.isErr()) {
+    return governedPlanValidation;
+  }
   const dryRunReport = await runPlanArtifactDryRun({
     artifact: loaded.value.artifact,
     includeEntries: input.includeEntries,
@@ -2668,7 +3283,11 @@ const runApplyRegradePlan = async (
   if (dryRunReport.isErr()) {
     return dryRunReport;
   }
-  const status = planStatusForReport(loaded.value.artifact, dryRunReport.value);
+  const status = planStatusForReport(
+    loaded.value.artifact,
+    dryRunReport.value,
+    rootDir
+  );
   if (status === 'stale') {
     return Result.err(
       new ValidationError(
@@ -2695,12 +3314,18 @@ const runApplyRegradePlan = async (
       rootDir,
     });
   } else {
-    const preserveInventory = await deriveLiveApiPreserveInventory(planBody);
+    const preserveResult = await deriveLiveApiPreserveInventory(
+      planBody,
+      rootDir
+    );
+    if (preserveResult.isErr()) {
+      return preserveResult;
+    }
     applied = runResolvedVocabularyPlan({
       apply: true,
       includeEntries: input.includeEntries,
       plan: planBody,
-      preserveInventory,
+      preserveInventory: preserveResult.value,
       rootDir,
     });
   }
@@ -2800,6 +3425,17 @@ const runAdjustRegrade = async (
   }
   const artifact: RegradePlanArtifact = {
     ...draft,
+    ...(draft.plan.kind === 'class'
+      ? {}
+      : {
+          derivation: deriveRegradePlanDerivation({
+            plan: draft.plan,
+            preserveInventory: report.value.run?.preserveInventory ?? [],
+            provenance: draft.provenance,
+            report: report.value,
+            rootDir,
+          }),
+        }),
     sourceHash: regradeSourceHash(report.value),
   };
   if (shouldDryRun) {
@@ -2834,7 +3470,7 @@ const listRegradePlans = async (
       kind: body.kind,
       path: artifact.value.path,
       schemaVersion: artifact.value.schemaVersion,
-      status: planStatusForReport(artifact.value, report.value),
+      status: planStatusForReport(artifact.value, report.value, rootDir),
     });
   }
   return Result.ok({ plans });
@@ -2969,6 +3605,47 @@ export const listRegradesTrail = trail('list.regrades', {
   permit: 'public',
 });
 
+export const auditRegradeTrail = trail('audit.regrade', {
+  cli: { path: ['regrade', 'audit'] },
+  description:
+    'Audit applied Regrade vocabulary transitions against current source',
+  implementation: async (input, ctx) => {
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return rootDirResult;
+    }
+    const result = await auditRegradeHistory(input, rootDirResult.value);
+    if (result.isErr()) {
+      return result;
+    }
+    const output = validateOutput(regradeAuditOutputSchema, result.value);
+    if (output.isErr()) {
+      return Result.err(output.error);
+    }
+    if (input.failOnOpen && output.value.gate.status === 'open') {
+      return Result.err(
+        new ValidationError('Regrade audit found current-tree residue.', {
+          context: {
+            gate: output.value.gate,
+            transitions: output.value.transitions
+              .filter((transition) => transition.report.status === 'open')
+              .map((transition) => ({
+                open: transition.report.open,
+                source: transition.source,
+                transitionId: transition.transitionId,
+              })),
+          },
+        })
+      );
+    }
+    return Result.ok(output.value);
+  },
+  input: regradeAuditInputSchema,
+  intent: 'read',
+  output: regradeAuditOutputSchema,
+  permit: 'public',
+});
+
 export const checkRegradeTrail = trail('check.regrade', {
   cli: { path: ['regrade', 'check'] },
   description: 'Check a saved Regrade plan gate without writing source',