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

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # trails
 
+## 1.0.0-beta.43
+
+### Minor Changes
+
+- [`4fb20a6`](https://github.com/outfitter-dev/trails/commit/4fb20a68e1ed98972d99fed8b2df96bfa6804bd3): Derive deterministic, provenance-bearing vocabulary plan proposals from a minimal `from`/`to` seed, including morphology, public and compound identifier review, filename and reference-closure candidates, namespace census, and validated live-topo API preserves. Classified governed transitions retain their registry identity while routing every governed form to review instead of inventing a single safe successor.
+- [`d3215b0`](https://github.com/outfitter-dev/trails/commit/d3215b0966f13af2a72ece9adbcc2c68c70f81b6): Add governed file renames to vocabulary Regrade plans, with move-first derived reference closure and persisted policy-aware evidence across CLI and MCP.
+- [`5a7d22a`](https://github.com/outfitter-dev/trails/commit/5a7d22ab9d674f86b28758f23c3e94a17efb5be1): Add three-tier vocabulary migration scope. Protected historical paths remain
+  scanned and counted as `historical-by-policy` without being rewritten, while
+  reports expose scope-tier totals and census-expected teaching-surface coverage
+  through equivalent CLI and MCP plan schemas. Applied vocabulary occurrences
+  remain auditable in history with an `applied` verdict, while policy-only
+  evidence does not make an active plan stale merely by being recorded.
+- [`88a6a62`](https://github.com/outfitter-dev/trails/commit/88a6a62a9e9e230ca6d368fa78dc3ece6c816204): Complete the v1 classification-first cutover from projection/project vocabulary
+  to derive/derived for contract-owned fact production and render/rendered for
+  surface presentation. Public type, helper, rule, relation, and report names move
+  without compatibility aliases; ordinary repository/project nouns remain
+  explicit preserves or structured review inventory.
+- [`9f0842e`](https://github.com/outfitter-dev/trails/commit/9f0842ee9d7c7155d86a4fd023760ac0a5636f5d): Retire the temporary root vocabulary-cutover toolchain now that Regrade owns
+  structured migration plans, safe rewrites, classification, census, CLI/MCP
+  reports, and immutable history. Remove the obsolete source exemptions so
+  Oxlint and Warden enforce the durable transition contract directly, and add a
+  history-driven Regrade audit surface for current-tree regression checks.
+- [`bd1bd96`](https://github.com/outfitter-dev/trails/commit/bd1bd96b90cd8b55f73061e4078a14cd75bed745): Require committed Regrade provenance for governed vocabulary transitions.
+
+  Applied governed plans now expose deterministic transition, plan, source,
+  safe-apply, and review-follow-up evidence through history results. Warden loads
+  committed history into project context, cites it for reintroduced symbols, and
+  rejects invalid or missing provenance for transitions that require Regrade in
+  the workspace that owns the governed registry, without making downstream apps
+  prove the framework's own migrations.
+  Portable validation accepts the authoritative numeric file-rename counters
+  persisted by Regrade history.
+
+### Patch Changes
+
+- [`742387e`](https://github.com/outfitter-dev/trails/commit/742387ea27e1f9fb9490147b871ae8c5a59903ae): Allow release checks to recognize changeset edits that only remove release rows
+  for packages absent from the live workspace while rejecting any additional
+  changes hidden beside that cleanup.
+- [`18a14e2`](https://github.com/outfitter-dev/trails/commit/18a14e220728be7108f3fe2864455c52305aef9f): Finish the v1 vocabulary reset cleanup by retaining the facet guard, adding a
+  durable TopoGraph artifact-family guard, teaching the live lexicon directly in
+  agent guidance, and replacing completed reset-family placeholders in public
+  Regrade examples and CLI schema help.
+- [`113aed6`](https://github.com/outfitter-dev/trails/commit/113aed62d20041e35b0cf9d6c1b1a18df4b88f57): Rename the dependency-light observability owner from `@ontrails/observe` to
+  `@ontrails/observability` as a pre-v1 hard cut. Update dependent packages,
+  documentation, package discovery, and the governed Regrade route; no
+  compatibility package or old import route is retained.
+- [`0938e7b`](https://github.com/outfitter-dev/trails/commit/0938e7badc0c5470d194139d642b673658d099e0): Fold the removed `@ontrails/tracing` package into the truthful existing
+  owners: intrinsic trace contracts remain in core, developer-state tooling now
+  lives at `@ontrails/observability/dev`, and the dependency-light OTel adapter
+  lives at `@ontrails/observability/otel`. There is intentionally no root-package
+  compatibility redirect because the former root had more than one owner.
+- [`504881d`](https://github.com/outfitter-dev/trails/commit/504881df0d15ac92c3234be068c9e1930e1ffddf): Require release checks to prove an exact governed Regrade route, or an explicit
+  classified multi-owner fold, whenever a public `@ontrails/*` package disappears
+  from the publishable workspace inventory.
+
 ## 1.0.0-beta.42
 
 ## 1.0.0-beta.41

package/README.md

@@ -18,7 +18,7 @@ Common workflows:
 - `trails wayfind`, `trails wayfind --trails --intent read`, `trails wayfind <id> --contract`, `trails wayfind <id> --deps`, `trails wayfind <id> --impact`, `trails wayfind pattern "wayfind.*"`, `trails wayfind query "release drift"`, and `trails wayfind diff ...` read graph artifacts through Wayfinder. `trails wayfind file <file> --outline` is the operator-owned live-source exception, assembled with `@ontrails/source` and enriched with saved graph context when available.
 - `trails schema <command...>` shows accepted CLI routes, aliases, flags, and schemas for an operator command or command namespace.
 - `trails warden` runs Trails governance checks for contract and architecture drift. Use `--scope-exclude <glob>` or project `warden.scope.exclude` config when local notes, scratch space, or generated state should not be governed by Warden.
-- `trails regrade plan <from> <to> --root-dir <path> --json` writes an active Regrade plan, `trails regrade plan --expand` stages wide-net review candidates in that plan, `trails regrade preview` reruns it without writing, and `trails regrade apply` consumes the plan and writes history. Use `plan --expand --dry-run` to inspect staged candidates without writing the active plan, and add `--dry-run` to `apply` to prove the apply path without mutating source. Use `trails regrade plans` and `trails regrade check` when a workspace has active plans that need inspection before apply. MCP exposes the same lifecycle as `trails_plan_regrade`, `trails_list_regrades`, `trails_check_regrade`, `trails_preview_regrade`, and `trails_apply_regrade`.
+- `trails regrade plan <from> <to> --root-dir <path> --json` writes an active Regrade plan, `trails regrade plan --expand` stages wide-net review candidates in that plan, `trails regrade preview` reruns it without writing, and `trails regrade apply` consumes the plan and writes history. The minimal `from`/`to` seed is the primary workflow: planning deterministically derives morphology proposals, source-observed naming and public-identifier review candidates, review-only filename moves with reference-closure evidence, a namespace census, and current live-topo API preserves into the artifact's `derivation` section. Each derived item records provenance; uncertain forms and file moves remain review inventory until explicitly authored into the plan. A malformed or incompatible `trails.lock` fails planning instead of silently dropping live-API preserves. Use `plan --expand --dry-run` to inspect additional observed candidates without writing the active plan, and add `--dry-run` to `apply` to prove the apply path without mutating source. Use `trails regrade plans` and `trails regrade check` when a workspace has active plans that need inspection before apply. MCP exposes the same artifact and lifecycle as `trails_plan_regrade`, `trails_list_regrades`, `trails_check_regrade`, `trails_preview_regrade`, and `trails_apply_regrade`.
 - `trails guide` remains available for compatibility; prefer `trails wayfind --source live --module <app-module>` or saved-artifact Wayfinder reads for agent navigation.
 
 Trails is contract-first: define trails once with typed input, Result output, examples, and meta; the framework derives CLI, MCP, HTTP, and future surfaces from the same contracts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/trails",
-  "version": "1.0.0-beta.42",
+  "version": "1.0.0-beta.43",
   "bin": {
     "trails": "./bin/trails.ts"
   },
@@ -27,26 +27,25 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
-    "@ontrails/adapter-kit": "^1.0.0-beta.42",
-    "@ontrails/cli": "^1.0.0-beta.42",
-    "@ontrails/commander": "^1.0.0-beta.42",
-    "@ontrails/config": "^1.0.0-beta.42",
-    "@ontrails/core": "^1.0.0-beta.42",
-    "@ontrails/http": "^1.0.0-beta.42",
-    "@ontrails/mcp": "^1.0.0-beta.42",
-    "@ontrails/observe": "^1.0.0-beta.42",
-    "@ontrails/permits": "^1.0.0-beta.42",
-    "@ontrails/regrade": "^1.0.0-beta.42",
-    "@ontrails/source": "^1.0.0-beta.42",
-    "@ontrails/topography": "^1.0.0-beta.42",
-    "@ontrails/tracing": "^1.0.0-beta.42",
-    "@ontrails/warden": "^1.0.0-beta.42",
+    "@ontrails/adapter-kit": "^1.0.0-beta.43",
+    "@ontrails/cli": "^1.0.0-beta.43",
+    "@ontrails/commander": "^1.0.0-beta.43",
+    "@ontrails/config": "^1.0.0-beta.43",
+    "@ontrails/core": "^1.0.0-beta.43",
+    "@ontrails/http": "^1.0.0-beta.43",
+    "@ontrails/mcp": "^1.0.0-beta.43",
+    "@ontrails/observability": "^1.0.0-beta.43",
+    "@ontrails/permits": "^1.0.0-beta.43",
+    "@ontrails/regrade": "^1.0.0-beta.43",
+    "@ontrails/source": "^1.0.0-beta.43",
+    "@ontrails/topography": "^1.0.0-beta.43",
+    "@ontrails/warden": "^1.0.0-beta.43",
     "commander": "^14.0.3",
     "typescript": "^5.9.3",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/cloudflare": "^1.0.0-beta.42",
-    "@ontrails/testing": "^1.0.0-beta.42"
+    "@ontrails/cloudflare": "^1.0.0-beta.43",
+    "@ontrails/testing": "^1.0.0-beta.43"
   }
 }

package/src/mcp-options.ts

@@ -21,6 +21,7 @@ export const trailsMcpIncludedTrails = [
   'guide',
   'adjust.regrade',
   'apply.regrade',
+  'audit.regrade',
   'check.regrade',
   'list.regrades',
   'plan.regrade',

package/src/regrade/audit.ts

@@ -0,0 +1,482 @@
+import {
+  InternalError,
+  isPlainObject,
+  matchesAnyPathGlob,
+  NotFoundError,
+  Result,
+  ValidationError,
+} from '@ontrails/core';
+import type { Result as TrailsResult } from '@ontrails/core';
+import {
+  listVocabularyRegradeAuditPlansFromRegistry,
+  regradeReportOutput,
+  runVocabularyRegrade,
+  vocabularyDispositionValues,
+  vocabularyRegradePlanForInput,
+} from '@ontrails/regrade';
+import type { VocabularyRegradePlan } from '@ontrails/regrade';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { z } from 'zod';
+
+import { deriveLiveApiPreserveInventory } from './live-api-preserve.js';
+import {
+  regradePlanArtifactSchema,
+  rootRelativePath,
+} from './plan-artifact.js';
+
+export const regradeAuditInputSchema = z.object({
+  failOnOpen: z
+    .boolean()
+    .default(false)
+    .describe('Fail when a completed transition has current-tree residue'),
+  includeEntries: z
+    .enum(['actionable', 'all'])
+    .default('actionable')
+    .describe('Report entry detail to include for each audited transition'),
+  rootDir: z.string().optional().describe('Workspace root directory'),
+  transitionIds: z
+    .array(z.string().min(1))
+    .optional()
+    .describe('Governed transition ids to audit; defaults to applied history'),
+});
+
+const regradeAuditTransitionSchema = z.object({
+  report: z
+    .object({
+      dispositions: z
+        .partialRecord(
+          z.enum(vocabularyDispositionValues),
+          z.number().int().nonnegative()
+        )
+        .describe('Current Markdown occurrence counts by classification'),
+      entries: regradeReportOutput.shape.entries
+        .readonly()
+        .describe('Actionable file-level residue details'),
+      occurrences: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe('Total classified Markdown occurrences'),
+      open: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe('Unresolved Markdown occurrences'),
+      scanned: z.number().int().nonnegative().describe('Files scanned'),
+      status: z.enum(['green', 'open']).describe('Transition audit status'),
+    })
+    .describe('Concise current-tree audit of the latest applied plan'),
+  source: z.string().describe('Committed Regrade history artifact'),
+  transitionId: z.string().describe('Stable Regrade transition identity'),
+});
+
+export const regradeAuditOutputSchema = z.object({
+  gate: z.object({
+    open: z
+      .number()
+      .int()
+      .nonnegative()
+      .describe('Current-tree unresolved occurrence count'),
+    status: z
+      .enum(['green', 'open'])
+      .describe('Whether every audited transition remains complete'),
+  }),
+  transitions: z
+    .array(regradeAuditTransitionSchema)
+    .describe('Applied vocabulary transitions audited against current source'),
+});
+
+const regradeAuditHistoryPlanSchema = z.object({
+  id: z.string().min(1),
+  runs: z.array(z.object({ plan: regradePlanArtifactSchema })).min(1),
+});
+
+export type RegradeAuditInput = z.output<typeof regradeAuditInputSchema>;
+export type RegradeAuditOutput = z.output<typeof regradeAuditOutputSchema>;
+
+interface RegradeAuditCandidate {
+  readonly plan: VocabularyRegradePlan;
+  readonly source: string;
+  readonly transitionId: string;
+}
+
+const historyTransitionId = (rawHistory: unknown): string | undefined => {
+  if (!isPlainObject(rawHistory)) {
+    return undefined;
+  }
+  const { id, runs } = rawHistory;
+  const latestRun = Array.isArray(runs) ? runs.at(-1) : undefined;
+  const planArtifact = isPlainObject(latestRun) ? latestRun['plan'] : undefined;
+  const plan = isPlainObject(planArtifact) ? planArtifact['plan'] : undefined;
+  const planId = isPlainObject(plan) ? plan['id'] : undefined;
+  if (typeof planId === 'string') {
+    return planId;
+  }
+  return typeof id === 'string' ? id : undefined;
+};
+
+const selectedHistoryFileNamesFor = (
+  selectedTransitionIds: ReadonlySet<string> | null,
+  registryPlansById: ReadonlyMap<string, VocabularyRegradePlan>
+): ReadonlySet<string> =>
+  new Set(
+    selectedTransitionIds === null
+      ? []
+      : [...selectedTransitionIds].flatMap((transitionId) => {
+          const plan = registryPlansById.get(transitionId);
+          return plan === undefined ? [] : [`${plan.from}-to-${plan.to}.json`];
+        })
+  );
+
+const historyIsSelected = (
+  rawHistory: unknown,
+  historyFile: string,
+  selectedTransitionIds: ReadonlySet<string> | null,
+  selectedHistoryFileNames: ReadonlySet<string>
+): boolean =>
+  selectedTransitionIds === null ||
+  selectedTransitionIds.has(historyTransitionId(rawHistory) ?? '') ||
+  selectedHistoryFileNames.has(basename(historyFile));
+
+export const mergeAuditPlan = (
+  latestPlan: VocabularyRegradePlan,
+  registryPlan: VocabularyRegradePlan | undefined
+): VocabularyRegradePlan => {
+  if (registryPlan === undefined) {
+    return latestPlan;
+  }
+  const policyClassified = [
+    ...(latestPlan.scope?.policyClassified ?? []),
+    ...(registryPlan.scope?.policyClassified ?? []),
+  ];
+  const teachingSurfaces = [
+    ...new Set([
+      ...(latestPlan.scope?.teachingSurfaces ?? []),
+      ...(registryPlan.scope?.teachingSurfaces ?? []),
+    ]),
+  ].toSorted();
+  const scope =
+    latestPlan.scope === undefined && registryPlan.scope === undefined
+      ? undefined
+      : {
+          ...registryPlan.scope,
+          ...latestPlan.scope,
+          ...(policyClassified.length === 0 ? {} : { policyClassified }),
+          ...(teachingSurfaces.length === 0 ? {} : { teachingSurfaces }),
+        };
+  return {
+    ...registryPlan,
+    ...latestPlan,
+    preserve: [
+      ...(latestPlan.preserve ?? []),
+      ...(registryPlan.preserve ?? []),
+    ],
+    ...(scope === undefined ? {} : { scope }),
+  };
+};
+
+const readRegradeAuditCandidates = (
+  rootDir: string,
+  selectedTransitionIds: ReadonlySet<string> | null
+): TrailsResult<readonly RegradeAuditCandidate[], Error> => {
+  const historyDir = join(rootDir, '.trails', 'regrade', 'history');
+  if (!existsSync(historyDir)) {
+    return Result.ok([]);
+  }
+  let historyFiles: readonly string[];
+  try {
+    historyFiles = readdirSync(historyDir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+      .map((entry) => join(historyDir, entry.name))
+      .toSorted();
+  } catch (error) {
+    return Result.err(
+      new InternalError('Failed to list Regrade history artifacts.', {
+        ...(error instanceof Error ? { cause: error } : {}),
+        context: { historyDir },
+      })
+    );
+  }
+  const registryPlansById = new Map(
+    listVocabularyRegradeAuditPlansFromRegistry().flatMap((plan) =>
+      plan.id === undefined ? [] : [[plan.id, plan] as const]
+    )
+  );
+  const selectedHistoryFileNames = selectedHistoryFileNamesFor(
+    selectedTransitionIds,
+    registryPlansById
+  );
+  const selectedHistoriesHaveCanonicalFileNames =
+    selectedTransitionIds !== null &&
+    selectedHistoryFileNames.size === selectedTransitionIds.size;
+  const candidates: RegradeAuditCandidate[] = [];
+  for (const historyFile of historyFiles) {
+    if (
+      selectedHistoriesHaveCanonicalFileNames &&
+      !selectedHistoryFileNames.has(basename(historyFile))
+    ) {
+      continue;
+    }
+    let rawHistory: unknown;
+    try {
+      rawHistory = JSON.parse(readFileSync(historyFile, 'utf8'));
+    } catch (error) {
+      return Result.err(
+        new InternalError('Failed to read Regrade history audit plan.', {
+          ...(error instanceof Error ? { cause: error } : {}),
+          context: { historyFile },
+        })
+      );
+    }
+    if (
+      !historyIsSelected(
+        rawHistory,
+        historyFile,
+        selectedTransitionIds,
+        selectedHistoryFileNames
+      )
+    ) {
+      continue;
+    }
+    const history = regradeAuditHistoryPlanSchema.safeParse(rawHistory);
+    if (!history.success) {
+      return Result.err(
+        new ValidationError('Invalid Regrade history audit plan.', {
+          context: { historyFile, issues: history.error.issues },
+        })
+      );
+    }
+    const latestPlan = history.data.runs.at(-1)?.plan.plan as
+      | VocabularyRegradePlan
+      | undefined;
+    if (latestPlan?.kind !== 'vocabulary') {
+      continue;
+    }
+    const transitionId = latestPlan.id ?? history.data.id;
+    if (
+      selectedTransitionIds !== null &&
+      !selectedTransitionIds.has(transitionId)
+    ) {
+      continue;
+    }
+    const registryPlan =
+      registryPlansById.get(transitionId) ??
+      vocabularyRegradePlanForInput(latestPlan.from, latestPlan.to) ??
+      undefined;
+    candidates.push({
+      plan: mergeAuditPlan(latestPlan, registryPlan),
+      source: rootRelativePath(rootDir, historyFile),
+      transitionId,
+    });
+  }
+  return Result.ok(
+    candidates.toSorted((left, right) =>
+      left.transitionId.localeCompare(right.transitionId)
+    )
+  );
+};
+
+type VocabularyPolicyClassified = NonNullable<
+  NonNullable<VocabularyRegradePlan['scope']>['policyClassified']
+>;
+
+export const projectPolicyClassifiedForMarkdownAudit = (
+  plan: VocabularyRegradePlan
+): VocabularyPolicyClassified | undefined =>
+  plan.scope?.policyClassified
+    ?.map((policy) => ({
+      ...policy,
+      paths: policy.paths.filter(
+        (path) =>
+          !plan.scope?.exclude?.some(
+            (excludedPath) =>
+              excludedPath === path || matchesAnyPathGlob(path, [excludedPath])
+          )
+      ),
+    }))
+    .filter((policy) => policy.paths.length > 0)
+    .map((policy) => {
+      const hasExplicitMarkdownPath = policy.paths.some((path) => {
+        const extension = extname(path);
+        return extension === '.md' || extension === '.mdx';
+      });
+      if (policy.expectMatches !== true || hasExplicitMarkdownPath) {
+        return policy;
+      }
+      // A Markdown-only audit cannot prove evidence for extensionless source
+      // globs. Markdown evidence requirements must name .md/.mdx explicitly.
+      const { expectMatches: _, ...markdownPolicy } = policy;
+      return markdownPolicy;
+    });
+
+export const projectExcludesForMarkdownAudit = (
+  plan: VocabularyRegradePlan,
+  policyClassified: VocabularyPolicyClassified | undefined
+): readonly string[] | undefined =>
+  plan.scope?.exclude?.filter(
+    (excludedPath) =>
+      !policyClassified?.some((policy) =>
+        policy.paths.some((path) => matchesAnyPathGlob(excludedPath, [path]))
+      )
+  );
+
+export const projectIncludesForMarkdownAudit = (
+  plan: VocabularyRegradePlan,
+  policyClassified: VocabularyPolicyClassified | undefined
+): readonly string[] | undefined => {
+  if (plan.scope?.include === undefined) {
+    return undefined;
+  }
+  return [
+    ...new Set([
+      ...plan.scope.include,
+      ...(policyClassified?.flatMap((policy) => policy.paths) ?? []),
+      ...(plan.scope.teachingSurfaces ?? []),
+    ]),
+  ].toSorted();
+};
+
+const runRegradeAuditCandidate = async (
+  candidate: RegradeAuditCandidate,
+  input: RegradeAuditInput,
+  rootDir: string
+): Promise<TrailsResult<RegradeAuditOutput['transitions'][number], Error>> => {
+  const policyClassified = projectPolicyClassifiedForMarkdownAudit(
+    candidate.plan
+  );
+  const exclude = projectExcludesForMarkdownAudit(
+    candidate.plan,
+    policyClassified
+  );
+  const include = projectIncludesForMarkdownAudit(
+    candidate.plan,
+    policyClassified
+  );
+  const auditPlan: VocabularyRegradePlan = {
+    ...candidate.plan,
+    scope: {
+      ...candidate.plan.scope,
+      extensions: ['.md', '.mdx'],
+      ...(exclude === undefined ? {} : { exclude }),
+      ...(include === undefined ? {} : { include }),
+      ...(policyClassified === undefined ? {} : { policyClassified }),
+    },
+  };
+  const preserveResult = await deriveLiveApiPreserveInventory(
+    auditPlan,
+    rootDir
+  );
+  if (preserveResult.isErr()) {
+    return preserveResult;
+  }
+  const reportResult = runVocabularyRegrade({
+    apply: false,
+    includeEntries: input.includeEntries,
+    plan: auditPlan,
+    ...(preserveResult.value.length === 0
+      ? {}
+      : { preserveInventory: preserveResult.value }),
+    root: rootDir,
+  });
+  if (reportResult.isErr()) {
+    return reportResult;
+  }
+  if (reportResult.value === null) {
+    return Result.err(
+      new NotFoundError('Regrade audit root could not be collected.', {
+        context: { rootDir },
+      })
+    );
+  }
+  const { run } = reportResult.value;
+  if (run === undefined) {
+    return Result.err(
+      new InternalError('Regrade audit did not produce a vocabulary run.', {
+        context: { transitionId: candidate.transitionId },
+      })
+    );
+  }
+  const output = regradeAuditTransitionSchema.safeParse({
+    report: {
+      dispositions: run.report.dispositions,
+      entries: reportResult.value.entries,
+      occurrences: run.ledger.occurrences.length,
+      open: run.report.open,
+      scanned: reportResult.value.scanned,
+      status: run.report.gate.status,
+    },
+    source: candidate.source,
+    transitionId: candidate.transitionId,
+  });
+  if (!output.success) {
+    return Result.err(
+      new InternalError('Regrade audit produced an invalid transition.', {
+        context: {
+          issues: output.error.issues,
+          transitionId: candidate.transitionId,
+        },
+      })
+    );
+  }
+  return Result.ok(output.data);
+};
+
+export const auditRegradeHistory = async (
+  input: RegradeAuditInput,
+  rootDir: string
+): Promise<TrailsResult<RegradeAuditOutput, Error>> => {
+  const selectedTransitionIds =
+    input.transitionIds === undefined ? null : new Set(input.transitionIds);
+  const candidatesResult = readRegradeAuditCandidates(
+    rootDir,
+    selectedTransitionIds
+  );
+  if (candidatesResult.isErr()) {
+    return candidatesResult;
+  }
+  const candidates = candidatesResult.value;
+  if (selectedTransitionIds !== null) {
+    const auditedTransitionIds = new Set(
+      candidates.map((candidate) => candidate.transitionId)
+    );
+    const missingTransitionIds = [...selectedTransitionIds].filter(
+      (transitionId) => !auditedTransitionIds.has(transitionId)
+    );
+    if (missingTransitionIds.length > 0) {
+      return Result.err(
+        new ValidationError(
+          'Selected Regrade audit transitions do not have committed history.',
+          { context: { transitionIds: missingTransitionIds.toSorted() } }
+        )
+      );
+    }
+  }
+  const transitions: RegradeAuditOutput['transitions'][number][] = [];
+  for (const candidate of candidates) {
+    const transitionResult = await runRegradeAuditCandidate(
+      candidate,
+      input,
+      rootDir
+    );
+    if (transitionResult.isErr()) {
+      return transitionResult;
+    }
+    transitions.push(transitionResult.value);
+  }
+  const open = transitions.reduce(
+    (total, transition) => total + transition.report.open,
+    0
+  );
+  return Result.ok({
+    gate: {
+      open,
+      status: transitions.some(
+        (transition) => transition.report.status === 'open'
+      )
+        ? 'open'
+        : 'green',
+    },
+    transitions,
+  });
+};