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

package/src/rules/governed-symbol-residue.ts

@@ -12,7 +12,13 @@ import type {
   GovernedVocabularySymbolRename,
   GovernedVocabularyTransition,
 } from './retired-vocabulary.js';
-import type { WardenDiagnostic, WardenFix, WardenRule } from './types.js';
+import type {
+  GovernedVocabularyHistoryEvidence,
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+  WardenFix,
+} from './types.js';
 
 const RULE_NAME = 'governed-symbol-residue';
 
@@ -37,11 +43,15 @@ const isAllowedSourcePath = (filePath: string): boolean =>
   );
 
 interface ActiveSymbolRename {
+  readonly history?: GovernedVocabularyHistoryEvidence;
   readonly rename: GovernedVocabularySymbolRename;
   readonly targetSegments: readonly string[];
+  readonly transition: GovernedVocabularyTransition;
 }
 
-const activeSymbolRenames = (): readonly ActiveSymbolRename[] =>
+const activeSymbolRenames = (
+  context?: ProjectContext
+): readonly ActiveSymbolRename[] =>
   listGovernedVocabularyTransitions()
     .filter(
       (transition) =>
@@ -52,9 +62,14 @@ const activeSymbolRenames = (): readonly ActiveSymbolRename[] =>
       const targetSegments = [
         ...new Set(transition.symbolRenames.map((rename) => rename.to)),
       ];
+      const history = context?.governedVocabularyHistoryByTransitionId?.get(
+        transition.id
+      );
       return transition.symbolRenames.map((rename) => ({
+        ...(history === undefined ? {} : { history }),
         rename,
         targetSegments,
+        transition,
       }));
     });
 
@@ -353,12 +368,28 @@ const safeFixFor = (match: SymbolRenameMatch): WardenFix | undefined => {
   };
 };
 
+const diagnosticMessageFor = (
+  match: SymbolRenameMatch,
+  transition?: GovernedVocabularyTransition,
+  history?: GovernedVocabularyHistoryEvidence
+): string => {
+  if (history !== undefined) {
+    return `Retired governed symbol '${match.from}' was reintroduced after governed transition '${history.transitionId}' in '${history.path}' (${history.id}); migrate to '${match.to}'.`;
+  }
+  if (transition?.provenance.mode === 'regrade-history') {
+    return `Retired governed symbol '${match.from}' belongs to governed transition '${transition.id}', but no committed Regrade history proves the migration ran.`;
+  }
+  return `Retired governed symbol '${match.from}' should migrate to '${match.to}'.`;
+};
+
 const diagnosticFor = (
   sourceCode: string,
   filePath: string,
   node: AstNode,
   match: SymbolRenameMatch,
-  reviewReason: string | null
+  reviewReason: string | null,
+  transition?: GovernedVocabularyTransition,
+  history?: GovernedVocabularyHistoryEvidence
 ): WardenDiagnostic => {
   const fix =
     reviewReason === null
@@ -368,71 +399,133 @@ const diagnosticFor = (
     filePath,
     ...(fix === undefined ? {} : { fix }),
     line: offsetToLine(sourceCode, node.start),
-    message: `Retired governed symbol '${match.from}' should migrate to '${match.to}'.`,
+    message: diagnosticMessageFor(match, transition, history),
     rule: RULE_NAME,
     severity: 'error',
   };
 };
 
-export const governedSymbolResidue: WardenRule = {
-  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
-    if (isAllowedSourcePath(filePath)) {
-      return [];
-    }
+const provenanceDiagnostics = (
+  context: ProjectContext
+): readonly WardenDiagnostic[] => {
+  const historyIssues = context.governedVocabularyHistoryIssues ?? [];
+  const invalidTransitionIds = new Set(
+    historyIssues.flatMap((issue) =>
+      issue.transitionId === undefined ? [] : [issue.transitionId]
+    )
+  );
+  const issues = historyIssues.map((issue) => ({
+    filePath: issue.path,
+    line: 1,
+    message: issue.message,
+    rule: RULE_NAME,
+    severity: 'error' as const,
+  }));
+  const missing = listGovernedVocabularyTransitions()
+    .filter(
+      (transition) =>
+        context.governedVocabularyHistoryRequired === true &&
+        transition.status === 'complete' &&
+        transition.provenance.mode === 'regrade-history' &&
+        !invalidTransitionIds.has(transition.id) &&
+        !context.governedVocabularyHistoryByTransitionId?.has(transition.id)
+    )
+    .map((transition) => ({
+      filePath: '<governed-vocabulary-history>',
+      line: 1,
+      message: `Governed transition '${transition.id}' is complete but has no valid committed Regrade history provenance. Run Regrade as the primary migration path before manual review or cleanup.`,
+      rule: RULE_NAME,
+      severity: 'error' as const,
+    }));
+  return [...issues, ...missing];
+};
 
-    const renames = activeSymbolRenames();
-    if (renames.length === 0) {
-      return [];
-    }
+const checkSource = (
+  sourceCode: string,
+  filePath: string,
+  projectContext?: ProjectContext
+): readonly WardenDiagnostic[] => {
+  if (isAllowedSourcePath(filePath)) {
+    return [];
+  }
 
-    const parsed = parseWithDiagnostics(filePath, sourceCode);
-    if (!parsed.ast || parsed.diagnostics.length > 0) {
-      return [];
-    }
+  const renames = activeSymbolRenames(projectContext);
+  if (renames.length === 0) {
+    return [];
+  }
 
-    const shorthandIdentifiers = new Set<string>();
-    walkWithScopeContext(parsed.ast, (node, context) => {
-      if (!isShorthandPropertyKeyVisit(node, context)) {
-        return;
-      }
-      const name = identifierName(node);
-      if (name !== null) {
-        shorthandIdentifiers.add(name);
-      }
-    });
+  const parsed = parseWithDiagnostics(filePath, sourceCode);
+  if (!parsed.ast || parsed.diagnostics.length > 0) {
+    return [];
+  }
 
-    const diagnostics: WardenDiagnostic[] = [];
-    walkWithScopeContext(parsed.ast, (node, context) => {
-      if (isDuplicateShorthandValueVisit(node, context)) {
-        return;
-      }
+  const shorthandIdentifiers = new Set<string>();
+  walkWithScopeContext(parsed.ast, (node, astContext) => {
+    if (!isShorthandPropertyKeyVisit(node, astContext)) {
+      return;
+    }
+    const name = identifierName(node);
+    if (name !== null) {
+      shorthandIdentifiers.add(name);
+    }
+  });
 
-      const activeMatch = renames
-        .map(({ rename, targetSegments }) => ({
-          match: resolveSymbolRenameMatch(node, sourceCode, rename),
-          targetSegments,
-        }))
-        .find((candidate) => candidate.match !== null);
-      if (activeMatch === undefined || activeMatch.match === null) {
-        return;
-      }
-      const { match, targetSegments } = activeMatch;
+  const diagnostics: WardenDiagnostic[] = [];
+  walkWithScopeContext(parsed.ast, (node, astContext) => {
+    if (isDuplicateShorthandValueVisit(node, astContext)) {
+      return;
+    }
 
-      diagnostics.push(
-        diagnosticFor(
-          sourceCode,
-          filePath,
-          node,
+    const activeMatch = renames
+      .map(({ history, rename, targetSegments, transition }) => ({
+        history,
+        match: resolveSymbolRenameMatch(node, sourceCode, rename),
+        targetSegments,
+        transition,
+      }))
+      .find((candidate) => candidate.match !== null);
+    if (activeMatch === undefined || activeMatch.match === null) {
+      return;
+    }
+    const { history, match, targetSegments, transition } = activeMatch;
+
+    diagnostics.push(
+      diagnosticFor(
+        sourceCode,
+        filePath,
+        node,
+        match,
+        reviewReasonFor(
+          astContext,
           match,
-          reviewReasonFor(context, match, shorthandIdentifiers, targetSegments)
-        )
-      );
-    });
+          shorthandIdentifiers,
+          targetSegments
+        ),
+        transition,
+        history
+      )
+    );
+  });
 
-    return diagnostics;
+  return diagnostics;
+};
+
+export const governedSymbolResidue: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    return checkSource(sourceCode, filePath);
+  },
+  checkProject(context: ProjectContext): readonly WardenDiagnostic[] {
+    return provenanceDiagnostics(context);
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    return checkSource(sourceCode, filePath, context);
   },
   description:
-    'Detect active governed vocabulary symbols that remain in source code.',
+    'Require committed Regrade provenance for governed transitions and detect retired symbols that remain or return.',
   name: RULE_NAME,
   severity: 'error',
 };

package/src/rules/governed-vocabulary-permutation-watch.ts

@@ -0,0 +1,76 @@
+import type {
+  GovernedVocabularyHistoryEvidence,
+  GovernedVocabularyHistoryFormObservation,
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const RULE_NAME = 'governed-vocabulary-permutation-watch';
+
+const formIdentity = (
+  form: string,
+  evidence: GovernedVocabularyHistoryEvidence
+): string => (evidence.caseSensitive ? form : form.toLowerCase());
+
+const isUnknownPermutation = (
+  observation: GovernedVocabularyHistoryFormObservation
+): boolean =>
+  observation.reason === 'unclassified-neighbor' &&
+  observation.verdict === 'deferred' &&
+  (observation.scopeTier === undefined || observation.scopeTier === 'in-scope');
+
+const compareObservation = (
+  left: GovernedVocabularyHistoryFormObservation,
+  right: GovernedVocabularyHistoryFormObservation
+): number =>
+  left.path.localeCompare(right.path) ||
+  left.line - right.line ||
+  left.form.localeCompare(right.form);
+
+const diagnosticsForHistory = (
+  evidence: GovernedVocabularyHistoryEvidence
+): readonly WardenDiagnostic[] => {
+  const unknownByIdentity = new Map<
+    string,
+    GovernedVocabularyHistoryFormObservation
+  >();
+
+  for (const observation of evidence.latestFormObservations) {
+    if (!isUnknownPermutation(observation)) {
+      continue;
+    }
+    const identity = formIdentity(observation.form, evidence);
+    const current = unknownByIdentity.get(identity);
+    if (current === undefined || compareObservation(observation, current) < 0) {
+      unknownByIdentity.set(identity, observation);
+    }
+  }
+
+  return [...unknownByIdentity.entries()]
+    .toSorted(([left], [right]) => left.localeCompare(right))
+    .map(([, observation]) => ({
+      filePath: observation.path,
+      line: observation.line,
+      message: `Governed transition '${evidence.transitionId}' recorded unknown vocabulary form '${observation.form}' in committed Regrade history '${evidence.path}' (${evidence.id}). Add the form and run an incremental plan, or classify it as out-of-family or preserved.`,
+      rule: RULE_NAME,
+      severity: 'warn' as const,
+    }));
+};
+
+const checkProject = (context: ProjectContext): readonly WardenDiagnostic[] =>
+  [...(context.governedVocabularyHistoryByTransitionId?.values() ?? [])]
+    .toSorted((left, right) =>
+      left.transitionId.localeCompare(right.transitionId)
+    )
+    .flatMap(diagnosticsForHistory);
+
+export const governedVocabularyPermutationWatch: ProjectAwareWardenRule = {
+  check: () => [],
+  checkProject,
+  checkWithContext: () => [],
+  description:
+    'Advise when committed Regrade history records unclassified permutations of governed vocabulary.',
+  name: RULE_NAME,
+  severity: 'warn',
+};

package/src/rules/index.ts

@@ -15,12 +15,13 @@ 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 { governedVocabularyPermutationWatch } from './governed-vocabulary-permutation-watch.js';
 import { implementationReturnsResult } from './implementation-returns-result.js';
 import { incompleteAccessorForStandardOp } from './incomplete-accessor-for-standard-op.js';
 import { incompleteCrud } from './incomplete-crud.js';
 import { intentPropagation } from './intent-propagation.js';
 import { layerFieldNameDrift } from './layer-field-name-drift.js';
-import { libraryProjectionCoherence } from './library-projection-coherence.js';
+import { libraryRenderCoherence } from './library-render-coherence.js';
 import { missingVisibility } from './missing-visibility.js';
 import { missingReconcile } from './missing-reconcile.js';
 import { noDevPermitInSource } from './no-dev-permit-in-source.js';
@@ -37,7 +38,7 @@ import { noThrowInImplementation } from './no-throw-in-implementation.js';
 import { noTopLevelSurface } from './no-top-level-surface.js';
 import { onReferencesExist } from './on-references-exist.js';
 import { orphanedSignal } from './orphaned-signal.js';
-import { ownerProjectionParity } from './owner-projection-parity.js';
+import { ownerRenderParity } from './owner-render-parity.js';
 import { permitGovernance } from './permit-governance.js';
 import { preferSchemaInference } from './prefer-schema-inference.js';
 import { publicExportExampleCoverage } from './public-export-example-coverage.js';
@@ -79,6 +80,9 @@ import { wardenRulesUseAst } from './warden-rules-use-ast.js';
 import { webhookRouteCollision } from './webhook-route-collision.js';
 
 export type {
+  GovernedVocabularyHistoryEvidence,
+  GovernedVocabularyHistoryFormObservation,
+  GovernedVocabularyHistoryIssue,
   WardenFix,
   WardenFixCapability,
   WardenFixClass,
@@ -106,7 +110,10 @@ export {
   formatGovernedVocabularyTransitionGuide,
   getGovernedVocabularyTransition,
   governedVocabularyLiteralRenameSchema,
+  governedVocabularyFileRenameSchema,
+  governedVocabularyHistoryProvenanceSchema,
   governedVocabularyPreserveRuleSchema,
+  governedVocabularyProvenancePolicySchema,
   governedVocabularyRegistrySchema,
   governedVocabularyScopeSchema,
   governedVocabularySymbolRenameSchema,
@@ -119,7 +126,9 @@ export {
 } from './retired-vocabulary.js';
 export type {
   GovernedVocabularyLiteralRename,
+  GovernedVocabularyHistoryProvenance,
   GovernedVocabularyPreserveRule,
+  GovernedVocabularyProvenancePolicy,
   GovernedVocabularyScope,
   GovernedVocabularySymbolRename,
   GovernedVocabularyTarget,
@@ -157,10 +166,11 @@ 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 { governedVocabularyPermutationWatch } from './governed-vocabulary-permutation-watch.js';
 export { incompleteAccessorForStandardOp } from './incomplete-accessor-for-standard-op.js';
 export { incompleteCrud } from './incomplete-crud.js';
 export { intentPropagation } from './intent-propagation.js';
-export { libraryProjectionCoherence } from './library-projection-coherence.js';
+export { libraryRenderCoherence } from './library-render-coherence.js';
 export { layerFieldNameDrift } from './layer-field-name-drift.js';
 export { missingVisibility } from './missing-visibility.js';
 export { missingReconcile } from './missing-reconcile.js';
@@ -178,7 +188,7 @@ export { implementationReturnsResult } from './implementation-returns-result.js'
 export { noThrowInDetourRecover } from './no-throw-in-detour-recover.js';
 export { noTopLevelSurface } from './no-top-level-surface.js';
 export { orphanedSignal } from './orphaned-signal.js';
-export { ownerProjectionParity } from './owner-projection-parity.js';
+export { ownerRenderParity } from './owner-render-parity.js';
 export { permitGovernance } from './permit-governance.js';
 export { preferSchemaInference } from './prefer-schema-inference.js';
 export { publicInternalDeepImports } from './public-internal-deep-imports.js';
@@ -235,6 +245,7 @@ export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   [exampleValid.name, exampleValid],
   [firesDeclarations.name, firesDeclarations],
   [governedSymbolResidue.name, governedSymbolResidue],
+  [governedVocabularyPermutationWatch.name, governedVocabularyPermutationWatch],
   [incompleteCrud.name, incompleteCrud],
   [intentPropagation.name, intentPropagation],
   [layerFieldNameDrift.name, layerFieldNameDrift],
@@ -242,7 +253,7 @@ export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   [missingReconcile.name, missingReconcile],
   [onReferencesExist.name, onReferencesExist],
   [orphanedSignal.name, orphanedSignal],
-  [ownerProjectionParity.name, ownerProjectionParity],
+  [ownerRenderParity.name, ownerRenderParity],
   [publicExportExampleCoverage.name, publicExportExampleCoverage],
   [publicInternalDeepImports.name, publicInternalDeepImports],
   [resourceDeclarations.name, resourceDeclarations],
@@ -297,7 +308,7 @@ export const wardenTopoRules: ReadonlyMap<string, TopoAwareWardenRule> =
     [cliCommandRouteCoherence.name, cliCommandRouteCoherence],
     [duplicatePublicContract.name, duplicatePublicContract],
     [incompleteAccessorForStandardOp.name, incompleteAccessorForStandardOp],
-    [libraryProjectionCoherence.name, libraryProjectionCoherence],
+    [libraryRenderCoherence.name, libraryRenderCoherence],
     [permitGovernance.name, permitGovernance],
     [publicOutputSchema.name, publicOutputSchema],
     [publicUnionOutputDiscriminants.name, publicUnionOutputDiscriminants],

package/src/rules/layer-field-name-drift.ts

@@ -60,7 +60,7 @@ const buildDiagnostic = (
 ): WardenDiagnostic => ({
   filePath,
   line: offsetToLine(sourceCode, node.start),
-  message: `layer-field-name-drift: surface-local reserved name set "${name}" can make layer input fields project differently across surfaces. Import LAYER_FIELD_RESERVED_NAMES from @ontrails/core instead.`,
+  message: `layer-field-name-drift: surface-local reserved name set "${name}" can make layer input fields render differently across surfaces. Import LAYER_FIELD_RESERVED_NAMES from @ontrails/core instead.`,
   rule: RULE_NAME,
   severity: 'error',
 });
@@ -96,7 +96,7 @@ export const layerFieldNameDrift: WardenRule = {
     return diagnostics;
   },
   description:
-    'Prevent surface-local reserved-name sets from drifting layer input field projection across surfaces.',
+    'Prevent surface-local reserved-name sets from drifting layer input field rendering across surfaces.',
   name: RULE_NAME,
   severity: 'error',
 };

package/src/rules/{library-projection-coherence.ts → library-render-coherence.ts}

@@ -1,12 +1,9 @@
 import { deriveTopoGraph } from '@ontrails/topography';
-import type {
-  TopoGraph,
-  TopoGraphLibraryProjection,
-} from '@ontrails/topography';
+import type { TopoGraph, TopoGraphLibraryDerived } from '@ontrails/topography';
 
 import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
 
-const RULE_NAME = 'library-projection-coherence';
+const RULE_NAME = 'library-render-coherence';
 const TOPO_FILE = '<topo>';
 
 const resolveGraph = (
@@ -26,7 +23,7 @@ const collisionDiagnostic = (
 ): WardenDiagnostic => ({
   filePath: TOPO_FILE,
   line: 1,
-  message: `Library projection export collision on "${exportName}": trails ${renderTrailIds(trailIds)} derive the same package export. Rename one trail or add a library export override before materializing the generated package.`,
+  message: `Library rendering export collision on "${exportName}": trails ${renderTrailIds(trailIds)} derive the same package export. Rename one trail or add a library export override before materializing the generated package.`,
   rule: RULE_NAME,
   severity: 'error',
 });
@@ -37,7 +34,7 @@ const missingTargetDiagnostic = (
 ): WardenDiagnostic => ({
   filePath: TOPO_FILE,
   line: 1,
-  message: `Library projection export "${exportName}" targets unknown trail "${trailId}". Resolved library exports must stay attached to existing trail contracts.`,
+  message: `Library rendering export "${exportName}" targets unknown trail "${trailId}". Resolved library exports must stay attached to existing trail contracts.`,
   rule: RULE_NAME,
   severity: 'error',
 });
@@ -48,16 +45,16 @@ const duplicateExportDiagnostic = (
 ): WardenDiagnostic => ({
   filePath: TOPO_FILE,
   line: 1,
-  message: `Library projection contains duplicate export "${exportName}" for trails ${renderTrailIds(trailIds)}. The resolved projection should record the collision and keep only one emitted export.`,
+  message: `Library rendering contains duplicate export "${exportName}" for trails ${renderTrailIds(trailIds)}. The resolved rendering should record the collision and keep only one emitted export.`,
   rule: RULE_NAME,
   severity: 'error',
 });
 
 const collectDuplicateExportDiagnostics = (
-  projection: TopoGraphLibraryProjection
+  rendering: TopoGraphLibraryDerived
 ): readonly WardenDiagnostic[] => {
   const trailIdsByExport = new Map<string, string[]>();
-  for (const entry of projection.exports) {
+  for (const entry of rendering.exports) {
     const trailIds = trailIdsByExport.get(entry.exportName) ?? [];
     trailIds.push(entry.trailId);
     trailIdsByExport.set(entry.exportName, trailIds);
@@ -70,14 +67,14 @@ const collectDuplicateExportDiagnostics = (
 };
 
 const collectMissingTargetDiagnostics = (
-  projection: TopoGraphLibraryProjection,
+  rendering: TopoGraphLibraryDerived,
   knownTrailIds: ReadonlySet<string>
 ): readonly WardenDiagnostic[] =>
-  projection.exports
+  rendering.exports
     .filter((entry) => !knownTrailIds.has(entry.trailId))
     .map((entry) => missingTargetDiagnostic(entry.exportName, entry.trailId));
 
-export const libraryProjectionCoherence: TopoAwareWardenRule = {
+export const libraryRenderCoherence: TopoAwareWardenRule = {
   checkTopo(topo, context) {
     const graph = resolveGraph(topo, context?.graph);
     if (!graph.library) {
@@ -94,7 +91,7 @@ export const libraryProjectionCoherence: TopoAwareWardenRule = {
     ];
   },
   description:
-    'Ensure resolved library projection exports are collision-free and target existing trails.',
+    'Ensure resolved library rendering exports are collision-free and target existing trails.',
   name: RULE_NAME,
   severity: 'error',
 };

package/src/rules/metadata.ts

@@ -84,9 +84,10 @@ const concernByRuleName: Partial<Record<string, WardenRuleConcern>> = {
   'fires-declarations': 'signals',
   'fork-without-preserved-implementation': 'lifecycle',
   'governed-symbol-residue': 'lifecycle',
+  'governed-vocabulary-permutation-watch': 'lifecycle',
   'implementation-returns-result': 'results',
   'intent-propagation': 'composition',
-  'library-projection-coherence': 'meta',
+  'library-render-coherence': 'meta',
   'marker-schema-unsupported': 'lifecycle',
   'missing-reconcile': 'resources',
   'missing-visibility': 'composition',
@@ -316,10 +317,46 @@ const builtinWardenRuleMetadataInput = {
   'governed-symbol-residue': {
     ...durableExternal,
     fix: { class: 'term-rewrite', safety: 'safe' },
+    guidance: {
+      docs: [
+        {
+          label: 'Vocabulary transition workflow',
+          path: 'docs/releases/v1-vocabulary-transition-workflow.md',
+        },
+      ],
+      steps: [
+        'Run the governed transition through Regrade so committed history proves the primary migration.',
+        'Use manual edits only for review or cleanup after Regrade exhausts the safe slice.',
+        'Keep the transition registry and committed history evidence aligned.',
+      ],
+      summary:
+        'Require committed Regrade evidence before completing a governed vocabulary migration.',
+    },
     invariant:
-      'Active governed vocabulary symbol renames do not leave retired identifiers in source.',
+      'Governed vocabulary transitions carry committed Regrade provenance and do not leave or reintroduce retired identifiers.',
     tier: 'source-static',
   },
+  'governed-vocabulary-permutation-watch': {
+    guidance: {
+      docs: [
+        {
+          label: 'Vocabulary transition workflow',
+          path: 'docs/releases/v1-vocabulary-transition-workflow.md',
+        },
+      ],
+      steps: [
+        'Add the unknown form to the governed vocabulary plan and run an incremental Regrade plan.',
+        'If the form is intentionally unrelated or preserved, classify it so later history suppresses the advisory.',
+      ],
+      summary:
+        'Classify unknown governed-stem permutations recorded by committed Regrade history.',
+    },
+    invariant:
+      'Committed Regrade history keeps unknown governed-stem permutations visible until they are classified.',
+    lifecycle: { state: 'durable' },
+    scope: 'advisory',
+    tier: 'project-static',
+  },
   'implementation-returns-result': {
     ...durableExternal,
     invariant: 'Implementations return Result values.',
@@ -343,10 +380,10 @@ const builtinWardenRuleMetadataInput = {
   'layer-field-name-drift': {
     ...durableExternal,
     invariant:
-      'Layer input field reserved names are shared across surface projections.',
+      'Layer input field reserved names are shared across surface renderings.',
     tier: 'source-static',
   },
-  'library-projection-coherence': {
+  'library-render-coherence': {
     ...durableExternal,
     guidance: {
       docs: [
@@ -361,20 +398,20 @@ const builtinWardenRuleMetadataInput = {
       ],
       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.',
-        'Run the generated-package smoke after repairing projection drift.',
+        'Keep serialized derived library exports attached to existing trail IDs.',
+        'Run the generated-package smoke after repairing rendering drift.',
       ],
       summary:
-        'Keep resolved library projection exports collision-free and attached to one trail contract.',
+        'Keep resolved derived library exports collision-free and attached to one trail contract.',
     },
     invariant:
-      'Resolved library projection exports are collision-free and target existing trails.',
+      'Resolved derived library exports are collision-free and target existing trails.',
     tier: 'topo-aware',
   },
   'marker-schema-unsupported': {
     ...durableExternal,
     invariant:
-      'Versioned schemas stay inside the supported marker projection subset.',
+      'Versioned schemas stay inside the supported marker derivation subset.',
     tier: 'source-static',
   },
   'missing-reconcile': {
@@ -503,8 +540,8 @@ const builtinWardenRuleMetadataInput = {
       'Derived store signals are consumed by matching trail on: consumers.',
     tier: 'project-static',
   },
-  'owner-projection-parity': {
-    invariant: 'Framework projections stay aligned with owner exports.',
+  'owner-render-parity': {
+    invariant: 'Framework renderings stay aligned with owner exports.',
     lifecycle: { state: 'durable' },
     scope: 'internal',
     tier: 'source-static',
@@ -565,11 +602,11 @@ const builtinWardenRuleMetadataInput = {
       docs: [trailContractDocs, wardenDocs],
       relatedRules: ['public-union-output-discriminants'],
       steps: [
-        'Add an explicit output schema to public trails that can be projected onto MCP or HTTP surfaces.',
+        'Add an explicit output schema to public trails that can be rendered onto MCP or HTTP surfaces.',
         'If the trail is composition-only, mark it visibility: "internal" instead of exposing it by default.',
       ],
       summary:
-        'Make public surface result contracts explicit before MCP/HTTP projection.',
+        'Make public surface result contracts explicit before MCP/HTTP rendering.',
     },
     invariant: 'Public MCP/HTTP surface trails declare output schemas.',
     tier: 'topo-aware',
@@ -709,7 +746,7 @@ const builtinWardenRuleMetadataInput = {
         'Record explicit visibility-widening acceptance and stable-description metadata when a trailhead intentionally widens visibility.',
       ],
       summary:
-        'Keep trailhead maps reviewable before they reach MCP projection.',
+        'Keep trailhead maps reviewable before they reach MCP rendering.',
     },
     invariant:
       'Trailhead maps avoid selector overlap, hidden visibility widening, and drift-prone dynamic selectors.',