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

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @ontrails/warden
 
+## 1.0.0-beta.32
+
+### Patch Changes
+
+- 3e5c0fc: Export shared diagnostic base types from core and align governance diagnostic
+  severity vocabulary across adapter checks, permits, and Warden.
+- f3c4fef: Export a shared `escapeRegExp` helper from core and migrate first-party callers off local copies.
+- cb0a9d8: Export shared workspace package discovery helpers from core and migrate first-party discovery callers.
+- fe72b84: Fold remaining Regrade and Warden scan-target surfaces onto the shared path-scope vocabulary.
+- Updated dependencies [3e5c0fc]
+- Updated dependencies [f3c4fef]
+- Updated dependencies [cb0a9d8]
+- Updated dependencies [8db145e]
+- Updated dependencies [2b819f4]
+- Updated dependencies [21c6dda]
+- Updated dependencies [860ef32]
+- Updated dependencies [fe72b84]
+  - @ontrails/adapter-kit@1.0.0-beta.32
+  - @ontrails/core@1.0.0-beta.32
+  - @ontrails/permits@1.0.0-beta.32
+  - @ontrails/topographer@1.0.0-beta.32
+  - @ontrails/config@1.0.0-beta.32
+  - @ontrails/cli@1.0.0-beta.32
+  - @ontrails/store@1.0.0-beta.32
+
+## 1.0.0-beta.31
+
+### Patch Changes
+
+- ee9f3ae: Let Warden fix capabilities declare downstream scan targets and have Regrade
+  honor those targets for Warden-backed term-rewrite classes.
+
+  Dogfood the first safe facet-to-trailhead prose rewrite through project-local
+  Warden rules and Regrade.
+
+- a0126d9: Add Warden `scope.exclude` globs through project config and the Trails CLI
+  wrapper so governance runs can exclude local notes, scratch space, and generated
+  state without dropping durable skills or plugin assets from scope.
+- 6a26a08: Rename Warden governance scope controls from jurisdiction ignore settings to `scope.exclude` across config, CLI, and Trails surfaces.
+- Updated dependencies [4cd5d4e]
+- Updated dependencies [38907cc]
+  - @ontrails/core@1.0.0-beta.31
+  - @ontrails/adapter-kit@1.0.0-beta.31
+  - @ontrails/cli@1.0.0-beta.31
+  - @ontrails/config@1.0.0-beta.31
+  - @ontrails/permits@1.0.0-beta.31
+  - @ontrails/store@1.0.0-beta.31
+  - @ontrails/topographer@1.0.0-beta.31
+
 ## 1.0.0-beta.30
 
 ### Patch Changes

package/README.md

@@ -47,6 +47,28 @@ Warden uses the shared Trails project-root resolver when a caller does not pass
 
 This is the right home for repo-specific migration checks or governance that has not earned a place in `@ontrails/warden` itself.
 
+## Scope
+
+Use `warden.scope.exclude` in `trails.config.*` to keep generated, scratch, or local planning paths outside Warden governance while leaving durable project paths in scope.
+
+```json
+{
+  "warden": {
+    "scope": {
+      "exclude": [".scratch/**", ".agents/notes/**"]
+    }
+  }
+}
+```
+
+For a single run, pass one or more root-relative globs:
+
+```bash
+warden --scope-exclude '.scratch/**' --scope-exclude '.agents/notes/**'
+```
+
+Scope is a governance boundary, not a migration scan boundary. Regrade uses its own `scope.exclude` / `--exclude` controls for migration plans.
+
 A rule module may export `rule`, `rules`, `sourceRule`, `sourceRules`, `topoRule`, or `topoRules`. Rules without explicit metadata receive default repo-local source-static or topo-aware metadata so short migration rules can run without extra ceremony. Project-aware source rules that provide `checkWithContext()` default to repo-local project-static metadata.
 
 ```typescript

package/bin/warden.ts

@@ -19,6 +19,7 @@ Options:
   --fail-on <value>            error or warning
   --format <value>             summary, github, or json
   --drafts <value>             include, exclude, or only
+  --scope-exclude <glob>       Root-relative path glob Warden should not govern
   --lock <value>               auto, cached, refresh, or skip
   --no-lock-mutation           Do not write lock artifacts
   --strict                     Fail on warnings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/warden",
-  "version": "1.0.0-beta.30",
+  "version": "1.0.0-beta.32",
   "bin": {
     "warden": "./bin/warden.ts"
   },
@@ -28,21 +28,21 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/adapter-kit": "^1.0.0-beta.30",
-    "@ontrails/cli": "^1.0.0-beta.30",
-    "@ontrails/config": "^1.0.0-beta.30",
-    "@ontrails/permits": "^1.0.0-beta.30",
-    "@ontrails/store": "^1.0.0-beta.30",
+    "@ontrails/adapter-kit": "^1.0.0-beta.32",
+    "@ontrails/cli": "^1.0.0-beta.32",
+    "@ontrails/config": "^1.0.0-beta.32",
+    "@ontrails/permits": "^1.0.0-beta.32",
+    "@ontrails/store": "^1.0.0-beta.32",
     "oxc-parser": "^0.121.0",
     "oxc-resolver": "11.19.1",
     "oxc-walker": "^1.0.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/testing": "^1.0.0-beta.30"
+    "@ontrails/testing": "^1.0.0-beta.32"
   },
   "peerDependencies": {
-    "@ontrails/core": "^1.0.0-beta.30",
-    "@ontrails/topographer": "^1.0.0-beta.30"
+    "@ontrails/core": "^1.0.0-beta.32",
+    "@ontrails/topographer": "^1.0.0-beta.32"
   }
 }

package/src/cli.ts

@@ -8,10 +8,10 @@
 import { isAbsolute, relative, resolve } from 'node:path';
 
 import { resolveTrailsProjectRoot } from '@ontrails/config';
+import { getContourReferences, matchesAnyPathGlob } from '@ontrails/core';
 import type { Topo } from '@ontrails/core';
 import { deriveTopoGraph } from '@ontrails/topographer';
 import type { TopoGraph } from '@ontrails/topographer';
-import { getContourReferences } from '@ontrails/core';
 
 import type {
   EffectiveWardenConfig,
@@ -20,6 +20,7 @@ import type {
   WardenDepth,
   WardenFailOn,
   WardenFormat,
+  WardenScope,
   WardenLockMode,
 } from './config.js';
 import { runWardenAdapterChecks } from './adapter-check.js';
@@ -105,6 +106,8 @@ export interface WardenRunOptions {
   readonly fix?: boolean | undefined;
   /** Output format requested by the caller. */
   readonly format?: WardenFormat | undefined;
+  /** Root-relative source paths that Warden should not govern. */
+  readonly scope?: WardenScope | undefined;
   /** Lockfile mode requested by the caller. */
   readonly lock?: WardenLockMode | undefined;
   /** Suppress lockfile mutation for CI/pre-push callers. */
@@ -260,6 +263,29 @@ const filterSourceFilesByDraftMode = (
         draftModeIncludesFile(sourceFile.filePath, drafts)
       );
 
+const rootRelativeScopePath = (rootDir: string, filePath: string): string =>
+  relative(rootDir, filePath).replaceAll('\\', '/');
+
+const filterSourceFilesByScope = (
+  sourceFiles: readonly SourceFile[],
+  rootDir: string,
+  scope: WardenScope
+): readonly SourceFile[] => {
+  if (scope.exclude.length === 0) {
+    return sourceFiles;
+  }
+
+  return sourceFiles.filter(
+    (sourceFile) =>
+      !matchesAnyPathGlob(
+        rootRelativeScopePath(rootDir, sourceFile.filePath),
+        scope.exclude
+      )
+  );
+};
+
+const EMPTY_WARDEN_SCOPE: WardenScope = { exclude: [] };
+
 const collectDevPermitTestFiles = (dir: string): readonly string[] => {
   const glob = new Bun.Glob('**/*.ts');
   let matches: IterableIterator<string>;
@@ -799,6 +825,7 @@ const collectFileImportResolutions = (
   context: MutableProjectContext
 ): void => {
   const resolutionsByFile = collectProjectImportResolutions({
+    publicWorkspaces: context.publicWorkspaces,
     rootDir,
     sourceFiles,
   });
@@ -813,6 +840,7 @@ const collectFileDocumentedImportResolutions = (
   context: MutableProjectContext
 ): void => {
   const resolutionsByFile = collectProjectDocumentationImportResolutions({
+    publicWorkspaces: context.publicWorkspaces,
     rootDir,
     sourceFiles,
   });
@@ -824,7 +852,8 @@ const collectFileDocumentedImportResolutions = (
 const buildProjectContext = (
   sourceFiles: readonly SourceFile[],
   rootDir: string,
-  appTopos: readonly Topo[] = []
+  appTopos: readonly Topo[] = [],
+  scope: WardenScope = EMPTY_WARDEN_SCOPE
 ): ProjectContext => {
   const context = createMutableProjectContext();
   const typeScriptSourceFiles = sourceFiles.filter(
@@ -833,7 +862,9 @@ const buildProjectContext = (
   const documentationSourceFiles = sourceFiles.filter(
     (sourceFile) => sourceFile.kind === 'documentation'
   );
-  context.publicWorkspaces = collectPublicWorkspaces(rootDir);
+  context.publicWorkspaces = collectPublicWorkspaces(rootDir, {
+    exclude: scope.exclude,
+  });
 
   if (appTopos.length > 0) {
     for (const appTopo of appTopos) {
@@ -1145,6 +1176,7 @@ interface WardenLintResult {
 const lintFiles = async (
   rootDir: string,
   drafts: EffectiveWardenConfig['drafts'],
+  scope: EffectiveWardenConfig['scope'],
   topoTargets: readonly WardenTopoTarget[],
   extraTopoRules: readonly TopoAwareWardenRule[],
   extraSourceRules: readonly WardenRule[],
@@ -1159,14 +1191,16 @@ const lintFiles = async (
     };
   }
 
-  const sourceFiles = filterSourceFilesByDraftMode(
-    await loadSourceFiles(rootDir),
-    drafts
+  const sourceFiles = filterSourceFilesByScope(
+    filterSourceFilesByDraftMode(await loadSourceFiles(rootDir), drafts),
+    rootDir,
+    scope
   );
   const context = buildProjectContext(
     sourceFiles,
     rootDir,
-    topoTargets.map((target) => target.topo)
+    topoTargets.map((target) => target.topo),
+    scope
   );
   const allDiagnostics: WardenDiagnostic[] = [
     ...lintSourceFiles(sourceFiles, context, extraSourceRules, selector),
@@ -1339,6 +1373,7 @@ const buildCliConfigLayer = (options: WardenRunOptions): WardenConfigLayer => ({
   ...(options.drafts ? { drafts: options.drafts } : {}),
   ...(options.failOn ? { failOn: options.failOn } : {}),
   ...(options.format ? { format: options.format } : {}),
+  ...(options.scope ? { scope: options.scope } : {}),
   ...(options.lock ? { lock: options.lock } : {}),
   ...(options.noLockMutation === undefined
     ? {}
@@ -1476,6 +1511,7 @@ export const runWarden = async (
     ? await lintFiles(
         rootDir,
         effectiveConfig.drafts,
+        effectiveConfig.scope,
         topoTargets,
         [...projectRules.topoRules, ...(options.extraTopoRules ?? [])],
         [...projectRules.sourceRules, ...(options.extraSourceRules ?? [])],

package/src/command.ts

@@ -26,6 +26,7 @@ import type {
   WardenDraftsMode,
   WardenFailOn,
   WardenFormat,
+  WardenScope,
   WardenLockMode,
 } from './config.js';
 import {
@@ -57,6 +58,7 @@ interface MutableWardenConfigLayer {
   drafts?: WardenDraftsMode | undefined;
   failOn?: WardenFailOn | undefined;
   format?: WardenFormat | undefined;
+  scope?: WardenScope | undefined;
   lock?: WardenLockMode | undefined;
   noLockMutation?: boolean | undefined;
 }
@@ -95,6 +97,12 @@ const splitApps = (value: string): readonly string[] =>
     .map((entry) => entry.trim())
     .filter((entry) => entry.length > 0);
 
+const splitCommaDelimitedValues = (value: string): readonly string[] =>
+  value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+
 const isAllowedValue = <T extends string>(
   value: string,
   allowed: readonly T[]
@@ -248,6 +256,7 @@ const parseTokens = (
         'no-lock-mutation': { type: 'boolean' },
         'pre-push': { type: 'boolean' },
         'root-dir': { type: 'string' },
+        'scope-exclude': { multiple: true, type: 'string' },
         strict: { type: 'boolean' },
         ...valueAliasParseOptions,
       },
@@ -397,6 +406,19 @@ const applyCommandOption = (
     state.configPath = value;
     return;
   }
+  if (token.name === 'scope-exclude') {
+    if (value === undefined) {
+      state.diagnostics.push(
+        diagnostic({ message: '--scope-exclude requires a path glob.' })
+      );
+      return;
+    }
+    const existing = state.cli.scope?.exclude ?? [];
+    state.cli.scope = {
+      exclude: [...existing, ...splitCommaDelimitedValues(value)],
+    };
+    return;
+  }
   if (token.name === 'fix') {
     state.fix = true;
     return;
@@ -821,6 +843,7 @@ const buildRunOptions = ({
     lock: cli.lock,
     noLockMutation: cli.noLockMutation,
     rootDir,
+    scope: cli.scope,
     topos,
   }),
   env,

package/src/config.ts

@@ -10,6 +10,13 @@ export const wardenDraftsValues = ['include', 'exclude', 'only'] as const;
 
 const appNameSchema = z.string().min(1);
 
+const wardenScopeSchema = z
+  .object({
+    exclude: z.array(z.string().min(1)).default([]),
+  })
+  .strict()
+  .default({ exclude: [] });
+
 const wardenConfigObjectSchema = z
   .object({
     apps: z.array(appNameSchema).min(1).optional(),
@@ -18,6 +25,7 @@ const wardenConfigObjectSchema = z
     failOn: z.enum(wardenFailOnValues).default('error'),
     format: z.enum(wardenFormatValues).default('summary'),
     lock: z.enum(wardenLockValues).default('auto'),
+    scope: wardenScopeSchema,
   })
   .strict();
 
@@ -31,6 +39,7 @@ export type WardenDepth = (typeof wardenDepthValues)[number];
 export type WardenDraftsMode = (typeof wardenDraftsValues)[number];
 export type WardenFailOn = (typeof wardenFailOnValues)[number];
 export type WardenFormat = (typeof wardenFormatValues)[number];
+export type WardenScope = z.output<typeof wardenScopeSchema>;
 export type WardenLockMode = (typeof wardenLockValues)[number];
 
 export interface WardenConfigLayer extends Partial<WardenConfig> {

package/src/index.ts

@@ -18,6 +18,7 @@ export type {
   WardenFixCapability,
   WardenFixClass,
   WardenFixEdit,
+  WardenFixScanTargets,
   WardenFixSafety,
   WardenGuidance,
   WardenGuidanceLink,
@@ -100,6 +101,7 @@ export type {
   WardenDraftsMode,
   WardenFailOn,
   WardenFormat,
+  WardenScope,
   WardenLockMode,
   EffectiveWardenConfig,
   ResolveWardenConfigOptions,

package/src/project-context.ts

@@ -81,16 +81,42 @@ const exportAliasesForWorkspaces = (
   return aliases;
 };
 
+const resolveOptionsWithWorkspaceAliases = (
+  publicWorkspaces: ReadonlyMap<string, WardenPublicWorkspace> | undefined,
+  resolveOptions: WardenResolverOptions['resolveOptions'] | undefined
+): WardenResolverOptions['resolveOptions'] => {
+  if (!publicWorkspaces) {
+    return resolveOptions;
+  }
+
+  const workspaceAliases = exportAliasesForWorkspaces(publicWorkspaces);
+  return {
+    ...resolveOptions,
+    alias: {
+      ...workspaceAliases,
+      ...resolveOptions?.alias,
+    },
+  };
+};
+
 export const collectProjectImportResolutions = ({
+  publicWorkspaces,
   resolveOptions,
   rootDir,
   sourceFiles,
 }: {
+  readonly publicWorkspaces?: ReadonlyMap<string, WardenPublicWorkspace>;
   readonly resolveOptions?: WardenResolverOptions['resolveOptions'];
   readonly rootDir: string;
   readonly sourceFiles: readonly WardenProjectContextSourceFile[];
 }): ReadonlyMap<string, readonly WardenImportResolution[]> => {
-  const resolver = createWardenResolver({ resolveOptions, rootDir });
+  const resolver = createWardenResolver({
+    resolveOptions: resolveOptionsWithWorkspaceAliases(
+      publicWorkspaces,
+      resolveOptions
+    ),
+    rootDir,
+  });
   const resolutionsByFile = new Map<
     string,
     readonly WardenImportResolution[]
@@ -118,13 +144,16 @@ export const collectProjectImportResolutions = ({
 };
 
 export const collectProjectDocumentationImportResolutions = ({
+  publicWorkspaces: providedPublicWorkspaces,
   rootDir,
   sourceFiles,
 }: {
+  readonly publicWorkspaces?: ReadonlyMap<string, WardenPublicWorkspace>;
   readonly rootDir: string;
   readonly sourceFiles: readonly WardenProjectContextSourceFile[];
 }): ReadonlyMap<string, readonly WardenImportResolution[]> => {
-  const publicWorkspaces = collectPublicWorkspaces(rootDir);
+  const publicWorkspaces =
+    providedPublicWorkspaces ?? collectPublicWorkspaces(rootDir);
   const resolver = createWardenResolver({
     resolveOptions: { alias: exportAliasesForWorkspaces(publicWorkspaces) },
     rootDir,

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

@@ -77,6 +77,7 @@ export type {
   WardenFixCapability,
   WardenFixClass,
   WardenFixEdit,
+  WardenFixScanTargets,
   WardenFixSafety,
   WardenGuidance,
   WardenGuidanceLink,

package/src/rules/metadata.ts

@@ -610,7 +610,7 @@ const builtinWardenRuleMetadataInput = {
     guidance: {
       docs: [
         {
-          label: 'Surface Facets ADR',
+          label: 'Trailheads ADR',
           path: 'docs/adr/drafts/20260603-surface-facets-shape-dense-topos.md',
         },
       ],
@@ -620,10 +620,10 @@ const builtinWardenRuleMetadataInput = {
         'Record explicit visibility-widening acceptance and stable-description metadata when a facet 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': {

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-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/surface-facet-coherence.ts

@@ -356,7 +356,7 @@ export const surfaceFacetCoherence: WardenRule = {
     return diagnostics;
   },
   description:
-    'Coach surface facet maps away from selector overlap, hidden visibility widening, and drift-prone dynamic selectors.',
+    'Coach trailhead maps away from selector overlap, hidden visibility widening, and drift-prone dynamic selectors.',
   name: RULE_NAME,
   severity: 'warn',
 };

package/src/rules/trail-fork-coaching.ts

@@ -554,7 +554,7 @@ const diagnosticForField = (
     .map((option) => `"${option}"`)
     .join(
       ', '
-    )}). This may be a trail fork hidden as a surface accommodation. If branches change semantics (intent, permits, errors, outputs, lifecycle, or side effects) or structure (selected trail identity), split them into distinct trails, a composing trail, or a surface facet that preserves member identity.`,
+    )}). This may be a trail fork hidden as a surface accommodation. If branches change semantics (intent, permits, errors, outputs, lifecycle, or side effects) or structure (selected trail identity), split them into distinct trails, a composing trail, or a trailhead that preserves member identity.`,
   rule: RULE_NAME,
   severity: 'warn',
 });

package/src/rules/types.ts

@@ -1,4 +1,10 @@
-import type { Intent, Topo } from '@ontrails/core';
+import type {
+  DiagnosticSeverity,
+  Intent,
+  RuleDiagnosticBase,
+  ScanTargets,
+  Topo,
+} from '@ontrails/core';
 import type { TopoGraph } from '@ontrails/topographer';
 
 import type { WardenDepth } from '../config.js';
@@ -8,7 +14,7 @@ import type { WardenPublicWorkspace } from '../workspaces.js';
 /**
  * Severity level for warden diagnostics.
  */
-export type WardenSeverity = 'error' | 'warn';
+export type WardenSeverity = DiagnosticSeverity;
 
 /**
  * Execution tier for a Warden rule.
@@ -130,6 +136,21 @@ export interface WardenFixEdit {
   readonly replacement: string;
 }
 
+/**
+ * Source targets a fix class can inspect when projected into downstream tools.
+ *
+ * Warden itself decides which committed files it scans. This metadata is for
+ * consumers such as Regrade that need to derive a narrower collection before
+ * invoking the rule against an explicit downstream root.
+ */
+export type WardenFixScanTargets = ScanTargets & {
+  /**
+   * @deprecated Compatibility bridge for Warden-backed Regrade classes that
+   * predate PathScope. Prefer Regrade collection scope for new callers.
+   */
+  readonly ignoredDirectories?: readonly string[];
+};
+
 /**
  * Per-finding fix metadata attached to a diagnostic.
  *
@@ -164,6 +185,8 @@ export interface WardenFixCapability {
   readonly class: WardenFixClass;
   /** Default safety for fixes this rule emits. */
   readonly safety: WardenFixSafety;
+  /** Downstream scan targets for tools that project this fix capability. */
+  readonly scanTargets?: WardenFixScanTargets | undefined;
 }
 
 /**
@@ -191,7 +214,7 @@ export interface WardenRuleMetadata {
 /**
  * A single diagnostic reported by a warden rule.
  */
-export interface WardenDiagnostic {
+export interface WardenDiagnostic extends RuleDiagnosticBase {
   /** Rule identifier, e.g. "no-throw-in-implementation" */
   readonly rule: string;
   /** Optional rule-local diagnostic code for checks with multiple stable findings. */

package/src/trails/surface-facet-coherence.trail.ts

@@ -18,7 +18,7 @@ export const surfaceFacetCoherenceTrail = wrapRule({
   },
 };`,
       },
-      name: 'Reviewable surface facet map',
+      name: 'Reviewable trailhead map',
     },
   ],
   rule: surfaceFacetCoherence,

package/src/trails/trail-fork-coaching.trail.ts

@@ -10,7 +10,7 @@ export const trailForkCoachingTrail = wrapRule({
             filePath: 'users.ts',
             line: 9,
             message:
-              'Trail "users.manage" branches on input.action ("create", "delete"). This may be a trail fork hidden as a surface accommodation. If branches change semantics (intent, permits, errors, outputs, lifecycle, or side effects) or structure (selected trail identity), split them into distinct trails, a composing trail, or a surface facet that preserves member identity.',
+              'Trail "users.manage" branches on input.action ("create", "delete"). This may be a trail fork hidden as a surface accommodation. If branches change semantics (intent, permits, errors, outputs, lifecycle, or side effects) or structure (selected trail identity), split them into distinct trails, a composing trail, or a trailhead that preserves member identity.',
             rule: 'trail-fork-coaching',
             severity: 'warn',
           },

package/src/workspaces.ts

@@ -2,8 +2,10 @@
  * Workspace-manifest discovery for Warden project-aware rules.
  */
 
-import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+
+import { listWorkspacePackages, matchesAnyPathGlob } from '@ontrails/core';
 
 export interface WardenPublicWorkspace {
   readonly name: string;
@@ -15,8 +17,8 @@ export interface WardenPublicWorkspace {
   readonly files?: readonly string[] | undefined;
 }
 
-interface RootManifest {
-  readonly workspaces?: unknown;
+export interface WardenWorkspaceCollectionOptions {
+  readonly exclude?: readonly string[];
 }
 
 interface PackageManifest {
@@ -37,55 +39,12 @@ const normalizeRealPath = (path: string): string => {
   }
 };
 
+const rootRelativePath = (rootDir: string, path: string): string =>
+  normalizePath(relative(rootDir, path));
+
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   Boolean(value && typeof value === 'object' && !Array.isArray(value));
 
-const readJson = <T>(path: string): T | undefined => {
-  try {
-    return JSON.parse(readFileSync(path, 'utf8')) as T;
-  } catch {
-    return undefined;
-  }
-};
-
-const workspacePatternsFromManifest = (
-  manifest: RootManifest | undefined
-): readonly string[] => {
-  const { workspaces } = manifest ?? {};
-  if (Array.isArray(workspaces)) {
-    return workspaces.filter(
-      (pattern): pattern is string => typeof pattern === 'string'
-    );
-  }
-
-  const packages = isRecord(workspaces) ? workspaces['packages'] : undefined;
-  return Array.isArray(packages)
-    ? packages.filter(
-        (pattern): pattern is string => typeof pattern === 'string'
-      )
-    : [];
-};
-
-const workspaceDirsForPattern = (
-  rootDir: string,
-  pattern: string
-): readonly string[] => {
-  if (!pattern.endsWith('/*')) {
-    const workspaceDir = join(rootDir, pattern);
-    return existsSync(workspaceDir) ? [workspaceDir] : [];
-  }
-
-  const groupDir = join(rootDir, pattern.slice(0, -2));
-  if (!existsSync(groupDir)) {
-    return [];
-  }
-
-  return readdirSync(groupDir, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => join(groupDir, entry.name))
-    .toSorted();
-};
-
 const packageLocalName = (name: string): string =>
   name.split('/').at(-1) ?? name;
 
@@ -208,29 +167,31 @@ const publicWorkspaceFromManifest = (
 };
 
 export const collectPublicWorkspaces = (
-  rootDir: string
+  rootDir: string,
+  options: WardenWorkspaceCollectionOptions = {}
 ): ReadonlyMap<string, WardenPublicWorkspace> => {
   const normalizedRoot = normalizeRealPath(rootDir);
-  const rootManifest = readJson<RootManifest>(
-    join(normalizedRoot, 'package.json')
-  );
   const workspaces = new Map<string, WardenPublicWorkspace>();
 
-  for (const pattern of workspacePatternsFromManifest(rootManifest)) {
-    for (const workspaceDir of workspaceDirsForPattern(
-      normalizedRoot,
-      pattern
-    )) {
-      const packageJsonPath = join(workspaceDir, 'package.json');
-      const manifest = readJson<PackageManifest>(packageJsonPath);
-      if (!manifest) {
-        continue;
-      }
-
-      const workspace = publicWorkspaceFromManifest(packageJsonPath, manifest);
-      if (workspace) {
-        workspaces.set(workspace.name, workspace);
-      }
+  for (const workspacePackage of listWorkspacePackages<PackageManifest>(
+    normalizedRoot
+  )) {
+    const workspace = publicWorkspaceFromManifest(
+      workspacePackage.packageJsonPath,
+      workspacePackage.manifest
+    );
+    if (
+      workspace &&
+      !matchesAnyPathGlob(
+        rootRelativePath(normalizedRoot, workspace.rootDir),
+        options.exclude ?? []
+      ) &&
+      !matchesAnyPathGlob(
+        rootRelativePath(normalizedRoot, workspace.packageJsonPath),
+        options.exclude ?? []
+      )
+    ) {
+      workspaces.set(workspace.name, workspace);
     }
   }