@ontrails/regrade 1.0.0-beta.30 → 1.0.0-beta.39

package/src/downstream/report.ts

@@ -1,12 +1,20 @@
-import { InternalError, Result } from '@ontrails/core';
+import {
+  InternalError,
+  Result,
+  escapeRegExp,
+  includedByPathScope,
+} from '@ontrails/core';
+import type { ScanTargets } from '@ontrails/core';
 import type {
   WardenDiagnostic,
   WardenFixEdit,
+  WardenGuidance,
   WardenRule,
 } from '@ontrails/warden';
 import {
   getWardenRuleMetadata,
   isWardenSourceScanTarget,
+  loadProjectWardenRules,
   wardenRules,
 } from '@ontrails/warden';
 import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
@@ -18,6 +26,13 @@ import {
   collectDownstreamSources,
 } from './collect.js';
 import type { DownstreamCollectionOptions, SkippedSource } from './collect.js';
+import {
+  buildRegradeScanSummary,
+  regradeScanSummaryOutput,
+} from './scan-summary.js';
+import type { RegradeScanSummary } from './scan-summary.js';
+import type { VocabularyRegradeRun } from './vocabulary.js';
+import { vocabularyRegradeRunOutput } from './vocabulary.js';
 
 /**
  * Regrade-class selection and coverage reporting (TRL-845).
@@ -67,12 +82,14 @@ export interface RegradeClassContext {
 }
 
 /** Files a regrade class knows how to inspect. */
-export interface RegradeScanTargets {
-  /** Source extensions the class can inspect. */
-  readonly extensions?: readonly string[];
-  /** Directory names to skip during collection. */
+export type RegradeScanTargets = ScanTargets & {
+  /**
+   * @deprecated Use collection-level `exclude` globs. Preserved so existing
+   * Regrade classes can explicitly opt into directories the default collector
+   * prunes, such as `dist`, while migrating to PathScope.
+   */
   readonly ignoredDirectories?: readonly string[];
-}
+};
 
 /** One named, contract-aware transform. */
 export interface RegradeClass {
@@ -89,12 +106,22 @@ export interface RegradeClass {
   readonly scanTargets?: RegradeScanTargets;
 }
 
+export interface RegradeWardenClassSet {
+  /** Built-in and project-local Warden term-rewrite classes. */
+  readonly classes: readonly RegradeClass[];
+  /** Diagnostics raised while loading project-local rules. */
+  readonly diagnostics: readonly WardenDiagnostic[];
+}
+
 /** Which regrade classes a run should execute. */
 export interface RegradeSelection {
   /** Class ids to run. Omit to run every provided class. */
   readonly classIds?: readonly string[];
 }
 
+/** Which report entries should be returned. Counts always cover the full run. */
+export type RegradeReportEntrySelection = 'actionable' | 'all';
+
 /** Optional write summary for an apply-mode regrade run. */
 export interface RegradeApplySummary {
   /** Safe rewrite outcomes written to disk. */
@@ -117,18 +144,39 @@ export interface RegradeReviewSpan {
   readonly start: number;
 }
 
+/**
+ * Verdict state for a review detail.
+ *
+ * - `unresolved`: the class could not complete occurrence judgment; a human or
+ *   agent decision is still needed.
+ * - `preserve`: a completed verdict to keep the occurrence as-is.
+ * - `rewrite`: a completed verdict that a rewrite is intended but this run
+ *   could not apply it (for example invalid or missing edits).
+ */
+export type RegradeReviewJudgment = 'preserve' | 'rewrite' | 'unresolved';
+
 /** Structured detail explaining why a source match needs review. */
 export interface RegradeReviewDetail {
+  /** Concrete replacement the class would apply if the occurrence were judged safe. */
+  readonly candidateReplacement?: string;
   /** Class that produced the review detail, injected by report building. */
   readonly classId?: string;
   /** Expected target shape when the class can describe one. */
   readonly expectedTarget?: string;
   /** Fixture or example reference that illustrates the expected migration. */
   readonly fixture?: string;
+  /** Whether occurrence judgment is unresolved or a preserve/rewrite verdict completed. */
+  readonly judgment?: RegradeReviewJudgment;
+  /** Exact matched source text for the occurrence under review. */
+  readonly matchedForm?: string;
   /** AST node kind or source construct kind. */
   readonly nodeKind?: string;
+  /** Cautions explaining why a blind rewrite of this occurrence is unsafe. */
+  readonly preserveCautions?: readonly string[];
   /** Machine-readable reason for review. */
   readonly reason: string;
+  /** Machine-readable provenance tags for the producing rule or class. */
+  readonly signals?: readonly string[];
   /** Source span and line/column for the review-required match. */
   readonly span?: RegradeReviewSpan;
   /** Suggested validation command after the review is resolved. */
@@ -137,9 +185,6 @@ export interface RegradeReviewDetail {
   readonly symbol?: string;
 }
 
-const escapeRegExp = (value: string): string =>
-  value.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
 /**
  * Build a whole-word term-rewrite class.
  *
@@ -198,6 +243,27 @@ type WardenEditApplication =
   | { readonly ok: true; readonly nextSource: string }
   | { readonly ok: false; readonly reason: string };
 
+const regradeScanTargetsFromWardenFix = (
+  scanTargets: NonNullable<
+    NonNullable<ReturnType<typeof getWardenRuleMetadata>>['fix']
+  >['scanTargets']
+): RegradeScanTargets | undefined => {
+  if (scanTargets === undefined) {
+    return undefined;
+  }
+  return {
+    ...(scanTargets.exclude === undefined
+      ? {}
+      : { exclude: scanTargets.exclude }),
+    ...(scanTargets.extensions === undefined
+      ? {}
+      : { extensions: scanTargets.extensions }),
+    ...(scanTargets.ignoredDirectories === undefined
+      ? {}
+      : { ignoredDirectories: scanTargets.ignoredDirectories }),
+  };
+};
+
 const diagnosticNote = (diagnostic: WardenDiagnostic): string => {
   const reason = diagnostic.fix?.reason ?? diagnostic.message;
   return `${diagnostic.rule}:${diagnostic.line}: ${reason}`;
@@ -273,7 +339,9 @@ const diagnosticSpan = (
   return spanForSymbolOnDiagnosticLine(source, diagnostic.line, symbol);
 };
 
-const expectedTarget = (diagnostic: WardenDiagnostic): string | undefined => {
+const diagnosticCandidateReplacement = (
+  diagnostic: WardenDiagnostic
+): string | undefined => {
   const replacements = new Set(
     (diagnostic.fix?.edits ?? []).map((edit) => edit.replacement)
   );
@@ -281,32 +349,98 @@ const expectedTarget = (diagnostic: WardenDiagnostic): string | undefined => {
     return undefined;
   }
   const [replacement] = replacements;
+  return replacement;
+};
+
+const expectedTarget = (diagnostic: WardenDiagnostic): string | undefined => {
+  const replacement = diagnosticCandidateReplacement(diagnostic);
   return replacement === undefined
     ? undefined
     : `Replace with "${replacement}".`;
 };
 
+const isValidEditSpan = (
+  source: string,
+  edit: WardenFixEdit | undefined
+): edit is WardenFixEdit =>
+  edit !== undefined &&
+  Number.isInteger(edit.start) &&
+  Number.isInteger(edit.end) &&
+  edit.start >= 0 &&
+  edit.end >= edit.start &&
+  edit.end <= source.length;
+
+const diagnosticMatchedForm = (
+  source: string,
+  diagnostic: WardenDiagnostic,
+  symbol: string | undefined
+): string | undefined => {
+  const [edit] = diagnostic.fix?.edits ?? [];
+  if (isValidEditSpan(source, edit)) {
+    return source.slice(edit.start, edit.end);
+  }
+  return symbol;
+};
+
+const diagnosticSignals = (diagnostic: WardenDiagnostic): readonly string[] => [
+  `warden:${diagnostic.rule}`,
+  ...(diagnostic.code === undefined
+    ? []
+    : [`${diagnostic.rule}:${diagnostic.code}`]),
+];
+
+interface WardenReviewMappingOptions {
+  /** Verdict state for this review path. */
+  readonly judgment: RegradeReviewJudgment;
+  /** Machine-readable review reason. */
+  readonly reason: string;
+  /** Rule-level guidance used when a finding carries none of its own. */
+  readonly ruleGuidance?: WardenGuidance;
+}
+
+const reviewDetailFromDiagnostic = (
+  source: string,
+  diagnostic: WardenDiagnostic,
+  options: WardenReviewMappingOptions
+): RegradeReviewDetail => {
+  const symbol =
+    firstQuotedValue(diagnostic.fix?.reason) ??
+    firstQuotedValue(diagnostic.message);
+  const span = diagnosticSpan(source, diagnostic, symbol);
+  const target = expectedTarget(diagnostic);
+  const replacement = diagnosticCandidateReplacement(diagnostic);
+  const matchedForm = diagnosticMatchedForm(source, diagnostic, symbol);
+  const guidance = diagnostic.guidance ?? options.ruleGuidance;
+  const preserveCautions =
+    guidance === undefined
+      ? undefined
+      : [guidance.summary, ...(guidance.steps ?? [])];
+  const suggestedValidation = guidance?.commands?.[0];
+  return {
+    ...(replacement === undefined ? {} : { candidateReplacement: replacement }),
+    ...(target === undefined ? {} : { expectedTarget: target }),
+    ...(diagnostic.fix?.fixture === undefined
+      ? {}
+      : { fixture: diagnostic.fix.fixture }),
+    judgment: options.judgment,
+    ...(matchedForm === undefined ? {} : { matchedForm }),
+    ...(preserveCautions === undefined ? {} : { preserveCautions }),
+    reason: options.reason,
+    signals: diagnosticSignals(diagnostic),
+    ...(span === undefined ? {} : { span }),
+    ...(suggestedValidation === undefined ? {} : { suggestedValidation }),
+    ...(symbol === undefined ? {} : { symbol }),
+  } satisfies RegradeReviewDetail;
+};
+
 const reviewDetailsFromDiagnostics = (
   source: string,
   diagnostics: readonly WardenDiagnostic[],
-  reason: string
+  options: WardenReviewMappingOptions
 ): readonly RegradeReviewDetail[] | undefined => {
-  const details = diagnostics.map((diagnostic) => {
-    const symbol =
-      firstQuotedValue(diagnostic.fix?.reason) ??
-      firstQuotedValue(diagnostic.message);
-    const span = diagnosticSpan(source, diagnostic, symbol);
-    const target = expectedTarget(diagnostic);
-    return {
-      ...(target === undefined ? {} : { expectedTarget: target }),
-      ...(diagnostic.fix?.fixture === undefined
-        ? {}
-        : { fixture: diagnostic.fix.fixture }),
-      reason,
-      ...(span === undefined ? {} : { span }),
-      ...(symbol === undefined ? {} : { symbol }),
-    } satisfies RegradeReviewDetail;
-  });
+  const details = diagnostics.map((diagnostic) =>
+    reviewDetailFromDiagnostic(source, diagnostic, options)
+  );
   return details.length === 0 ? undefined : details;
 };
 
@@ -351,10 +485,11 @@ const applyWardenEdits = (
 export const createWardenTermRewriteClass = (
   rule: WardenRule
 ): RegradeClass | null => {
-  const metadata = getWardenRuleMetadata(rule.name);
+  const metadata = getWardenRuleMetadata(rule);
   if (metadata?.fix?.class !== TERM_REWRITE_FIX_CLASS) {
     return null;
   }
+  const scanTargets = regradeScanTargetsFromWardenFix(metadata.fix.scanTargets);
 
   return {
     apply: (
@@ -386,10 +521,18 @@ export const createWardenTermRewriteClass = (
         (diagnostic) => diagnostic.fix?.safety !== 'safe'
       );
       if (reviewDiagnostics.length > 0) {
+        // The rule flagged the occurrence but marked it review: occurrence
+        // judgment is unresolved and needs a human or agent decision.
         const reviewDetails = reviewDetailsFromDiagnostics(
           source,
           reviewDiagnostics,
-          'warden-review-required'
+          {
+            judgment: 'unresolved',
+            reason: 'warden-review-required',
+            ...(metadata.guidance === undefined
+              ? {}
+              : { ruleGuidance: metadata.guidance }),
+          }
         );
         return {
           kind: 'needs-review',
@@ -403,10 +546,18 @@ export const createWardenTermRewriteClass = (
         (diagnostic) => (diagnostic.fix?.edits?.length ?? 0) === 0
       );
       if (diagnosticsMissingEdits.length > 0) {
+        // A safe fix without concrete edits cannot complete occurrence
+        // judgment on its own, so the verdict stays unresolved.
         const reviewDetails = reviewDetailsFromDiagnostics(
           source,
           diagnosticsMissingEdits,
-          'warden-fix-missing-edits'
+          {
+            judgment: 'unresolved',
+            reason: 'warden-fix-missing-edits',
+            ...(metadata.guidance === undefined
+              ? {}
+              : { ruleGuidance: metadata.guidance }),
+          }
         );
         return {
           kind: 'needs-review',
@@ -421,10 +572,18 @@ export const createWardenTermRewriteClass = (
       );
       const application = applyWardenEdits(source, edits);
       if (!application.ok) {
+        // The rule completed judgment — it authored concrete edits — but this
+        // run could not apply them, so the verdict is a rewrite left undone.
         const reviewDetails = reviewDetailsFromDiagnostics(
           source,
           diagnostics,
-          'warden-fix-invalid'
+          {
+            judgment: 'rewrite',
+            reason: 'warden-fix-invalid',
+            ...(metadata.guidance === undefined
+              ? {}
+              : { ruleGuidance: metadata.guidance }),
+          }
         );
         return {
           kind: 'needs-review',
@@ -445,6 +604,7 @@ export const createWardenTermRewriteClass = (
     },
     describe: `${rule.description} (${metadata.fix.safety} ${metadata.fix.class})`,
     id: `${metadata.fix.class}:${rule.name}`,
+    ...(scanTargets === undefined ? {} : { scanTargets }),
   };
 };
 
@@ -479,29 +639,56 @@ export const selectRegradeClasses = (
 const uniqueSorted = (values: readonly string[]): readonly string[] =>
   [...new Set(values)].toSorted((a, b) => a.localeCompare(b));
 
+const intersectValues = (
+  left: readonly string[],
+  right: readonly string[]
+): readonly string[] => left.filter((value) => right.includes(value));
+
+const deriveClassIgnoredDirectories = (
+  classes: readonly RegradeClass[]
+): readonly string[] | undefined => {
+  const explicitTargets = classes
+    .map((cls) => cls.scanTargets?.ignoredDirectories)
+    .filter((value): value is readonly string[] => value !== undefined);
+  if (explicitTargets.length === 0) {
+    return undefined;
+  }
+
+  let common = explicitTargets[0] ?? [];
+  for (const target of explicitTargets.slice(1)) {
+    common = intersectValues(common, target);
+  }
+  return uniqueSorted(common);
+};
+
 const deriveCollectionOptions = (
   classes: readonly RegradeClass[],
   collection: DownstreamCollectionOptions | undefined
 ): DownstreamCollectionOptions => {
-  const targetExtensions = uniqueSorted(
-    classes.length === 0
-      ? DEFAULT_SOURCE_EXTENSIONS
-      : classes.flatMap(
-          (cls) => cls.scanTargets?.extensions ?? DEFAULT_SOURCE_EXTENSIONS
-        )
-  );
-  const ignoredDirectories = uniqueSorted(
-    classes.length === 0
-      ? DEFAULT_IGNORED_DIRECTORIES
-      : classes.flatMap(
-          (cls) =>
-            cls.scanTargets?.ignoredDirectories ?? DEFAULT_IGNORED_DIRECTORIES
-        )
+  const allExtensions = classes.some(
+    (cls) => cls.scanTargets?.extensions?.length === 0
   );
-
+  const targetExtensions = allExtensions
+    ? []
+    : uniqueSorted(
+        classes.length === 0
+          ? DEFAULT_SOURCE_EXTENSIONS
+          : classes.flatMap(
+              (cls) => cls.scanTargets?.extensions ?? DEFAULT_SOURCE_EXTENSIONS
+            )
+      );
   return {
+    ...(collection?.exclude === undefined
+      ? {}
+      : { exclude: collection.exclude }),
+    ...(collection?.include === undefined
+      ? {}
+      : { include: collection.include }),
     extensions: collection?.extensions ?? targetExtensions,
-    ignoredDirectories: collection?.ignoredDirectories ?? ignoredDirectories,
+    ignoredDirectories:
+      collection?.ignoredDirectories ??
+      deriveClassIgnoredDirectories(classes) ??
+      DEFAULT_IGNORED_DIRECTORIES,
   };
 };
 
@@ -539,10 +726,38 @@ export interface RegradeReport {
   readonly review: number;
   /** Entries skipped (collection skips plus any run-level skips). */
   readonly skipped: number;
+  /** Skipped entries grouped by reason. */
+  readonly skipsByReason: Readonly<Record<string, number>>;
+  /** Agent-facing inventory summary for the scan. */
+  readonly scan: RegradeScanSummary;
   /** Per-entry detail, sorted by path. */
   readonly entries: readonly RegradeReportEntry[];
   /** Apply-mode summary; absent for dry-run report-only calls. */
   readonly apply?: RegradeApplySummary;
+  /** Vocabulary regrade run: plan, ledger, and completion report. */
+  readonly run?: VocabularyRegradeRun;
+  /** Saved active Regrade plan evidence for vocabulary regrades. */
+  readonly plan?: {
+    readonly expansionPending?: number;
+    readonly path: string;
+    readonly schemaVersion: number;
+    readonly status: 'active' | 'stale';
+  };
+  /** Saved applied Regrade history evidence for vocabulary regrades. */
+  readonly history?: {
+    readonly path: string;
+    readonly schemaVersion: number;
+    readonly status: 'applied' | 'checked' | 'replay';
+  };
+  /**
+   * @deprecated Persisted transition record evidence for vocabulary regrades.
+   *   Use `plan` and `history` summaries in public surfaces.
+   */
+  readonly record?: {
+    readonly path: string;
+    readonly schemaVersion: number;
+    readonly status: 'candidate' | 'applied' | 'checked';
+  };
 }
 
 interface RegradeRewriteCandidate {
@@ -557,20 +772,80 @@ interface RegradeClassifiedFile {
   readonly rewrite?: RegradeRewriteCandidate;
 }
 
+const isIgnoredByClassDirectories = (
+  path: string,
+  ignoredDirectories: readonly string[] | undefined
+): boolean => {
+  if (ignoredDirectories === undefined || ignoredDirectories.length === 0) {
+    return false;
+  }
+  return path
+    .split('/')
+    .slice(0, -1)
+    .some((segment) => ignoredDirectories.includes(segment));
+};
+
+const classScanTargetSkip = (
+  cls: RegradeClass,
+  path: string,
+  collection: DownstreamCollectionOptions | undefined
+): RegradeClassResult | undefined => {
+  const ignoredDirectories =
+    collection?.ignoredDirectories ??
+    cls.scanTargets?.ignoredDirectories ??
+    DEFAULT_IGNORED_DIRECTORIES;
+  if (isIgnoredByClassDirectories(path, ignoredDirectories)) {
+    return {
+      kind: 'skipped',
+      notes: [`Skipped by ${cls.id} scan-target filtering.`],
+      reason: 'regrade-scan-target-filtered',
+    };
+  }
+  const effectiveScanTargets: ScanTargets | undefined =
+    cls.scanTargets?.extensions === undefined &&
+    collection?.extensions === undefined
+      ? {
+          ...cls.scanTargets,
+          extensions: DEFAULT_SOURCE_EXTENSIONS,
+        }
+      : cls.scanTargets;
+  if (
+    effectiveScanTargets === undefined ||
+    includedByPathScope(path, effectiveScanTargets)
+  ) {
+    return undefined;
+  }
+  return {
+    kind: 'skipped',
+    notes: [`Skipped by ${cls.id} scan-target filtering.`],
+    reason: 'regrade-scan-target-filtered',
+  };
+};
+
 const classifyFile = (
   path: string,
   source: string,
   context: RegradeClassContext,
-  selected: readonly RegradeClass[]
+  selected: readonly RegradeClass[],
+  collection?: DownstreamCollectionOptions
 ): RegradeClassifiedFile => {
-  // First selected class that matches (rewrite or review) wins, mirroring the
-  // "run one class" emphasis. A scan-target skip is remembered so the file is
-  // accounted as skipped rather than a scanned/clean no-op. No-ops fall through.
+  // Compose safe rewrites across selected classes in memory so one governed
+  // transition can move every compatible symbol in a file. Review still wins:
+  // if any class needs judgment, no partial rewrite is returned for that file.
   let skipped:
     | { readonly classId: string; readonly result: RegradeClassResult }
     | undefined;
+  let inspected = false;
+  let currentSource = source;
+  const rewriteClassIds: string[] = [];
+  const rewriteNotes: string[] = [];
   for (const cls of selected) {
-    const result = cls.apply(source, context);
+    const result =
+      classScanTargetSkip(cls, path, collection) ??
+      cls.apply(currentSource, context);
+    if (result.kind !== 'skipped') {
+      inspected = true;
+    }
     if (result.kind === 'rewrite') {
       if (typeof result.nextSource !== 'string') {
         return {
@@ -583,38 +858,29 @@ const classifyFile = (
           },
         };
       }
-      const entry = {
-        classId: cls.id,
-        notes: result.notes,
-        outcome: 'rewrite',
-        path,
-      } satisfies RegradeReportEntry;
-      return {
-        entry,
-        ...(context.absolutePath === undefined
-          ? {}
-          : {
-              rewrite: {
-                absolutePath: context.absolutePath,
-                classId: cls.id,
-                nextSource: result.nextSource,
-                path,
-              },
-            }),
-      };
+      currentSource = result.nextSource;
+      rewriteClassIds.push(cls.id);
+      rewriteNotes.push(...(result.notes ?? []));
+      continue;
     }
     if (result.kind === 'needs-review') {
-      const reviewDetails = result.reviewDetails?.map((detail) => ({
+      const originalSourceResult =
+        currentSource === source ? result : cls.apply(source, context);
+      const reviewResult =
+        originalSourceResult.kind === 'needs-review'
+          ? originalSourceResult
+          : result;
+      const reviewDetails = reviewResult.reviewDetails?.map((detail) => ({
         ...detail,
         classId: detail.classId ?? cls.id,
       }));
       return {
         entry: {
           classId: cls.id,
-          notes: result.notes,
+          notes: reviewResult.notes,
           outcome: 'needs-review',
           path,
-          reason: result.reason ?? 'needs-review',
+          reason: reviewResult.reason ?? 'needs-review',
           ...(reviewDetails === undefined ? {} : { reviewDetails }),
         },
       };
@@ -623,7 +889,29 @@ const classifyFile = (
       skipped = { classId: cls.id, result };
     }
   }
-  if (skipped !== undefined) {
+  if (rewriteClassIds.length > 0) {
+    const classId = rewriteClassIds.join(',');
+    const entry = {
+      classId,
+      notes: rewriteNotes,
+      outcome: 'rewrite',
+      path,
+    } satisfies RegradeReportEntry;
+    return {
+      entry,
+      ...(context.absolutePath === undefined
+        ? {}
+        : {
+            rewrite: {
+              absolutePath: context.absolutePath,
+              classId,
+              nextSource: currentSource,
+              path,
+            },
+          }),
+    };
+  }
+  if (!inspected && skipped !== undefined) {
     return {
       entry: {
         classId: skipped.classId,
@@ -642,6 +930,32 @@ interface RegradeEvaluation {
   readonly rewrites: readonly RegradeRewriteCandidate[];
 }
 
+const includeEntryInReport = (
+  entry: RegradeReportEntry,
+  selection: RegradeReportEntrySelection
+): boolean =>
+  selection === 'all' ||
+  entry.outcome === 'rewrite' ||
+  entry.outcome === 'needs-review';
+
+const skipsByReason = (
+  entries: readonly RegradeReportEntry[]
+): Readonly<Record<string, number>> => {
+  const counts = new Map<string, number>();
+  for (const entry of entries) {
+    if (entry.outcome !== 'skip') {
+      continue;
+    }
+    const reason = entry.reason ?? 'skipped';
+    counts.set(reason, (counts.get(reason) ?? 0) + 1);
+  }
+  return Object.fromEntries(
+    [...counts.entries()].toSorted(([left], [right]) =>
+      left.localeCompare(right)
+    )
+  );
+};
+
 /**
  * Build a coverage report from already-read source files. Pure: no filesystem
  * access, so coverage semantics are testable directly.
@@ -656,7 +970,10 @@ const buildRegradeEvaluation = (params: {
   readonly skipped: readonly SkippedSource[];
   readonly classes: readonly RegradeClass[];
   readonly selection?: RegradeSelection;
+  readonly collection?: DownstreamCollectionOptions;
+  readonly includeEntries?: RegradeReportEntrySelection;
 }): RegradeEvaluation => {
+  const entrySelection = params.includeEntries ?? 'actionable';
   const { selected, unknownClassIds } = selectRegradeClasses(
     params.classes,
     params.selection
@@ -672,7 +989,8 @@ const buildRegradeEvaluation = (params: {
           : { absolutePath: file.absolutePath }),
         path: file.path,
       },
-      selected
+      selected,
+      params.collection
     )
   );
   const fileEntries = classifiedFiles.map((file) => file.entry);
@@ -685,9 +1003,12 @@ const buildRegradeEvaluation = (params: {
     reason: entry.reason,
   }));
 
-  const entries = [...fileEntries, ...skipEntries].toSorted((a, b) =>
+  const allEntries = [...fileEntries, ...skipEntries].toSorted((a, b) =>
     a.path.localeCompare(b.path)
   );
+  const entries = allEntries.filter((entry) =>
+    includeEntryInReport(entry, entrySelection)
+  );
 
   // Class-level skips (e.g. scan-target filtering) are accounted as skipped, not
   // as scanned/clean files.
@@ -699,6 +1020,11 @@ const buildRegradeEvaluation = (params: {
   const review = scannedEntries.filter(
     (e) => e.outcome === 'needs-review'
   ).length;
+  const matchedPaths = scannedEntries
+    .filter((e) => e.outcome === 'rewrite' || e.outcome === 'needs-review')
+    .map((entry) => entry.path);
+  const skipped = skipEntries.length + fileSkipCount;
+  const skippedReasons = skipsByReason(allEntries);
 
   return {
     report: {
@@ -707,9 +1033,16 @@ const buildRegradeEvaluation = (params: {
       review,
       rewritten,
       root: params.root,
+      scan: buildRegradeScanSummary({
+        matchedPaths,
+        scanned: scannedEntries.length,
+        skipped,
+        skippedByReason: skippedReasons,
+      }),
       scanned: scannedEntries.length,
       selectedClassIds: selected.map((cls) => cls.id),
-      skipped: skipEntries.length + fileSkipCount,
+      skipped,
+      skipsByReason: skippedReasons,
       unknownClassIds,
     },
     rewrites,
@@ -726,6 +1059,8 @@ export const buildRegradeReport = (params: {
   readonly skipped: readonly SkippedSource[];
   readonly classes: readonly RegradeClass[];
   readonly selection?: RegradeSelection;
+  readonly collection?: DownstreamCollectionOptions;
+  readonly includeEntries?: RegradeReportEntrySelection;
 }): RegradeReport => buildRegradeEvaluation(params).report;
 
 const applyRegradeEvaluation = (
@@ -797,6 +1132,7 @@ const runRegradeEvaluation = (params: {
   readonly classes: readonly RegradeClass[];
   readonly selection?: RegradeSelection;
   readonly collection?: DownstreamCollectionOptions;
+  readonly includeEntries?: RegradeReportEntrySelection;
 }): RegradeEvaluation | null => {
   const { selected, unknownClassIds } = selectRegradeClasses(
     params.classes,
@@ -808,9 +1144,15 @@ const runRegradeEvaluation = (params: {
     }
     return buildRegradeEvaluation({
       classes: params.classes,
+      ...(params.collection === undefined
+        ? {}
+        : { collection: params.collection }),
       files: [],
       root: params.root,
       skipped: [],
+      ...(params.includeEntries === undefined
+        ? {}
+        : { includeEntries: params.includeEntries }),
       ...(params.selection === undefined
         ? {}
         : { selection: params.selection }),
@@ -841,9 +1183,15 @@ const runRegradeEvaluation = (params: {
 
   return buildRegradeEvaluation({
     classes: params.classes,
+    ...(params.collection === undefined
+      ? {}
+      : { collection: params.collection }),
     files,
     root: params.root,
     skipped,
+    ...(params.includeEntries === undefined
+      ? {}
+      : { includeEntries: params.includeEntries }),
     ...(params.selection === undefined ? {} : { selection: params.selection }),
   });
 };
@@ -861,6 +1209,7 @@ export const runRegrade = (params: {
   readonly selection?: RegradeSelection;
   readonly collection?: DownstreamCollectionOptions;
   readonly apply?: boolean;
+  readonly includeEntries?: RegradeReportEntrySelection;
 }): Result<RegradeReport | null, InternalError> => {
   const evaluation = runRegradeEvaluation(params);
   if (evaluation === null) {
@@ -890,6 +1239,12 @@ const regradeReportEntrySchema = z.object({
   reviewDetails: z
     .array(
       z.object({
+        candidateReplacement: z
+          .string()
+          .optional()
+          .describe(
+            'Concrete replacement the class would apply if the occurrence were judged safe'
+          ),
         classId: z
           .string()
           .optional()
@@ -902,11 +1257,35 @@ const regradeReportEntrySchema = z.object({
           .string()
           .optional()
           .describe('Fixture or example reference for the migration'),
+        judgment: z
+          .enum(['preserve', 'rewrite', 'unresolved'])
+          .optional()
+          .describe(
+            'Verdict state: unresolved = occurrence judgment is incomplete and needs a human or agent decision; preserve = completed verdict to keep the occurrence; rewrite = completed verdict that a rewrite is intended but this run could not apply it'
+          ),
+        matchedForm: z
+          .string()
+          .optional()
+          .describe(
+            'Exact matched source text for the occurrence under review'
+          ),
         nodeKind: z
           .string()
           .optional()
           .describe('AST node kind or source construct kind'),
+        preserveCautions: z
+          .array(z.string())
+          .optional()
+          .describe(
+            'Cautions explaining why a blind rewrite of this occurrence is unsafe'
+          ),
         reason: z.string().describe('Machine-readable review reason'),
+        signals: z
+          .array(z.string())
+          .optional()
+          .describe(
+            'Machine-readable provenance tags for the producing rule or class'
+          ),
         span: z
           .object({
             column: z.number().describe('One-based source column'),
@@ -941,14 +1320,61 @@ export const regradeReportOutput = z.object({
     .describe('Apply-mode summary; absent for dry-run report-only calls'),
   entries: z
     .array(regradeReportEntrySchema)
-    .describe('Per-entry detail, sorted by path'),
+    .describe(
+      'Per-entry detail, sorted by path. Defaults to actionable rewrite/review entries.'
+    ),
+  history: z
+    .object({
+      path: z.string().describe('Root-relative applied history entry path'),
+      schemaVersion: z.number().describe('Regrade history schema version'),
+      status: z
+        .enum(['applied', 'checked', 'replay'])
+        .describe(
+          'How this command used the Regrade history file: applied = run appended, replay = identical re-run recognized and not duplicated, checked = consolidated history verified per-run'
+        ),
+    })
+    .optional()
+    .describe('Saved applied Regrade history evidence'),
   matched: z.number().describe('Files with a rewrite or review outcome'),
+  plan: z
+    .object({
+      expansionPending: z
+        .number()
+        .optional()
+        .describe('Pending staged expansion candidates on this plan'),
+      path: z.string().describe('Root-relative Regrade plan path'),
+      schemaVersion: z.number().describe('Regrade plan schema version'),
+      status: z
+        .enum(['active', 'stale'])
+        .describe('Whether the saved plan still matches the source tree'),
+    })
+    .optional()
+    .describe('Saved active Regrade plan evidence'),
+  record: z
+    .object({
+      path: z.string().describe('Root-relative transition record path'),
+      schemaVersion: z.number().describe('Transition record schema version'),
+      status: z
+        .enum(['candidate', 'applied', 'checked'])
+        .describe('How this command used the transition record'),
+    })
+    .optional()
+    .describe('Persisted transition record evidence'),
   review: z.number().describe('Files routed to review'),
   rewritten: z.number().describe('Files with a rewrite outcome'),
   root: z.string().describe('Root the run scanned'),
+  run: vocabularyRegradeRunOutput
+    .optional()
+    .describe('Vocabulary regrade run: plan, ledger, and completion report'),
+  scan: regradeScanSummaryOutput.describe(
+    'Agent-facing inventory summary for the scan'
+  ),
   scanned: z.number().describe('Source files inspected'),
   selectedClassIds: z.array(z.string()).describe('Class ids executed'),
   skipped: z.number().describe('Entries skipped'),
+  skipsByReason: z
+    .record(z.string(), z.number())
+    .describe('Skipped entries grouped by reason'),
   unknownClassIds: z
     .array(z.string())
     .describe('Selected ids that did not resolve to a class'),
@@ -967,3 +1393,55 @@ export const wardenTermRewriteClasses: readonly RegradeClass[] = Object.freeze(
     return cls === null ? [] : [cls];
   })
 );
+
+const duplicateClassDiagnostics = (
+  root: string,
+  classes: readonly RegradeClass[]
+): readonly WardenDiagnostic[] => {
+  const seen = new Set<string>();
+  const diagnostics: WardenDiagnostic[] = [];
+  for (const cls of classes) {
+    if (!seen.has(cls.id)) {
+      seen.add(cls.id);
+      continue;
+    }
+    diagnostics.push({
+      filePath: root,
+      line: 1,
+      message: `Duplicate Regrade class id "${cls.id}" from Warden term-rewrite rules.`,
+      rule: 'regrade-warden-term-rewrite-classes',
+      severity: 'error',
+    });
+  }
+  return diagnostics;
+};
+
+/**
+ * Load built-in and project-local Warden term-rewrite rules as Regrade classes.
+ *
+ * Built-ins are always available. When `root` is provided, committed
+ * project-local Warden rules under `.trails/rules.ts` or direct
+ * `.trails/rules/*.ts` modules are loaded and any term-rewrite-capable source
+ * rules join the class set.
+ */
+export const loadWardenTermRewriteClasses = async (
+  root?: string
+): Promise<RegradeWardenClassSet> => {
+  if (root === undefined) {
+    return { classes: wardenTermRewriteClasses, diagnostics: [] };
+  }
+
+  const projectRules = await loadProjectWardenRules(root);
+  const projectClasses = projectRules.sourceRules.flatMap((rule) => {
+    const cls = createWardenTermRewriteClass(rule);
+    return cls === null ? [] : [cls];
+  });
+  const classes = [...wardenTermRewriteClasses, ...projectClasses];
+  return {
+    classes,
+    diagnostics: [
+      ...projectRules.diagnostics,
+      ...duplicateClassDiagnostics(root, classes),
+    ],
+  };
+};