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

package/src/rules/implementation-returns-result.ts

@@ -8,6 +8,7 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, isAbsolute, resolve } from 'node:path';
+import { escapeRegExp } from '@ontrails/core';
 import type { AstNode } from './ast.js';
 import {
   collectScopeFrameBindings,
@@ -288,9 +289,6 @@ const extractIdentifierName = (node: AstNode | undefined): string | null =>
 
 const DEFAULT_RESULT_TYPE_NAMES = new Set(['Result']);
 
-const escapeRegExp = (value: string): string =>
-  value.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
 const hasGenericTypeReference = (
   annotationText: string,
   typeName: string

package/src/rules/index.ts

@@ -8,10 +8,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';
@@ -22,6 +24,7 @@ import { missingVisibility } from './missing-visibility.js';
 import { missingReconcile } from './missing-reconcile.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';
@@ -50,8 +53,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,
@@ -77,9 +82,11 @@ export type {
   WardenFixCapability,
   WardenFixClass,
   WardenFixEdit,
+  WardenFixScanTargets,
   WardenFixSafety,
   WardenGuidance,
   WardenGuidanceLink,
+  WardenExportedSymbolDefinition,
   WardenRuleLifecycle,
   WardenRuleLifecycleState,
   WardenRuleConcern,
@@ -94,6 +101,30 @@ export type {
   WardenSeverity,
 } from './types.js';
 
+export {
+  formatGovernedVocabularyTransitionGuide,
+  getGovernedVocabularyTransition,
+  governedVocabularyLiteralRenameSchema,
+  governedVocabularyPreserveRuleSchema,
+  governedVocabularyRegistrySchema,
+  governedVocabularyScopeSchema,
+  governedVocabularySymbolRenameSchema,
+  governedVocabularyTargetSchema,
+  governedVocabularyTransitionSchema,
+  governedVocabularyTransitionStatuses,
+  governedVocabularyTransitions,
+  listGovernedVocabularyTransitions,
+  requireGovernedVocabularyTransition,
+} from './retired-vocabulary.js';
+export type {
+  GovernedVocabularyLiteralRename,
+  GovernedVocabularyPreserveRule,
+  GovernedVocabularyScope,
+  GovernedVocabularySymbolRename,
+  GovernedVocabularyTarget,
+  GovernedVocabularyTransition,
+  GovernedVocabularyTransitionInput,
+} from './retired-vocabulary.js';
 export {
   builtinWardenRuleMetadata,
   getWardenRuleMetadata,
@@ -118,10 +149,12 @@ export { deadInternalTrail } from './dead-internal-trail.js';
 export { deadPublicTrail } from './dead-public-trail.js';
 export { draftFileMarking } from './draft-file-marking.js';
 export { draftVisibleDebt } from './draft-visible-debt.js';
+export { duplicateExportedSymbol } from './duplicate-exported-symbol.js';
 export { duplicatePublicContract } from './duplicate-public-contract.js';
 export { errorMappingCompleteness } from './error-mapping-completeness.js';
 export { exampleValid } from './example-valid.js';
 export { firesDeclarations } from './fires-declarations.js';
+export { governedSymbolResidue } from './governed-symbol-residue.js';
 export { incompleteAccessorForStandardOp } from './incomplete-accessor-for-standard-op.js';
 export { incompleteCrud } from './incomplete-crud.js';
 export { intentPropagation } from './intent-propagation.js';
@@ -132,6 +165,7 @@ export { missingReconcile } from './missing-reconcile.js';
 export { onReferencesExist } from './on-references-exist.js';
 export { noDevPermitInSource } from './no-dev-permit-in-source.js';
 export { noDestructuredCompose } from './no-destructured-compose.js';
+export { noLegacyCliAliasExport } from './no-legacy-cli-alias-export.js';
 export { noLegacyLayerImports } from './no-legacy-layer-imports.js';
 export { noDirectImplementationCall } from './no-direct-implementation-call.js';
 export { noNativeErrorResult } from './no-native-error-result.js';
@@ -158,8 +192,10 @@ export { resourceMockCoverage } from './resource-mock-coverage.js';
 export { scheduledDestroyIntent } from './scheduled-destroy-intent.js';
 export { signalGraphCoaching } from './signal-graph-coaching.js';
 export { staticResourceAccessorPreference } from './static-resource-accessor-preference.js';
-export { surfaceFacetCoherence } from './surface-facet-coherence.js';
+export { surfaceOverlayCoherence } from './surface-overlay-coherence.js';
+export { surfaceTrailheadCoherence } from './surface-trailhead-coherence.js';
 export { trailForkCoaching } from './trail-fork-coaching.js';
+export { trailheadOverrideDivergence } from './trailhead-override-divergence.js';
 export {
   forkWithoutPreservedBlaze,
   markerSchemaUnsupported,
@@ -191,9 +227,11 @@ export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   [deadPublicTrail.name, deadPublicTrail],
   [draftFileMarking.name, draftFileMarking],
   [draftVisibleDebt.name, draftVisibleDebt],
+  [duplicateExportedSymbol.name, duplicateExportedSymbol],
   [errorMappingCompleteness.name, errorMappingCompleteness],
   [exampleValid.name, exampleValid],
   [firesDeclarations.name, firesDeclarations],
+  [governedSymbolResidue.name, governedSymbolResidue],
   [incompleteCrud.name, incompleteCrud],
   [intentPropagation.name, intentPropagation],
   [layerFieldNameDrift.name, layerFieldNameDrift],
@@ -213,12 +251,14 @@ export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   [resourceMockCoverage.name, resourceMockCoverage],
   [preferSchemaInference.name, preferSchemaInference],
   [staticResourceAccessorPreference.name, staticResourceAccessorPreference],
-  [surfaceFacetCoherence.name, surfaceFacetCoherence],
+  [surfaceTrailheadCoherence.name, surfaceTrailheadCoherence],
   [trailForkCoaching.name, trailForkCoaching],
+  [trailheadOverrideDivergence.name, trailheadOverrideDivergence],
   [validDescribeRefs.name, validDescribeRefs],
   [noDevPermitInSource.name, noDevPermitInSource],
   [noDestructuredCompose.name, noDestructuredCompose],
   [noDirectImplementationCall.name, noDirectImplementationCall],
+  [noLegacyCliAliasExport.name, noLegacyCliAliasExport],
   [noLegacyLayerImports.name, noLegacyLayerImports],
   [noNativeErrorResult.name, noNativeErrorResult],
   [noRedundantResultErrorWrap.name, noRedundantResultErrorWrap],
@@ -260,6 +300,7 @@ export const wardenTopoRules: ReadonlyMap<string, TopoAwareWardenRule> =
     [publicUnionOutputDiscriminants.name, publicUnionOutputDiscriminants],
     [scheduledDestroyIntent.name, scheduledDestroyIntent],
     [signalGraphCoaching.name, signalGraphCoaching],
+    [surfaceOverlayCoherence.name, surfaceOverlayCoherence],
     [unmaterializedActivationSource.name, unmaterializedActivationSource],
     [validDetourContract.name, validDetourContract],
     [deprecationWithoutGuidance.name, deprecationWithoutGuidance],

package/src/rules/metadata.ts

@@ -44,6 +44,7 @@ export const wardenRuleLifecycleStates = [
 ] as const satisfies readonly WardenRuleLifecycleState[];
 
 export const wardenFixClasses = [
+  'export-restructure',
   'term-rewrite',
 ] as const satisfies readonly WardenFixClass[];
 
@@ -76,10 +77,12 @@ const concernByRuleName: Partial<Record<string, WardenRuleConcern>> = {
   'deprecation-without-guidance': 'lifecycle',
   'draft-file-marking': 'lifecycle',
   'draft-visible-debt': 'lifecycle',
+  'duplicate-exported-symbol': 'general',
   'duplicate-public-contract': 'meta',
   'error-mapping-completeness': 'results',
   'fires-declarations': 'signals',
   'fork-without-preserved-blaze': 'lifecycle',
+  'governed-symbol-residue': 'lifecycle',
   'implementation-returns-result': 'results',
   'intent-propagation': 'composition',
   'library-projection-coherence': 'meta',
@@ -89,6 +92,7 @@ const concernByRuleName: Partial<Record<string, WardenRuleConcern>> = {
   'no-destructured-compose': 'composition',
   'no-dev-permit-in-source': 'permits',
   'no-direct-implementation-call': 'composition',
+  'no-legacy-cli-alias-export': 'general',
   'no-native-error-result': 'results',
   'no-redundant-result-error-wrap': 'results',
   'no-retired-cross-vocabulary': 'composition',
@@ -109,8 +113,10 @@ const concernByRuleName: Partial<Record<string, WardenRuleConcern>> = {
   'scheduled-destroy-intent': 'lifecycle',
   'signal-graph-coaching': 'signals',
   'static-resource-accessor-preference': 'resources',
-  'surface-facet-coherence': 'meta',
+  'surface-overlay-coherence': 'meta',
+  'surface-trailhead-coherence': 'meta',
   'trail-fork-coaching': 'meta',
+  'trailhead-override-divergence': 'meta',
   'unmaterialized-activation-source': 'lifecycle',
   'valid-detour-contract': 'results',
   'version-gap': 'lifecycle',
@@ -220,6 +226,26 @@ const builtinWardenRuleMetadataInput = {
     invariant: 'Draft-authored IDs remain visible debt.',
     tier: 'source-static',
   },
+  'duplicate-exported-symbol': {
+    ...durableRepoLocal,
+    guidance: {
+      docs: [
+        {
+          label: 'Package ownership',
+          path: 'docs/contributing/package-ownership.md',
+        },
+      ],
+      relatedRules: [
+        'resolved-import-boundary',
+        'public-internal-deep-imports',
+      ],
+      summary:
+        'Keep exported symbol ownership from drifting across first-party packages.',
+    },
+    invariant:
+      'First-party packages should not define the same exported symbol name in parallel.',
+    tier: 'project-static',
+  },
   'duplicate-public-contract': {
     ...durableExternal,
     guidance: {
@@ -265,6 +291,13 @@ const builtinWardenRuleMetadataInput = {
     invariant: 'Fork version entries preserve their historical blaze.',
     tier: 'source-static',
   },
+  'governed-symbol-residue': {
+    ...durableExternal,
+    fix: { class: 'term-rewrite', safety: 'safe' },
+    invariant:
+      'Active governed vocabulary symbol renames do not leave retired identifiers in source.',
+    tier: 'source-static',
+  },
   'implementation-returns-result': {
     ...durableExternal,
     invariant: 'Blazes return Result values.',
@@ -300,7 +333,10 @@ const builtinWardenRuleMetadataInput = {
           path: 'docs/adr/drafts/20260612-library-surface-and-compiler.md',
         },
       ],
-      relatedRules: ['cli-command-route-coherence', 'surface-facet-coherence'],
+      relatedRules: [
+        'cli-command-route-coherence',
+        'surface-trailhead-coherence',
+      ],
       steps: [
         'Rename one source trail or add an explicit library export override before generating a package.',
         'Keep serialized library projection exports attached to existing trail IDs.',
@@ -346,6 +382,18 @@ const builtinWardenRuleMetadataInput = {
     invariant: 'Application code composes trails through ctx.compose().',
     tier: 'source-static',
   },
+  'no-legacy-cli-alias-export': {
+    fix: { class: 'export-restructure', safety: 'review' },
+    invariant:
+      'Legacy app-module CLI alias exports (cliAliases, trailsCliAliases) removed in the TRL-1207 surfaces-overlay cutover do not reappear in committed source.',
+    lifecycle: {
+      retireWhen:
+        'TRL-1207 surfaces-overlay migration window closes and supported apps have moved CLI bindings into surfaceOverlay entries in their trailsOverlays exports.',
+      state: 'temporary',
+    },
+    scope: 'external',
+    tier: 'source-static',
+  },
   'no-legacy-layer-imports': {
     fix: { class: 'term-rewrite', safety: 'review' },
     invariant:
@@ -605,25 +653,44 @@ const builtinWardenRuleMetadataInput = {
     scope: 'advisory',
     tier: 'source-static',
   },
-  'surface-facet-coherence': {
+  'surface-overlay-coherence': {
+    ...durableExternal,
+    guidance: {
+      relatedRules: [
+        'cli-command-route-coherence',
+        'surface-trailhead-coherence',
+      ],
+      steps: [
+        'Point every binding selector at an existing trail id or dotted trail-id glob.',
+        'Narrow overlapping grouped bindings so each trail has one grouped owner per surface.',
+        'Rename bindings that shadow canonical CLI command paths or derived MCP tool names.',
+      ],
+      summary:
+        'Keep surface overlay bindings pointed at real trails without shadowing canonical surface entries.',
+    },
+    invariant:
+      'Surface overlay bindings resolve to real trails without group overlap or canonical-entry shadowing.',
+    tier: 'topo-aware',
+  },
+  'surface-trailhead-coherence': {
     ...durableExternal,
     guidance: {
       docs: [
         {
-          label: 'Surface Facets ADR',
-          path: 'docs/adr/drafts/20260603-surface-facets-shape-dense-topos.md',
+          label: 'Trailheads ADR',
+          path: 'docs/adr/drafts/20260603-surface-trailheads-shape-dense-topos.md',
         },
       ],
       steps: [
-        'Keep facet selectors as explicit string literals or literal arrays when possible.',
-        'Ensure each public trail belongs to one facet owner.',
-        'Record explicit visibility-widening acceptance and stable-description metadata when a facet intentionally widens visibility.',
+        'Keep trailhead selectors as explicit string literals or literal arrays when possible.',
+        'Ensure each public trail belongs to one trailhead owner.',
+        'Record explicit visibility-widening acceptance and stable-description metadata when a trailhead intentionally widens visibility.',
       ],
       summary:
-        'Keep surface facet maps reviewable before they reach MCP projection.',
+        'Keep trailhead maps reviewable before they reach MCP projection.',
     },
     invariant:
-      'Surface facet maps avoid selector overlap, hidden visibility widening, and drift-prone dynamic selectors.',
+      'Trailhead maps avoid selector overlap, hidden visibility widening, and drift-prone dynamic selectors.',
     tier: 'source-static',
   },
   'trail-fork-coaching': {
@@ -639,12 +706,15 @@ const builtinWardenRuleMetadataInput = {
           path: 'docs/surfaces/surface-accommodations.md',
         },
       ],
-      relatedRules: ['surface-facet-coherence', 'cli-command-route-coherence'],
+      relatedRules: [
+        'surface-trailhead-coherence',
+        'cli-command-route-coherence',
+      ],
       steps: [
         'Check the semantic fork boundary: intent, permits, outputs, errors, lifecycle, and side effects.',
         'Check the structural fork boundary: selected trail identity stays visible instead of hiding behind action vocabulary.',
         'Split real capability forks into distinct trails or a composing trail.',
-        'Use a facet only when one surface entry needs to group multiple trails while preserving selected member identity.',
+        'Use a trailhead only when one surface entry needs to group multiple trails while preserving selected member identity.',
       ],
       summary:
         'Keep surface accommodations from hiding several capabilities behind one branching trail input.',
@@ -654,6 +724,30 @@ const builtinWardenRuleMetadataInput = {
     scope: 'advisory',
     tier: 'source-static',
   },
+  'trailhead-override-divergence': {
+    ...durableExternal,
+    guidance: {
+      docs: [
+        {
+          label: 'Surface Accommodations',
+          path: 'docs/surfaces/surface-accommodations.md',
+        },
+      ],
+      relatedRules: [
+        'surface-overlay-coherence',
+        'surface-trailhead-coherence',
+      ],
+      steps: [
+        'Author the grouped entry as an mcp list binding in surfaceOverlay({ mcp }) so the lock carries the default.',
+        'Keep the call-site trailhead map aligned with the authored binding names and member selectors, or rename one side to make the intentional divergence explicit.',
+      ],
+      summary:
+        'Keep call-site MCP trailhead overrides aligned with the authored overlay default.',
+    },
+    invariant:
+      'Call-site MCP trailhead maps stay aligned with authored surfaces overlay mcp bindings.',
+    tier: 'project-static',
+  },
   'unmaterialized-activation-source': {
     ...durableExternal,
     invariant:
@@ -715,7 +809,7 @@ const builtinWardenRuleMetadataInput = {
 
 export type BuiltinWardenRuleName = keyof typeof builtinWardenRuleMetadataInput;
 
-const withFacetDefaults = (
+const withRuleDefaults = (
   name: string,
   metadata: BuiltinWardenRuleMetadataInput
 ): WardenRuleMetadata => ({
@@ -727,7 +821,7 @@ const withFacetDefaults = (
 export const builtinWardenRuleMetadata = Object.fromEntries(
   Object.entries(builtinWardenRuleMetadataInput).map(([name, metadata]) => [
     name,
-    withFacetDefaults(name, metadata),
+    withRuleDefaults(name, metadata),
   ])
 ) as Readonly<Record<BuiltinWardenRuleName, WardenRuleMetadata>>;
 

package/src/rules/no-legacy-cli-alias-export.ts

@@ -0,0 +1,247 @@
+/**
+ * Flags leftover legacy app-module CLI alias exports removed in TRL-1207.
+ *
+ * Before the surfaces-overlay cutover, apps published CLI alias maps through
+ * a module-level export named `cliAliases` or `trailsCliAliases`. TRL-1207 is
+ * a hard cutover: app-owned CLI bindings now live in a
+ * `surfaceOverlay({ cli: { ... } })` envelope inside the app module's
+ * `trailsOverlays` array export, and the legacy export convention was
+ * deleted. This rule makes a leftover legacy export an error so stale app
+ * modules get a fix-forward diagnostic instead of silently losing their
+ * bindings.
+ *
+ * Detection is AST-scoped and export-shaped:
+ *
+ *   - `export const cliAliases = { ... }` (also `let`/`var`, destructured
+ *     bindings, and function/class declarations) is flagged.
+ *   - `export { cliAliases }` and `export { whatever as trailsCliAliases }`
+ *     specifiers are flagged, including re-export statements such as
+ *     `export { trailsCliAliases } from './app.js'`.
+ *   - A non-exported local `const cliAliases = ...` is legal and never
+ *     flagged, and the identifiers appearing only in strings or comments do
+ *     not match because the rule inspects export bindings, not raw text.
+ */
+
+import {
+  getNodeArgument,
+  getNodeBodyStatements,
+  getNodeDeclaration,
+  getNodeDeclarations,
+  getNodeElements,
+  getNodeExported,
+  getNodeExportKind,
+  getNodeId,
+  getNodeLeft,
+  getNodeProperties,
+  getNodeSpecifiers,
+  getNodeValueNode,
+  getStringValue,
+  identifierName,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import type { WardenDiagnostic, WardenFix, WardenRule } from './types.js';
+
+const RULE_NAME = 'no-legacy-cli-alias-export';
+
+/** Legacy app-module CLI alias export names removed in TRL-1207. */
+const LEGACY_CLI_ALIAS_EXPORT_NAMES: ReadonlySet<string> = new Set([
+  'cliAliases',
+  'trailsCliAliases',
+]);
+
+/** Declaration node types that only propagate types, never value bindings. */
+const TYPE_ONLY_DECLARATION_TYPES: ReadonlySet<string> = new Set([
+  'TSInterfaceDeclaration',
+  'TSTypeAliasDeclaration',
+]);
+
+interface ExportedBinding {
+  readonly name: string;
+  readonly start: number;
+}
+
+/** Exported name of a specifier: identifier or string-literal alias. */
+const exportedSpecifierName = (node: AstNode | undefined): string | null =>
+  identifierName(node) ??
+  (node && isStringLiteral(node) ? getStringValue(node) : null);
+
+/**
+ * Expand one binding-pattern node into legacy-named bindings, pushing child
+ * patterns onto the worklist. Destructured exports such as
+ * `export const { cliAliases } = mod` still introduce a module-level exported
+ * value binding, so patterns cannot be skipped.
+ */
+const visitBindingPatternNode = (
+  node: AstNode,
+  into: ExportedBinding[],
+  worklist: AstNode[]
+): void => {
+  const name = identifierName(node);
+  if (name !== null) {
+    if (LEGACY_CLI_ALIAS_EXPORT_NAMES.has(name)) {
+      into.push({ name, start: node.start });
+    }
+    return;
+  }
+  if (node.type === 'AssignmentPattern') {
+    const left = getNodeLeft(node);
+    if (left) {
+      worklist.push(left);
+    }
+    return;
+  }
+  if (node.type === 'RestElement') {
+    const argument = getNodeArgument(node);
+    if (argument) {
+      worklist.push(argument);
+    }
+    return;
+  }
+  if (node.type === 'ObjectPattern') {
+    for (const property of getNodeProperties(node)) {
+      const value = getNodeValueNode(property) ?? getNodeArgument(property);
+      if (value) {
+        worklist.push(value);
+      }
+    }
+    return;
+  }
+  if (node.type === 'ArrayPattern') {
+    for (const element of getNodeElements(node)) {
+      if (element) {
+        worklist.push(element);
+      }
+    }
+  }
+};
+
+const collectLegacyPatternBindings = (
+  pattern: AstNode | undefined,
+  into: ExportedBinding[]
+): void => {
+  if (!pattern) {
+    return;
+  }
+  const worklist: AstNode[] = [pattern];
+  while (worklist.length > 0) {
+    const node = worklist.pop();
+    if (node) {
+      visitBindingPatternNode(node, into, worklist);
+    }
+  }
+};
+
+const collectLegacyDeclarationBindings = (
+  declaration: AstNode
+): readonly ExportedBinding[] => {
+  if (TYPE_ONLY_DECLARATION_TYPES.has(declaration.type)) {
+    return [];
+  }
+  const bindings: ExportedBinding[] = [];
+  if (declaration.type === 'VariableDeclaration') {
+    for (const declarator of getNodeDeclarations(declaration)) {
+      collectLegacyPatternBindings(getNodeId(declarator), bindings);
+    }
+    return bindings;
+  }
+  const name = identifierName(getNodeId(declaration));
+  if (name !== null && LEGACY_CLI_ALIAS_EXPORT_NAMES.has(name)) {
+    bindings.push({ name, start: declaration.start });
+  }
+  return bindings;
+};
+
+const collectLegacySpecifierBindings = (
+  statement: AstNode
+): readonly ExportedBinding[] => {
+  const bindings: ExportedBinding[] = [];
+  for (const specifier of getNodeSpecifiers(statement)) {
+    if (
+      specifier.type !== 'ExportSpecifier' ||
+      getNodeExportKind(specifier) === 'type'
+    ) {
+      continue;
+    }
+    const name = exportedSpecifierName(getNodeExported(specifier));
+    if (name !== null && LEGACY_CLI_ALIAS_EXPORT_NAMES.has(name)) {
+      bindings.push({ name, start: specifier.start });
+    }
+  }
+  return bindings;
+};
+
+const collectLegacyExportBindings = (
+  ast: AstNode
+): readonly ExportedBinding[] => {
+  const bindings: ExportedBinding[] = [];
+  for (const statement of getNodeBodyStatements(ast)) {
+    if (
+      statement.type !== 'ExportNamedDeclaration' ||
+      getNodeExportKind(statement) === 'type'
+    ) {
+      continue;
+    }
+    const declaration = getNodeDeclaration(statement);
+    if (declaration) {
+      bindings.push(...collectLegacyDeclarationBindings(declaration));
+      continue;
+    }
+    bindings.push(...collectLegacySpecifierBindings(statement));
+  }
+  return bindings;
+};
+
+const buildMessage = (name: string): string =>
+  `Legacy CLI alias export '${name}' was removed in the TRL-1207 surfaces-overlay cutover. Wrap the alias map into surfaceOverlay({ cli: { ... } }) from @ontrails/core inside the module's trailsOverlays array export.`;
+
+/**
+ * Build the fix metadata for a legacy CLI alias export finding.
+ *
+ * The rewrite is an export restructure, not a rename, so there is no
+ * mechanical single-span replacement: the fix carries no edits and Warden
+ * never applies it. Downstream, the `export-restructure` fix class routes the
+ * finding to the Regrade `export-restructure:cli-aliases` class (TRL-1210),
+ * which inverts the alias map into `surfaceOverlay({ cli: { ... } })`
+ * bindings inside the module's `trailsOverlays` array export.
+ */
+const buildFix = (name: string): WardenFix => ({
+  class: 'export-restructure',
+  reason: `Legacy CLI alias export '${name}' must be rewritten into a surfaceOverlay({ cli: { ... } }) entry inside the module's trailsOverlays array export; run the Regrade class export-restructure:cli-aliases (TRL-1210) to automate this restructure.`,
+  safety: 'review',
+});
+
+/**
+ * Flags exported bindings named `cliAliases` or `trailsCliAliases`, the
+ * legacy app-module CLI alias export convention deleted in TRL-1207.
+ */
+export const noLegacyCliAliasExport: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (
+      !(
+        sourceCode.includes('cliAliases') ||
+        sourceCode.includes('trailsCliAliases')
+      )
+    ) {
+      return [];
+    }
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+    return collectLegacyExportBindings(ast).map((binding) => ({
+      filePath,
+      fix: buildFix(binding.name),
+      line: offsetToLine(sourceCode, binding.start),
+      message: buildMessage(binding.name),
+      rule: RULE_NAME,
+      severity: 'error',
+    }));
+  },
+  description:
+    'Disallow the legacy app-module CLI alias exports (cliAliases, trailsCliAliases) removed in the TRL-1207 surfaces-overlay cutover.',
+  name: RULE_NAME,
+  severity: 'error',
+};