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

package/src/rules/no-retired-cross-vocabulary.ts

@@ -8,17 +8,25 @@
  */
 import { resolve, sep } from 'node:path';
 
+import { requireGovernedVocabularyTransition } from './retired-vocabulary.js';
 import type { WardenDiagnostic, WardenFix, WardenRule } from './types.js';
 
 const RULE_NAME = 'no-retired-cross-vocabulary';
 
-const SAFE_REWRITES = [
-  { from: 'ctx.cross', to: 'ctx.compose' },
-  { from: 'crossInput', to: 'composeInput' },
-  { from: 'crosses', to: 'composes' },
-] as const;
+const CROSS_COMPOSE_TRANSITION =
+  requireGovernedVocabularyTransition('cross-compose');
 
-const REVIEW_TERMS = ['Cross', 'cross'] as const;
+if (CROSS_COMPOSE_TRANSITION.target.kind !== 'single') {
+  throw new Error('cross-compose transition must have a single target.');
+}
+
+const COMPOSE_TARGET = CROSS_COMPOSE_TRANSITION.target.to;
+
+const SAFE_REWRITES = Object.entries(
+  CROSS_COMPOSE_TRANSITION.safeRewriteForms
+).map(([from, to]) => ({ from, to }));
+
+const REVIEW_TERMS = CROSS_COMPOSE_TRANSITION.reviewForms;
 
 const IDENTIFIER_CHAR = /[$0-9A-Z_a-z]/u;
 
@@ -28,6 +36,8 @@ const ALLOWED_PATH_SUFFIXES: readonly string[] = [
   '/docs/adr/0049-composition-is-compose-not-cross.md',
   '/packages/warden/src/rules/no-retired-cross-vocabulary.ts',
   '/packages/warden/src/rules/metadata.ts',
+  '/packages/warden/src/rules/retired-vocabulary.ts',
+  '/packages/warden/src/trails/governed-symbol-residue.trail.ts',
   '/packages/warden/src/trails/no-retired-cross-vocabulary.trail.ts',
   '/scripts/vocab-cutover-rewrite.ts',
 ];
@@ -40,7 +50,7 @@ interface SafeRewriteMatch {
 
 interface ReviewMatch {
   readonly index: number;
-  readonly term: (typeof REVIEW_TERMS)[number];
+  readonly term: string;
 }
 
 const normalizePath = (filePath: string): string =>
@@ -150,7 +160,7 @@ const safeFix = (match: SafeRewriteMatch): WardenFix => ({
 
 const reviewFix = (term: string): WardenFix => ({
   class: 'term-rewrite',
-  reason: `Retired composition vocabulary '${term}' appears in a larger or ambiguous form. Review before migrating to compose vocabulary.`,
+  reason: `Retired composition vocabulary '${term}' appears in a larger or ambiguous form. Review before migrating to ${COMPOSE_TARGET} vocabulary.`,
   safety: 'review',
 });
 
@@ -158,7 +168,7 @@ const safeMessage = (match: SafeRewriteMatch): string =>
   `Retired composition vocabulary '${match.from}' should be '${match.to}' after the beta.19 compose cutover.`;
 
 const reviewMessage = (term: string): string =>
-  `Retired composition vocabulary '${term}' needs review before migrating to compose vocabulary.`;
+  `Retired composition vocabulary '${term}' needs review before migrating to ${COMPOSE_TARGET} vocabulary.`;
 
 export const noRetiredCrossVocabulary: WardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {

package/src/rules/permit-governance.ts

@@ -10,7 +10,7 @@ const toWardenDiagnostic = (
   line: 1,
   message: diagnostic.message,
   rule: `permit.${diagnostic.rule}`,
-  severity: diagnostic.severity === 'error' ? 'error' : 'warn',
+  severity: diagnostic.severity,
 });
 
 export const permitGovernance: TopoAwareWardenRule = {

package/src/rules/public-export-example-coverage.ts

@@ -113,6 +113,11 @@ export const PUBLIC_API_EXAMPLE_TARGETS: readonly PublicApiPackageTarget[] = [
     minimumExports: ['createApp', 'surface'],
     packageName: '@ontrails/hono',
   },
+  {
+    indexPath: 'adapters/cloudflare/src/index.ts',
+    minimumExports: ['createWorkersHandler', 'cloudflareKv'],
+    packageName: '@ontrails/cloudflare',
+  },
 ] as const;
 
 export interface ResolvedPublicApiTarget extends PublicApiPackageTarget {

package/src/rules/public-internal-deep-imports.ts

@@ -1,5 +1,6 @@
 import { existsSync, realpathSync } from 'node:fs';
 import { resolve, sep } from 'node:path';
+import { matchesPathGlob } from '@ontrails/core';
 
 import {
   extractStringLiteral,
@@ -303,50 +304,6 @@ const rootBarrelDiagnostics = (
 const stripLeadingDotSlash = (path: string): string =>
   path.startsWith('./') ? path.slice(2) : path;
 
-const escapeRegExp = (value: string): string =>
-  value.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
-const wildcardPatternSource = (pattern: string): string => {
-  let regexSource = '';
-  for (let index = 0; index < pattern.length; index += 1) {
-    const char = pattern[index];
-    if (char === '*') {
-      if (pattern[index + 1] === '*') {
-        regexSource += '.*';
-        index += 1;
-      } else {
-        regexSource += '[^/]*';
-      }
-      continue;
-    }
-    regexSource += escapeRegExp(char ?? '');
-  }
-  return regexSource;
-};
-
-const segmentWildcardPatternCovers = (
-  filePath: string,
-  pattern: string
-): boolean => new RegExp(`^${wildcardPatternSource(pattern)}$`).test(filePath);
-
-const deepWildcardPatternCovers = (
-  filePath: string,
-  pattern: string,
-  globIndex: number
-): boolean => {
-  const prefix = pattern.slice(0, globIndex + 1);
-  if (!filePath.startsWith(prefix)) {
-    return false;
-  }
-  const suffixPattern = pattern.slice(globIndex + '/**/'.length);
-  if (suffixPattern.length === 0) {
-    return true;
-  }
-  const remainingPath = filePath.slice(prefix.length);
-  const regexSource = `^(?:.*/)?${wildcardPatternSource(suffixPattern)}$`;
-  return new RegExp(regexSource).test(remainingPath);
-};
-
 const filePatternCovers = (filePath: string, pattern: string): boolean => {
   const normalizedFilePath = normalizePath(stripLeadingDotSlash(filePath));
   const normalizedPattern = normalizePath(stripLeadingDotSlash(pattern));
@@ -359,27 +316,10 @@ const filePatternCovers = (filePath: string, pattern: string): boolean => {
   if (normalizedPattern === '**') {
     return true;
   }
-  if (normalizedPattern.endsWith('/**')) {
-    const prefix = normalizedPattern.slice(0, -2);
-    return normalizedFilePath.startsWith(prefix);
-  }
-
-  const globIndex = normalizedPattern.indexOf('/**/');
-  if (globIndex === -1) {
-    if (normalizedPattern.includes('*')) {
-      return segmentWildcardPatternCovers(
-        normalizedFilePath,
-        normalizedPattern
-      );
-    }
+  if (!normalizedPattern.includes('*') && !normalizedPattern.includes('?')) {
     return normalizedFilePath.startsWith(`${normalizedPattern}/`);
   }
-
-  return deepWildcardPatternCovers(
-    normalizedFilePath,
-    normalizedPattern,
-    globIndex
-  );
+  return matchesPathGlob(normalizedFilePath, normalizedPattern);
 };
 
 const filesCoverTarget = (

package/src/rules/registry-names.ts

@@ -16,10 +16,12 @@ import { deadInternalTrail } from './dead-internal-trail.js';
 import { deadPublicTrail } from './dead-public-trail.js';
 import { draftFileMarking } from './draft-file-marking.js';
 import { draftVisibleDebt } from './draft-visible-debt.js';
+import { duplicateExportedSymbol } from './duplicate-exported-symbol.js';
 import { duplicatePublicContract } from './duplicate-public-contract.js';
 import { errorMappingCompleteness } from './error-mapping-completeness.js';
 import { exampleValid } from './example-valid.js';
 import { firesDeclarations } from './fires-declarations.js';
+import { governedSymbolResidue } from './governed-symbol-residue.js';
 import { implementationReturnsResult } from './implementation-returns-result.js';
 import { incompleteAccessorForStandardOp } from './incomplete-accessor-for-standard-op.js';
 import { incompleteCrud } from './incomplete-crud.js';
@@ -30,6 +32,7 @@ import { missingReconcile } from './missing-reconcile.js';
 import { missingVisibility } from './missing-visibility.js';
 import { noDevPermitInSource } from './no-dev-permit-in-source.js';
 import { noDestructuredCompose } from './no-destructured-compose.js';
+import { noLegacyCliAliasExport } from './no-legacy-cli-alias-export.js';
 import { noLegacyLayerImports } from './no-legacy-layer-imports.js';
 import { noDirectImplementationCall } from './no-direct-implementation-call.js';
 import { noNativeErrorResult } from './no-native-error-result.js';
@@ -58,8 +61,10 @@ import { resourceMockCoverage } from './resource-mock-coverage.js';
 import { scheduledDestroyIntent } from './scheduled-destroy-intent.js';
 import { signalGraphCoaching } from './signal-graph-coaching.js';
 import { staticResourceAccessorPreference } from './static-resource-accessor-preference.js';
-import { surfaceFacetCoherence } from './surface-facet-coherence.js';
+import { surfaceOverlayCoherence } from './surface-overlay-coherence.js';
+import { surfaceTrailheadCoherence } from './surface-trailhead-coherence.js';
 import { trailForkCoaching } from './trail-fork-coaching.js';
+import { trailheadOverrideDivergence } from './trailhead-override-divergence.js';
 import {
   forkWithoutPreservedBlaze,
   markerSchemaUnsupported,
@@ -94,12 +99,14 @@ export const registeredRuleNames: readonly string[] = [
   deadInternalTrail.name,
   deadPublicTrail.name,
   deprecationWithoutGuidance.name,
+  duplicateExportedSymbol.name,
   duplicatePublicContract.name,
   draftFileMarking.name,
   draftVisibleDebt.name,
   errorMappingCompleteness.name,
   exampleValid.name,
   firesDeclarations.name,
+  governedSymbolResidue.name,
   forkWithoutPreservedBlaze.name,
   implementationReturnsResult.name,
   incompleteAccessorForStandardOp.name,
@@ -112,6 +119,7 @@ export const registeredRuleNames: readonly string[] = [
   missingVisibility.name,
   noDevPermitInSource.name,
   noDestructuredCompose.name,
+  noLegacyCliAliasExport.name,
   noLegacyLayerImports.name,
   noDirectImplementationCall.name,
   noNativeErrorResult.name,
@@ -141,8 +149,10 @@ export const registeredRuleNames: readonly string[] = [
   scheduledDestroyIntent.name,
   signalGraphCoaching.name,
   staticResourceAccessorPreference.name,
-  surfaceFacetCoherence.name,
+  surfaceOverlayCoherence.name,
+  surfaceTrailheadCoherence.name,
   trailForkCoaching.name,
+  trailheadOverrideDivergence.name,
   unmaterializedActivationSource.name,
   unreachableDetourShadowing.name,
   validDetourContract.name,

package/src/rules/retired-vocabulary.ts

@@ -0,0 +1,396 @@
+import { z } from 'zod';
+
+export const governedVocabularyTransitionStatuses = [
+  'planned',
+  'active',
+  'complete',
+] as const;
+
+const governedVocabularySingleTargetSchema = z.object({
+  kind: z.literal('single'),
+  to: z.string().min(1),
+});
+
+const governedVocabularyClassifiedTargetSchema = z.object({
+  guidance: z.string().min(1),
+  kind: z.literal('classified'),
+  options: z
+    .array(
+      z.object({
+        to: z.string().min(1),
+        when: z.string().min(1),
+      })
+    )
+    .min(1),
+});
+
+export const governedVocabularyTargetSchema = z.discriminatedUnion('kind', [
+  governedVocabularySingleTargetSchema,
+  governedVocabularyClassifiedTargetSchema,
+]);
+
+export const governedVocabularyPreserveRuleSchema = z.object({
+  paths: z.array(z.string().min(1)).optional(),
+  pattern: z.string().min(1),
+  reason: z.string().min(1),
+});
+
+export const governedVocabularyScopeSchema = z.object({
+  exclude: z.array(z.string().min(1)).optional(),
+  extensions: z.array(z.string().min(1)).optional(),
+  ignoredDirectories: z.array(z.string().min(1)).optional(),
+  include: z.array(z.string().min(1)).optional(),
+});
+
+export const governedVocabularySymbolRenameSchema = z.object({
+  from: z.string().min(1),
+  reviewDeclarationTypes: z.array(z.string().min(1)).default([]),
+  to: z.string().min(1),
+});
+
+export const governedVocabularyLiteralRenameSchema = z.object({
+  from: z.string().min(1),
+  to: z.string().min(1),
+});
+
+export const governedVocabularyTransitionSchema = z.object({
+  codeIdentifiers: z.array(z.string().min(1)).default([]),
+  docs: z.object({
+    guidance: z.array(z.string().min(1)).default([]),
+    summary: z.string().min(1),
+  }),
+  from: z.string().min(1),
+  id: z.string().min(1),
+  intent: z.string().min(1),
+  kind: z.literal('vocabulary'),
+  oldForms: z.array(z.string().min(1)).min(1),
+  overrides: z.record(z.string().min(1), z.string().min(1)).default({}),
+  preserve: z.array(governedVocabularyPreserveRuleSchema).default([]),
+  reviewForms: z.array(z.string().min(1)).default([]),
+  safeRewriteForms: z.record(z.string().min(1), z.string().min(1)).default({}),
+  scope: governedVocabularyScopeSchema.optional(),
+  status: z.enum(governedVocabularyTransitionStatuses),
+  stringLiteralRenames: z
+    .array(governedVocabularyLiteralRenameSchema)
+    .default([]),
+  symbolRenames: z.array(governedVocabularySymbolRenameSchema).default([]),
+  target: governedVocabularyTargetSchema,
+});
+
+export const governedVocabularyRegistrySchema = z
+  .array(governedVocabularyTransitionSchema)
+  .superRefine((transitions, ctx) => {
+    const seenIds = new Set<string>();
+    const seenFrom = new Set<string>();
+
+    for (const [index, transition] of transitions.entries()) {
+      if (seenIds.has(transition.id)) {
+        ctx.addIssue({
+          code: 'custom',
+          message: `Duplicate governed vocabulary transition id "${transition.id}".`,
+          path: [index, 'id'],
+        });
+      }
+      seenIds.add(transition.id);
+
+      if (seenFrom.has(transition.from)) {
+        ctx.addIssue({
+          code: 'custom',
+          message: `Duplicate governed vocabulary source "${transition.from}".`,
+          path: [index, 'from'],
+        });
+      }
+      seenFrom.add(transition.from);
+    }
+  });
+
+export type GovernedVocabularyPreserveRule = z.output<
+  typeof governedVocabularyPreserveRuleSchema
+>;
+export type GovernedVocabularyScope = z.output<
+  typeof governedVocabularyScopeSchema
+>;
+export type GovernedVocabularyTarget = z.output<
+  typeof governedVocabularyTargetSchema
+>;
+export type GovernedVocabularySymbolRename = z.output<
+  typeof governedVocabularySymbolRenameSchema
+>;
+export type GovernedVocabularyLiteralRename = z.output<
+  typeof governedVocabularyLiteralRenameSchema
+>;
+export type GovernedVocabularyTransition = z.output<
+  typeof governedVocabularyTransitionSchema
+>;
+export type GovernedVocabularyTransitionInput = z.input<
+  typeof governedVocabularyTransitionSchema
+>;
+
+const defineTransition = (
+  input: GovernedVocabularyTransitionInput
+): GovernedVocabularyTransition =>
+  governedVocabularyTransitionSchema.parse(input);
+
+const reviewFunctionParamDeclarations = {
+  reviewDeclarationTypes: ['FunctionParam'],
+};
+
+const v1VocabularyHistoricalExcludes = [
+  '.agents/memory/**',
+  '.agents/plans/archive/**',
+  '.changeset/**',
+  '**/CHANGELOG.md',
+];
+
+const v1VocabularySelfExcludes = [
+  'packages/warden/src/rules/retired-vocabulary.ts',
+];
+
+const unique = (values: readonly string[]): string[] => [...new Set(values)];
+
+const defineV1Transition = (
+  input: GovernedVocabularyTransitionInput
+): GovernedVocabularyTransition =>
+  defineTransition({
+    ...input,
+    scope: {
+      ...input.scope,
+      exclude: unique([
+        ...v1VocabularyHistoricalExcludes,
+        ...v1VocabularySelfExcludes,
+        ...(input.scope?.exclude ?? []),
+      ]),
+    },
+  });
+
+export const governedVocabularyTransitions =
+  governedVocabularyRegistrySchema.parse([
+    defineTransition({
+      codeIdentifiers: ['ctx.cross', 'crossInput', 'crosses'],
+      docs: {
+        guidance: [
+          'Exact ctx.cross, crossInput, and crosses forms are mechanically rewritten.',
+          'Broader cross or Cross forms route to review because a text rule cannot prove the intended symbol boundary.',
+        ],
+        summary:
+          'Beta.19 retired cross composition vocabulary in favor of compose.',
+      },
+      from: 'cross',
+      id: 'cross-compose',
+      intent:
+        'Retire beta.19 cross composition vocabulary in favor of compose.',
+      kind: 'vocabulary',
+      oldForms: ['cross', 'Cross', 'crosses', 'crossInput', 'ctx.cross'],
+      reviewForms: ['Cross', 'cross'],
+      safeRewriteForms: {
+        crossInput: 'composeInput',
+        crosses: 'composes',
+        'ctx.cross': 'ctx.compose',
+      },
+      status: 'complete',
+      symbolRenames: [
+        { ...reviewFunctionParamDeclarations, from: 'cross', to: 'compose' },
+        {
+          ...reviewFunctionParamDeclarations,
+          from: 'crossInput',
+          to: 'composeInput',
+        },
+        { ...reviewFunctionParamDeclarations, from: 'crosses', to: 'composes' },
+      ],
+      target: { kind: 'single', to: 'compose' },
+    }),
+    defineV1Transition({
+      codeIdentifiers: ['blaze', 'blazes'],
+      docs: {
+        guidance: [
+          'Treat code/API identifiers as governed symbols, not prose-only vocabulary.',
+          'Review inflected forms such as blazed or blazing instead of forcing a mechanical rewrite.',
+        ],
+        summary:
+          'The authored trail behavior field is moving from blaze to implementation.',
+      },
+      from: 'blaze',
+      id: 'v1-blaze-implementation',
+      intent:
+        'Move the authored trail behavior field from blaze to implementation for v1.',
+      kind: 'vocabulary',
+      oldForms: ['blaze', 'blazes', 'Blaze'],
+      reviewForms: ['Blaze', 'blazing', 'blazed', 'trailblaze'],
+      safeRewriteForms: {
+        blaze: 'implementation',
+        blazes: 'implementations',
+      },
+      status: 'planned',
+      symbolRenames: [
+        {
+          ...reviewFunctionParamDeclarations,
+          from: 'blaze',
+          to: 'implementation',
+        },
+        {
+          ...reviewFunctionParamDeclarations,
+          from: 'blazes',
+          to: 'implementations',
+        },
+      ],
+      target: { kind: 'single', to: 'implementation' },
+    }),
+    defineV1Transition({
+      codeIdentifiers: ['contour', 'contours'],
+      docs: {
+        guidance: [
+          'Keep domain-object semantics distinct from entities in app data until the occurrence is classified.',
+        ],
+        summary:
+          'The domain object declaration term is moving from contour to entity.',
+      },
+      from: 'contour',
+      id: 'v1-contour-entity',
+      intent:
+        'Move the domain object declaration vocabulary from contour to entity for v1.',
+      kind: 'vocabulary',
+      oldForms: ['contour', 'contours', 'Contour'],
+      reviewForms: ['Contour'],
+      safeRewriteForms: {
+        contour: 'entity',
+        contours: 'entities',
+      },
+      status: 'planned',
+      symbolRenames: [
+        { ...reviewFunctionParamDeclarations, from: 'contour', to: 'entity' },
+        {
+          ...reviewFunctionParamDeclarations,
+          from: 'contours',
+          to: 'entities',
+        },
+      ],
+      target: { kind: 'single', to: 'entity' },
+    }),
+    defineV1Transition({
+      codeIdentifiers: [
+        'facets',
+        'facetId',
+        'McpSurfaceFacetMap',
+        'surface-facet-coherence',
+        'wayfind.facets',
+      ],
+      docs: {
+        guidance: [
+          'A trailhead is one grouped surface entry fronting several trails while preserving member identity.',
+          'Code/API identifiers remain governed symbols and need structured preservation before broad application.',
+        ],
+        summary:
+          'The grouped surface entry term is moving from facet to trailhead.',
+      },
+      from: 'facet',
+      id: 'v1-facet-trailhead',
+      intent:
+        'Move grouped surface entry vocabulary from facet to trailhead for v1.',
+      kind: 'vocabulary',
+      oldForms: ['facet', 'facets', 'Facet'],
+      reviewForms: ['Facet'],
+      safeRewriteForms: {
+        facet: 'trailhead',
+        facets: 'trailheads',
+      },
+      status: 'complete',
+      stringLiteralRenames: [
+        { from: 'surface-facet-coherence', to: 'surface-trailhead-coherence' },
+        { from: 'wayfind.facets', to: 'wayfind.trailheads' },
+      ],
+      symbolRenames: [
+        { ...reviewFunctionParamDeclarations, from: 'facet', to: 'trailhead' },
+        {
+          ...reviewFunctionParamDeclarations,
+          from: 'facets',
+          to: 'trailheads',
+        },
+        {
+          ...reviewFunctionParamDeclarations,
+          from: 'facetId',
+          to: 'trailheadId',
+        },
+        {
+          ...reviewFunctionParamDeclarations,
+          from: 'McpSurfaceFacetMap',
+          to: 'McpSurfaceTrailheadMap',
+        },
+      ],
+      target: { kind: 'single', to: 'trailhead' },
+    }),
+    defineV1Transition({
+      codeIdentifiers: [],
+      docs: {
+        guidance: [
+          'Use derive for contract-owned fact production.',
+          'Use render for surface- or operator-facing presentation.',
+          'Route every occurrence to review until the stage is classified.',
+        ],
+        summary: 'Projection vocabulary splits by stage into derive or render.',
+      },
+      from: 'projection',
+      id: 'v1-projection-derive-render',
+      intent:
+        'Split projection vocabulary into derive/render by lifecycle stage for v1.',
+      kind: 'vocabulary',
+      oldForms: ['projection', 'projections', 'project', 'projected'],
+      reviewForms: ['projection', 'projections', 'project', 'projected'],
+      safeRewriteForms: {},
+      status: 'planned',
+      target: {
+        guidance:
+          'No single replacement is safe. Classify by whether the occurrence produces contract facts or presents derived facts.',
+        kind: 'classified',
+        options: [
+          {
+            to: 'derive',
+            when: 'The occurrence describes producing contract-owned facts or inferred data from authored inputs.',
+          },
+          {
+            to: 'render',
+            when: 'The occurrence describes presenting derived facts through a surface, report, guide, or operator output.',
+          },
+        ],
+      },
+    }),
+  ]);
+
+export const listGovernedVocabularyTransitions =
+  (): readonly GovernedVocabularyTransition[] => governedVocabularyTransitions;
+
+export const getGovernedVocabularyTransition = (
+  id: string
+): GovernedVocabularyTransition | undefined =>
+  governedVocabularyTransitions.find((transition) => transition.id === id);
+
+export const requireGovernedVocabularyTransition = (
+  id: string
+): GovernedVocabularyTransition => {
+  const transition = getGovernedVocabularyTransition(id);
+  if (transition === undefined) {
+    throw new Error(`Unknown governed vocabulary transition "${id}".`);
+  }
+  return transition;
+};
+
+export const formatGovernedVocabularyTransitionGuide = (
+  transitions: readonly GovernedVocabularyTransition[] = governedVocabularyTransitions
+): string =>
+  transitions
+    .map((transition) => {
+      const target =
+        transition.target.kind === 'single'
+          ? transition.target.to
+          : transition.target.options
+              .map((option) => `${option.to} (${option.when})`)
+              .join(' or ');
+      const lines = [
+        `- ${transition.id}: ${transition.from} -> ${target}`,
+        `  - Status: ${transition.status}`,
+        `  - Intent: ${transition.intent}`,
+        `  - Safe rewrites: ${Object.keys(transition.safeRewriteForms).length}`,
+        `  - Review forms: ${transition.reviewForms.join(', ') || 'none'}`,
+      ];
+      return lines.join('\n');
+    })
+    .join('\n');