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

package/src/rules/retired-vocabulary.ts

@@ -40,6 +40,17 @@ export const governedVocabularyScopeSchema = z.object({
   extensions: z.array(z.string().min(1)).optional(),
   ignoredDirectories: z.array(z.string().min(1)).optional(),
   include: z.array(z.string().min(1)).optional(),
+  policyClassified: z
+    .array(
+      z.object({
+        disposition: z.enum(['explicit-preserve', 'historical-by-policy']),
+        expectMatches: z.boolean().optional(),
+        paths: z.array(z.string().min(1)).min(1),
+        reason: z.string().min(1),
+      })
+    )
+    .optional(),
+  teachingSurfaces: z.array(z.string().min(1)).optional(),
 });
 
 export const governedVocabularySymbolRenameMatchModes = [
@@ -65,12 +76,42 @@ export const governedVocabularyLiteralRenameSchema = z.object({
   to: z.string().min(1),
 });
 
+export const governedVocabularyFileRenameSchema = z.object({
+  from: z.string().min(1),
+  to: z.string().min(1),
+});
+
+export const governedVocabularyProvenancePolicySchema = z.discriminatedUnion(
+  'mode',
+  [
+    z.object({ mode: z.literal('regrade-history') }),
+    z.object({
+      mode: z.literal('legacy'),
+      reason: z.string().min(1),
+    }),
+  ]
+);
+
+export const governedVocabularyHistoryProvenanceSchema = z
+  .object({
+    disposition: z.enum(['applied-clean', 'review-follow-up']),
+    kind: z.literal('governed-vocabulary'),
+    planContentHash: z.string().regex(/^[0-9a-f]{64}$/),
+    reviewPending: z.number().int().nonnegative(),
+    safeApplied: z.number().int().nonnegative(),
+    sourceHashAfter: z.string().regex(/^[0-9a-f]{64}$/),
+    sourceHashBefore: z.string().regex(/^[0-9a-f]{64}$/),
+    transitionId: z.string().min(1),
+  })
+  .strict();
+
 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),
   }),
+  fileRenames: z.array(governedVocabularyFileRenameSchema).default([]),
   from: z.string().min(1),
   id: z.string().min(1),
   intent: z.string().min(1),
@@ -78,6 +119,11 @@ export const governedVocabularyTransitionSchema = z.object({
   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([]),
+  provenance: governedVocabularyProvenancePolicySchema.default({
+    mode: 'legacy',
+    reason:
+      'Transition completed before committed Regrade history provenance became enforceable.',
+  }),
   reviewForms: z.array(z.string().min(1)).default([]),
   safeRewriteForms: z.record(z.string().min(1), z.string().min(1)).default({}),
   scope: governedVocabularyScopeSchema.optional(),
@@ -113,6 +159,18 @@ export const governedVocabularyRegistrySchema = z
         });
       }
       seenFrom.add(transition.from);
+
+      if (
+        transition.status === 'planned' &&
+        transition.provenance.mode !== 'regrade-history'
+      ) {
+        ctx.addIssue({
+          code: 'custom',
+          message:
+            'Planned governed transitions must require committed Regrade history provenance.',
+          path: [index, 'provenance'],
+        });
+      }
     }
   });
 
@@ -134,6 +192,12 @@ export type GovernedVocabularyLiteralRename = z.output<
 export type GovernedVocabularyTransition = z.output<
   typeof governedVocabularyTransitionSchema
 >;
+export type GovernedVocabularyHistoryProvenance = z.output<
+  typeof governedVocabularyHistoryProvenanceSchema
+>;
+export type GovernedVocabularyProvenancePolicy = z.output<
+  typeof governedVocabularyProvenancePolicySchema
+>;
 export type GovernedVocabularyTransitionInput = z.input<
   typeof governedVocabularyTransitionSchema
 >;
@@ -147,75 +211,66 @@ const reviewFunctionParamDeclarations = {
   reviewDeclarationTypes: ['FunctionParam'],
 };
 
-const v1VocabularyHistoricalExcludes = [
+const v1VocabularyHardExcludes = [
+  '.scratch/**',
+  '**/.scratch/**',
+  '**/.tmp-tests/**',
+];
+
+const v1VocabularyHistoricalPaths = [
   '.agents/goals/**',
   '**/.agents/goals/**',
   '.agents/memory/**',
   '**/.agents/memory/**',
   '.agents/notes/**',
   '**/.agents/notes/**',
+  '.agents/plans/**',
+  '**/.agents/plans/**',
   '.claude/agent-memory/**',
   '**/.claude/agent-memory/**',
-  '.agents/plans/archive/**',
-  '**/.agents/plans/archive/**',
   '.changeset/**',
   '**/.changeset/**',
-  '.scratch/**',
-  '**/.scratch/**',
-  '.trails/regrade/history/**',
-  '**/.trails/regrade/history/**',
+  '.trails/regrade/*.json',
+  '**/.trails/regrade/*.json',
   '**/CHANGELOG.md',
-  '**/.tmp-tests/**',
-];
-
-const v1VocabularyHistoricalPreservePaths = [
-  '.agents/plans/**',
-  '**/.agents/plans/**',
   'docs/adr/0*.md',
   'docs/adr/decision-map.json',
-  'docs/migration/**',
+  'docs/migration/*-to-adapter.md',
+  'docs/migration/*-to-compose.md',
+  'docs/migration/trailhead-to-surface.md',
   'docs/releases/beta*.md',
   'docs/releases/v1-vocabulary-reset.md',
   'docs/releases/v1-vocabulary-transition-workflow.md',
-  'scripts/vocab-cutover-*.ts',
-];
-
-const v1VocabularySelfExcludes = [
   'packages/warden/src/__tests__/retired-vocabulary.test.ts',
   'packages/warden/src/rules/retired-vocabulary.ts',
 ];
 
 const unique = (values: readonly string[]): string[] => [...new Set(values)];
 
-const escapeRegExp = (value: string): string =>
-  value.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
-const formsPattern = (forms: readonly string[]): string =>
-  `(?:${forms.map(escapeRegExp).join('|')})`;
-
 const defineV1Transition = (
   input: GovernedVocabularyTransitionInput
 ): GovernedVocabularyTransition =>
   defineTransition({
     ...input,
-    preserve: [
-      {
-        paths: v1VocabularyHistoricalPreservePaths,
-        pattern: formsPattern(
-          unique([...(input.oldForms ?? []), ...(input.reviewForms ?? [])])
-        ),
-        reason:
-          'Preserve authored migration plans and historical decision/release evidence while keeping occurrences visible to the run ledger.',
-      },
-      ...(input.preserve ?? []),
-    ],
+    preserve: input.preserve ?? [],
     scope: {
       ...input.scope,
       exclude: unique([
-        ...v1VocabularyHistoricalExcludes,
-        ...v1VocabularySelfExcludes,
+        ...v1VocabularyHardExcludes,
         ...(input.scope?.exclude ?? []),
       ]),
+      policyClassified: [
+        {
+          disposition: 'historical-by-policy',
+          paths: v1VocabularyHistoricalPaths,
+          reason:
+            'Preserve authored migration plans and historical decision/release evidence while keeping occurrences visible to the run ledger.',
+        },
+        ...(input.scope?.policyClassified ?? []),
+      ],
+      ...(input.scope?.teachingSurfaces === undefined
+        ? {}
+        : { teachingSurfaces: input.scope.teachingSurfaces }),
     },
   });
 
@@ -339,6 +394,184 @@ export const governedVocabularyTransitions =
       ],
       target: { kind: 'single', to: 'entity' },
     }),
+    defineV1Transition({
+      codeIdentifiers: [
+        '@ontrails/observe',
+        '@ontrails/observe/logtape',
+        '@ontrails/observe/pino',
+        'packages/observe',
+      ],
+      docs: {
+        guidance: [
+          'Treat the public package routes as exact code strings and module specifiers, not as general observability vocabulary.',
+          'Rewrite the temporary Pino and LogTape subpaths only to their renamed temporary owner; their extraction to top-level adapters is a later transition.',
+        ],
+        summary:
+          'The dependency-light observability owner moved from @ontrails/observe to @ontrails/observability.',
+      },
+      from: '@ontrails/observe',
+      id: 'v1-observe-observability',
+      intent:
+        'Rename the dependency-light observability owner and its temporary adapter subpaths for v1.',
+      kind: 'vocabulary',
+      oldForms: [
+        '@ontrails/observe',
+        '@ontrails/observe/logtape',
+        '@ontrails/observe/pino',
+        'packages/observe',
+      ],
+      reviewForms: [],
+      safeRewriteForms: {
+        '@ontrails/observe': '@ontrails/observability',
+        '@ontrails/observe/logtape': '@ontrails/observability/logtape',
+        '@ontrails/observe/pino': '@ontrails/observability/pino',
+        'packages/observe': 'packages/observability',
+      },
+      status: 'complete',
+      stringLiteralRenames: [
+        {
+          from: '@ontrails/observe',
+          moduleSpecifier: { targetPackage: '@ontrails/observability' },
+          to: '@ontrails/observability',
+        },
+        {
+          from: '@ontrails/observe/logtape',
+          moduleSpecifier: { targetPackage: '@ontrails/observability' },
+          to: '@ontrails/observability/logtape',
+        },
+        {
+          from: '@ontrails/observe/pino',
+          moduleSpecifier: { targetPackage: '@ontrails/observability' },
+          to: '@ontrails/observability/pino',
+        },
+        { from: 'packages/observe', to: 'packages/observability' },
+      ],
+      target: { kind: 'single', to: '@ontrails/observability' },
+    }),
+    defineV1Transition({
+      codeIdentifiers: ['@ontrails/observability/logtape'],
+      docs: {
+        guidance: [
+          'Move the temporary observability subpath to the extracted LogTape adapter package.',
+          'Do not retain a compatibility subpath: the extracted package owns the real LogTape dependency boundary.',
+        ],
+        summary:
+          'The temporary LogTape forwarding subpath was extracted into a real top-level adapter package.',
+      },
+      from: '@ontrails/observability/logtape',
+      id: 'v1-observability-logtape-extraction',
+      intent:
+        'Replace the temporary LogTape forwarding subpath with the extracted @ontrails/logtape adapter.',
+      kind: 'vocabulary',
+      oldForms: ['@ontrails/observability/logtape'],
+      reviewForms: [],
+      safeRewriteForms: {
+        '@ontrails/observability/logtape': '@ontrails/logtape',
+      },
+      status: 'complete',
+      stringLiteralRenames: [
+        {
+          from: '@ontrails/observability/logtape',
+          moduleSpecifier: { targetPackage: '@ontrails/logtape' },
+          to: '@ontrails/logtape',
+        },
+      ],
+      target: { kind: 'single', to: '@ontrails/logtape' },
+    }),
+    defineV1Transition({
+      codeIdentifiers: ['@ontrails/observability/pino'],
+      docs: {
+        guidance: [
+          'Move the temporary observability subpath to the extracted Pino adapter package.',
+          'Do not retain a compatibility subpath: the extracted package owns the real Pino dependency boundary.',
+        ],
+        summary:
+          'The temporary Pino forwarding subpath was extracted into a real top-level adapter package.',
+      },
+      from: '@ontrails/observability/pino',
+      id: 'v1-observability-pino-extraction',
+      intent:
+        'Replace the temporary Pino forwarding subpath with the extracted @ontrails/pino adapter.',
+      kind: 'vocabulary',
+      oldForms: ['@ontrails/observability/pino'],
+      reviewForms: [],
+      safeRewriteForms: {
+        '@ontrails/observability/pino': '@ontrails/pino',
+      },
+      status: 'complete',
+      stringLiteralRenames: [
+        {
+          from: '@ontrails/observability/pino',
+          moduleSpecifier: { targetPackage: '@ontrails/pino' },
+          to: '@ontrails/pino',
+        },
+      ],
+      target: { kind: 'single', to: '@ontrails/pino' },
+    }),
+    defineV1Transition({
+      codeIdentifiers: ['@ontrails/tracing', 'packages/tracing'],
+      docs: {
+        guidance: [
+          'Classify root imports by ownership: intrinsic trace contracts belong to @ontrails/core and developer-state APIs belong to @ontrails/observability/dev.',
+          'Do not mechanically redirect the tracing root because it formerly combined more than one owner.',
+        ],
+        summary:
+          'The former tracing root was folded into core and the observability developer-state subpath.',
+      },
+      from: '@ontrails/tracing',
+      id: 'v1-tracing-owner-fold',
+      intent:
+        'Remove the multi-owner tracing package without inventing a false one-to-one package redirect.',
+      kind: 'vocabulary',
+      oldForms: ['@ontrails/tracing', 'packages/tracing'],
+      reviewForms: [],
+      safeRewriteForms: {},
+      status: 'complete',
+      target: {
+        guidance:
+          'Root tracing imports require ownership classification; use @ontrails/core for intrinsic contracts and @ontrails/observability/dev for developer-state APIs.',
+        kind: 'classified',
+        options: [
+          {
+            to: '@ontrails/core',
+            when: 'The imported symbol is an intrinsic trace record, context, or sink registry contract.',
+          },
+          {
+            to: '@ontrails/observability/dev',
+            when: 'The imported symbol is developer-state storage, sampling, or tracing query/status tooling.',
+          },
+        ],
+      },
+    }),
+    defineV1Transition({
+      codeIdentifiers: ['@ontrails/tracing/otel'],
+      docs: {
+        guidance: [
+          'Rewrite the exact OTel adapter subpath after the observability package declares its /otel export.',
+        ],
+        summary:
+          'The supported OTel adapter moved to the observability package.',
+      },
+      from: '@ontrails/tracing/otel',
+      id: 'v1-tracing-otel-observability-otel',
+      intent:
+        'Move the dependency-light OTel adapter from the removed tracing package to @ontrails/observability/otel.',
+      kind: 'vocabulary',
+      oldForms: ['@ontrails/tracing/otel'],
+      reviewForms: [],
+      safeRewriteForms: {
+        '@ontrails/tracing/otel': '@ontrails/observability/otel',
+      },
+      status: 'complete',
+      stringLiteralRenames: [
+        {
+          from: '@ontrails/tracing/otel',
+          moduleSpecifier: { targetPackage: '@ontrails/observability' },
+          to: '@ontrails/observability/otel',
+        },
+      ],
+      target: { kind: 'single', to: '@ontrails/observability/otel' },
+    }),
     defineV1Transition({
       codeIdentifiers: [
         '@ontrails/topographer',
@@ -556,7 +789,105 @@ export const governedVocabularyTransitions =
       target: { kind: 'single', to: '@ontrails/topography' },
     }),
     defineV1Transition({
-      codeIdentifiers: [],
+      codeIdentifiers: [
+        'ActivationSourceProjection',
+        'AstFieldProjection',
+        'DeriveTrailCliCommandProjectionOptions',
+        'ErrorClassSurfaceProjection',
+        'ErrorDiagnosticsProjection',
+        'HTTP_METHOD_PROJECTION_PATH',
+        'HttpInputProjection',
+        'HttpLayerInputProjection',
+        'LayerFieldProjection',
+        'LayerFlagProjection',
+        'LibraryInputProjection',
+        'LibraryLayerFieldProjection',
+        'LibraryLayerInputProjection',
+        'LibraryProjection',
+        'McpInputProjection',
+        'McpLayerInputProjection',
+        'NormalizedTopoProjection',
+        'OutputSchemaProjection',
+        'PROJECTION_BLOCKING_RULES',
+        'ProjectionMap',
+        'ProjectedLayerField',
+        'ProjectedPermitRequirement',
+        'RenamedLayerFieldProjection',
+        'ShippedSurfaceProjection',
+        'SurfaceErrorProjection',
+        'SurfaceProjectionSource',
+        'SurfaceTrailVersionProjection',
+        'TopoGraphLibraryProjection',
+        'TopoStoreSurfaceProjectionRecord',
+        'TopoSurfaceProjectionRow',
+        'TrailCliCommandProjection',
+        'TrailCliProjection',
+        'TrailCliProjectionInput',
+        'TrailErrorTaxonomyProjection',
+        'buildOutputSchemaProjection',
+        'buildProjectionDiagnostic',
+        'cliProjection',
+        'cliProjectionSchema',
+        'collectLibraryProjection',
+        'projectActivationEdge',
+        'projectActivationSource',
+        'projectActivationSourceDeclaration',
+        'projectActual',
+        'projectAstFields',
+        'projectErrorClassSurface',
+        'projectErrorDiagnostics',
+        'projectExample',
+        'projectHttpInputSchema',
+        'projectHttpLayerInput',
+        'projectInputForSchema',
+        'projectLayerFieldName',
+        'projectLayerFlags',
+        'projectLayerInputFields',
+        'projectLibraryInput',
+        'projectMcpInputSchema',
+        'projectMcpLayerInput',
+        'projectMcpOutputSchema',
+        'projectPermitRequirement',
+        'projectPublicSurfaceError',
+        'projectSchema',
+        'projectSignalAssertion',
+        'projectSignalAssertions',
+        'projectSignalExample',
+        'projectSingleLayerFlags',
+        'projectSurfaceError',
+        'projectSurfaceMapTool',
+        'projectTrailVersionEntry',
+        'projectTrailVersions',
+        'projectVersionDetours',
+        'projectVersionRuntimeRefs',
+        'SchemaProjector',
+        'deriveShippedSurfaceProjectionInventory',
+        'deriveTrailCliCommandProjection',
+        'errorSurfaceProjectionSchema',
+        'errorTaxonomyProjectionSchema',
+        'expectProjectionCounts',
+        'inputProjection',
+        'isProjectionBlockingIssue',
+        'isTrailCliProjection',
+        'keepProjectionBlockingIssues',
+        'layerProjection',
+        'libraryProjectionCoherence',
+        'libraryProjectionCoherenceTrail',
+        'normalizeTopoProjection',
+        'ownerProjectionParity',
+        'ownerProjectionParityTrail',
+        'projectionDb',
+        'projectionKeys',
+        'projectionSource',
+        'seedLegacyProjectionStore',
+        'simpleProjectionApp',
+        'surfaceProjectionBaseOutput',
+        'surfaceProjectionOutput',
+        'taxonomyProjection',
+        'topoGraphLibraryProjectionSchema',
+        'trailCliProjectionFor',
+        'withProjectionDb',
+      ],
       docs: {
         guidance: [
           'Use derive for contract-owned fact production.',
@@ -565,15 +896,413 @@ export const governedVocabularyTransitions =
         ],
         summary: 'Projection vocabulary splits by stage into derive or render.',
       },
+      fileRenames: [
+        {
+          from: 'docs/adr/drafts/20260608-release-provenance-as-lifecycle-projection.md',
+          to: 'docs/adr/drafts/20260608-release-provenance-as-lifecycle-derivation.md',
+        },
+        {
+          from: 'packages/cli/src/__tests__/layer-input-projection.test.ts',
+          to: 'packages/cli/src/__tests__/layer-input-rendering.test.ts',
+        },
+        {
+          from: 'packages/core/src/__tests__/activation-source-projection.test.ts',
+          to: 'packages/core/src/__tests__/activation-source-derivation.test.ts',
+        },
+        {
+          from: 'packages/core/src/__tests__/error-projection.test.ts',
+          to: 'packages/core/src/__tests__/error-rendering.test.ts',
+        },
+        {
+          from: 'packages/core/src/activation-source-projection.ts',
+          to: 'packages/core/src/activation-source-derivation.ts',
+        },
+        {
+          from: 'packages/core/src/error-projection.ts',
+          to: 'packages/core/src/error-rendering.ts',
+        },
+        {
+          from: 'packages/core/src/layer-projection.ts',
+          to: 'packages/core/src/layer-field-rendering.ts',
+        },
+        {
+          from: 'packages/http/src/__tests__/layer-input-projection.test.ts',
+          to: 'packages/http/src/__tests__/layer-input-rendering.test.ts',
+        },
+        {
+          from: 'packages/mcp/src/__tests__/layer-input-projection.test.ts',
+          to: 'packages/mcp/src/__tests__/layer-input-rendering.test.ts',
+        },
+        {
+          from: 'packages/topography/src/library-projection.ts',
+          to: 'packages/topography/src/library-derivation.ts',
+        },
+        {
+          from: 'packages/warden/src/__tests__/library-projection-coherence.test.ts',
+          to: 'packages/warden/src/__tests__/library-render-coherence.test.ts',
+        },
+        {
+          from: 'packages/warden/src/__tests__/owner-projection-parity.test.ts',
+          to: 'packages/warden/src/__tests__/owner-render-parity.test.ts',
+        },
+        {
+          from: 'packages/warden/src/rules/library-projection-coherence.ts',
+          to: 'packages/warden/src/rules/library-render-coherence.ts',
+        },
+        {
+          from: 'packages/warden/src/rules/owner-projection-parity.ts',
+          to: 'packages/warden/src/rules/owner-render-parity.ts',
+        },
+        {
+          from: 'packages/warden/src/trails/library-projection-coherence.trail.ts',
+          to: 'packages/warden/src/trails/library-render-coherence.trail.ts',
+        },
+        {
+          from: 'packages/warden/src/trails/owner-projection-parity.trail.ts',
+          to: 'packages/warden/src/trails/owner-render-parity.trail.ts',
+        },
+      ],
       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'],
+      oldForms: [
+        'projection',
+        'projections',
+        'project',
+        'projects',
+        'Projects',
+        'projecting',
+        'Projecting',
+        'projected',
+        'Projected',
+      ],
+      preserve: [
+        {
+          pattern: "\\b[Pp]roject(?:[-/:]|['’]s\\b)",
+          reason:
+            'Preserve compound project-domain nouns, permit scopes, paths, and possessives without suppressing the standalone retired verb.',
+        },
+        {
+          pattern:
+            '\\b[Pp]roject\\s+(?:root|directory|files?|paths?|state|scripts?|guidance|structure|name|marker|context|conventions?|vocabulary|rules?|findings?|operations?|key|source|config|metadata|policy|package|scope|entities|resources|diagnostics|history|update|control|instructions?|overview|documentation|boundary|helpers?|shape|dependencies|dependency|detection|substrate|truth|work|writing|management|settings?|skills?|issue|ids?)\\b',
+          reason:
+            'Preserve project as an attributive noun before established repository and workspace concepts.',
+        },
+        {
+          pattern:
+            '\\b(?:A|An|The|This|That|a|an|the|this|that|each|entire|every|existing|new|current|same|target|nested|downstream|Trails|Linear|Node|UX|logical|adopting|generated|scaffolded|source-shaped|first-party|temp)\\s+project\\b',
+          reason:
+            'Preserve project as an ordinary count noun selected by a determiner or domain adjective.',
+        },
+        {
+          pattern:
+            "\\b(?:Trails|Matt[’']s|Vite|ADR|adopting|application|consumer|customer|developer|framework|package|software|source|workspace|generated|scaffolded|new|existing|source-shaped|first-party|downstream|most|large|all|many|multiple|other|our|several|their|these|those|your)\\s+projects\\b",
+          reason:
+            'Preserve projects as an ordinary plural repository or application noun selected by an established domain modifier.',
+        },
+        {
+          pattern:
+            '\\b(?:across|among|between|for|from|in|inside|of|outside|under|within|with|without)\\s+(?:the\\s+)?projects\\b',
+          reason:
+            'Preserve projects as the object of a repository or application preposition.',
+        },
+        {
+          pattern:
+            '(?:[\'"`/.][Pp]rojects(?:[\'"`/]|\\b)|\\b[Pp]rojects\\b\\s*(?:=|[):;,]))',
+          reason:
+            'Preserve exact projects domain literals, member accesses, route segments, and enum values.',
+        },
+        {
+          pattern:
+            '\\b(?:in|for|within|across|under|outside|inside|from|of|with|without|per|before|after)\\s+(?:the\\s+)?project\\b',
+          reason:
+            'Preserve project as the object of a repository or workspace preposition.',
+        },
+        {
+          pattern:
+            '(?:[\'"`/]project(?:[\'"`/]|\\b)|\\bproject\\b\\s*(?:=|[);,]))',
+          reason:
+            'Preserve exact project domain literals, example variables, route segments, and enum values.',
+        },
+        {
+          pattern:
+            '(?:\\bmemory:\\s*project\\b|\\bproject\\b(?=\\s+(?:from|health-check|show)\\b))',
+          reason:
+            'Preserve project as an exact metadata value, import alias, or domain command segment.',
+        },
+        {
+          pattern:
+            '(?:\\bA Node project\\b|\\ba non-trivial UX project\\b|\\bproject\\s+`warden\\.)',
+          reason:
+            'Preserve established multiword project nouns and project-scoped Warden configuration prose.',
+        },
+      ],
+      provenance: { mode: 'regrade-history' },
+      reviewForms: [
+        'projection',
+        'projections',
+        'project',
+        'projects',
+        'Projects',
+        'projecting',
+        'Projecting',
+        'projected',
+        'Projected',
+      ],
       safeRewriteForms: {},
-      status: 'planned',
+      scope: {
+        policyClassified: [
+          {
+            disposition: 'explicit-preserve',
+            expectMatches: true,
+            paths: [
+              'apps/trails/src/__tests__/mcp.test.ts',
+              'apps/trails/src/__tests__/regrade.test.ts',
+              'packages/regrade/src/downstream/__tests__/**/*.test.ts',
+            ],
+            reason:
+              'Preserve exact old/new vocabulary fixtures that prove CLI, MCP, registry, and rewrite behavior without treating them as current teaching or API residue.',
+          },
+          {
+            disposition: 'historical-by-policy',
+            expectMatches: true,
+            paths: ['docs/adr/0*.md'],
+            reason:
+              'The Trails projection census records accepted ADR history that must remain visible during the v1 split.',
+          },
+        ],
+        teachingSurfaces: ['docs/**'],
+      },
+      status: 'complete',
+      stringLiteralRenames: [
+        {
+          from: 'library-projection-coherence',
+          to: 'library-render-coherence',
+        },
+        { from: 'owner-projection-parity', to: 'owner-render-parity' },
+        { from: 'surface-projects', to: 'surface-renders' },
+      ],
+      symbolRenames: [
+        { from: 'ActivationSourceProjection', to: 'ActivationSourceFacts' },
+        { from: 'AstFieldProjection', to: 'AstFieldView' },
+        {
+          from: 'DeriveTrailCliCommandProjectionOptions',
+          to: 'DeriveTrailCliCommandOptions',
+        },
+        {
+          from: 'ErrorClassSurfaceProjection',
+          to: 'ErrorClassSurfaceRendering',
+        },
+        {
+          from: 'ErrorDiagnosticsProjection',
+          to: 'ErrorDiagnosticsRendering',
+        },
+        {
+          from: 'HTTP_METHOD_PROJECTION_PATH',
+          to: 'HTTP_METHOD_DERIVATION_PATH',
+        },
+        { from: 'HttpInputProjection', to: 'HttpInputRendering' },
+        {
+          from: 'HttpLayerInputProjection',
+          to: 'HttpLayerInputRendering',
+        },
+        { from: 'LayerFieldProjection', to: 'LayerFieldRendering' },
+        { from: 'LayerFlagProjection', to: 'LayerFlagRendering' },
+        { from: 'LibraryInputProjection', to: 'LibraryInputRendering' },
+        {
+          from: 'LibraryLayerFieldProjection',
+          to: 'LibraryLayerFieldRendering',
+        },
+        {
+          from: 'LibraryLayerInputProjection',
+          to: 'LibraryLayerInputRendering',
+        },
+        { from: 'LibraryProjection', to: 'LibraryRenderingPlan' },
+        { from: 'McpInputProjection', to: 'McpInputRendering' },
+        {
+          from: 'McpLayerInputProjection',
+          to: 'McpLayerInputRendering',
+        },
+        { from: 'NormalizedTopoProjection', to: 'NormalizedTopoFacts' },
+        {
+          from: 'OutputSchemaProjection',
+          to: 'McpOutputSchemaRendering',
+        },
+        {
+          from: 'PROJECTION_BLOCKING_RULES',
+          to: 'DERIVATION_BLOCKING_RULES',
+        },
+        { from: 'ProjectionMap', to: 'IntentKeyMap' },
+        { from: 'ProjectedLayerField', to: 'RenderedLayerField' },
+        {
+          from: 'ProjectedPermitRequirement',
+          to: 'DerivedPermitRequirement',
+        },
+        {
+          from: 'RenamedLayerFieldProjection',
+          to: 'RenamedLayerFieldRendering',
+        },
+        { from: 'ShippedSurfaceProjection', to: 'ShippedSurfaceDerived' },
+        { from: 'SurfaceErrorProjection', to: 'SurfaceErrorRendering' },
+        { from: 'SurfaceProjectionSource', to: 'SurfaceDerivedSource' },
+        {
+          from: 'SurfaceTrailVersionProjection',
+          to: 'SurfaceTrailVersionRendering',
+        },
+        {
+          from: 'TopoGraphLibraryProjection',
+          to: 'TopoGraphLibraryDerived',
+        },
+        {
+          from: 'TopoStoreSurfaceProjectionRecord',
+          to: 'TopoStoreSurfaceDerivedRecord',
+        },
+        {
+          from: 'TopoSurfaceProjectionRow',
+          to: 'TopoSurfaceDerivedRow',
+        },
+        {
+          from: 'TrailCliCommandProjection',
+          to: 'TrailCliCommandRendering',
+        },
+        { from: 'TrailCliProjection', to: 'TrailCliRendering' },
+        {
+          from: 'TrailCliProjectionInput',
+          to: 'TrailCliRenderingInput',
+        },
+        {
+          from: 'TrailErrorTaxonomyProjection',
+          to: 'TrailErrorTaxonomyFacts',
+        },
+        {
+          from: 'buildOutputSchemaProjection',
+          to: 'buildMcpOutputSchemaRendering',
+        },
+        {
+          from: 'buildProjectionDiagnostic',
+          to: 'buildDerivationDiagnostic',
+        },
+        { from: 'cliProjection', to: 'cliRendering' },
+        { from: 'cliProjectionSchema', to: 'cliDerivedSchema' },
+        {
+          from: 'collectLibraryProjection',
+          to: 'deriveTopoGraphLibrary',
+        },
+        { from: 'projectActivationEdge', to: 'deriveActivationEdge' },
+        { from: 'projectActivationSource', to: 'deriveActivationSource' },
+        {
+          from: 'projectActivationSourceDeclaration',
+          to: 'deriveActivationSourceFacts',
+        },
+        { from: 'projectActual', to: 'deriveActualOutcome' },
+        { from: 'projectAstFields', to: 'deriveAstFieldView' },
+        {
+          from: 'projectErrorClassSurface',
+          to: 'renderErrorClassSurface',
+        },
+        { from: 'projectErrorDiagnostics', to: 'renderErrorDiagnostics' },
+        { from: 'projectExample', to: 'deriveExample' },
+        { from: 'projectHttpInputSchema', to: 'renderHttpInputSchema' },
+        { from: 'projectHttpLayerInput', to: 'renderHttpLayerInput' },
+        { from: 'projectInputForSchema', to: 'deriveInputForSchema' },
+        { from: 'projectLayerFieldName', to: 'renderLayerFieldName' },
+        { from: 'projectLayerFlags', to: 'renderLayerFlags' },
+        { from: 'projectLayerInputFields', to: 'renderLayerInputFields' },
+        { from: 'projectLibraryInput', to: 'renderLibraryInput' },
+        { from: 'projectMcpInputSchema', to: 'renderMcpInputSchema' },
+        { from: 'projectMcpLayerInput', to: 'renderMcpLayerInput' },
+        { from: 'projectMcpOutputSchema', to: 'renderMcpOutputSchema' },
+        { from: 'projectPermitRequirement', to: 'derivePermitRequirement' },
+        {
+          from: 'projectPublicSurfaceError',
+          to: 'renderPublicSurfaceError',
+        },
+        { from: 'projectSchema', to: 'deriveSchema' },
+        { from: 'projectSignalAssertion', to: 'deriveSignalAssertion' },
+        { from: 'projectSignalAssertions', to: 'deriveSignalAssertions' },
+        { from: 'projectSignalExample', to: 'deriveSignalExample' },
+        { from: 'projectSingleLayerFlags', to: 'renderSingleLayerFlags' },
+        { from: 'projectSurfaceError', to: 'renderSurfaceError' },
+        { from: 'projectSurfaceMapTool', to: 'renderSurfaceMapTool' },
+        { from: 'projectTrailVersionEntry', to: 'deriveTrailVersionEntry' },
+        { from: 'projectTrailVersions', to: 'deriveTrailVersions' },
+        { from: 'projectVersionDetours', to: 'deriveVersionDetours' },
+        {
+          from: 'projectVersionRuntimeRefs',
+          to: 'deriveVersionRuntimeRefs',
+        },
+        { from: 'SchemaProjector', to: 'SchemaDeriver' },
+        {
+          from: 'deriveShippedSurfaceProjectionInventory',
+          to: 'deriveShippedSurfaceInventory',
+        },
+        {
+          from: 'deriveTrailCliCommandProjection',
+          to: 'deriveTrailCliCommandRendering',
+        },
+        {
+          from: 'errorSurfaceProjectionSchema',
+          to: 'errorSurfaceDerivedSchema',
+        },
+        {
+          from: 'errorTaxonomyProjectionSchema',
+          to: 'errorTaxonomyDerivedSchema',
+        },
+        { from: 'expectProjectionCounts', to: 'expectDerivedRowCounts' },
+        { from: 'inputProjection', to: 'inputRendering' },
+        {
+          from: 'isProjectionBlockingIssue',
+          to: 'isDerivationBlockingIssue',
+        },
+        { from: 'isTrailCliProjection', to: 'isTrailCliRendering' },
+        {
+          from: 'keepProjectionBlockingIssues',
+          to: 'keepDerivationBlockingIssues',
+        },
+        { from: 'layerProjection', to: 'layerRendering' },
+        {
+          from: 'libraryProjectionCoherence',
+          to: 'libraryRenderCoherence',
+        },
+        {
+          from: 'libraryProjectionCoherenceTrail',
+          to: 'libraryRenderCoherenceTrail',
+        },
+        {
+          from: 'normalizeTopoProjection',
+          to: 'deriveNormalizedTopoRows',
+        },
+        { from: 'ownerProjectionParity', to: 'ownerRenderParity' },
+        {
+          from: 'ownerProjectionParityTrail',
+          to: 'ownerRenderParityTrail',
+        },
+        { from: 'projectionDb', to: 'derivedDb' },
+        { from: 'projectionKeys', to: 'derivedKeys' },
+        { from: 'projectionSource', to: 'derivedSource' },
+        {
+          from: 'seedLegacyProjectionStore',
+          to: 'seedLegacyDerivedStore',
+        },
+        { from: 'simpleProjectionApp', to: 'simpleDerivedRowsApp' },
+        {
+          from: 'surfaceProjectionBaseOutput',
+          to: 'surfaceDerivedBaseOutput',
+        },
+        {
+          from: 'surfaceProjectionOutput',
+          to: 'surfaceDerivedOutput',
+        },
+        { from: 'taxonomyProjection', to: 'deriveTaxonomyFacts' },
+        {
+          from: 'topoGraphLibraryProjectionSchema',
+          to: 'topoGraphLibraryDerivedSchema',
+        },
+        { from: 'trailCliProjectionFor', to: 'trailCliRenderingFor' },
+        { from: 'withProjectionDb', to: 'withDerivedDb' },
+      ],
       target: {
         guidance:
           'No single replacement is safe. Classify by whether the occurrence produces contract facts or presents derived facts.',
@@ -625,6 +1354,11 @@ export const formatGovernedVocabularyTransitionGuide = (
         `- ${transition.id}: ${transition.from} -> ${target}`,
         `  - Status: ${transition.status}`,
         `  - Intent: ${transition.intent}`,
+        `  - Provenance: ${
+          transition.provenance.mode === 'regrade-history'
+            ? 'committed Regrade history required'
+            : `legacy (${transition.provenance.reason})`
+        }`,
         `  - Safe rewrites: ${Object.keys(transition.safeRewriteForms).length}`,
         `  - Review forms: ${transition.reviewForms.join(', ') || 'none'}`,
       ];