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

package/CHANGELOG.md

@@ -1,5 +1,110 @@
 # @ontrails/warden
 
+## 1.0.0-beta.39
+
+### Patch Changes
+
+- [`f42ca6e`](https://github.com/outfitter-dev/trails/commit/f42ca6e40b29155acec446e5bf44e52e014466bd): Hard cutover: the CLI consumes `cli` bindings from the app-authored surfaces overlay. Scalar bindings behave identically to the removed cliAliases (parity-tested) — the binding name splits on `.` into a transparent synonym command path for exactly one trail. List bindings arrive as command groups: each expanded member trail gets a group-prefixed route that dispatches the member trail with its identity preserved, and a singleton list stays a group. Expansion is fail-fast boundary validation: a scalar binding resolving to zero or multiple trails, or a group with an empty member union, is a `ValidationError` naming the binding. `DeriveTopoGraphOptions.cliAliases`, the `cliAliases`/`trailsCliAliases` app-module export convention, and the per-kind compile lift are deleted; `deriveCliCommands`/`createProgram` take `overlays` instead of `aliases`, and both topo-graph derivation pipelines expand the same bindings through one shared helper so runtime CLI routes and lock routes come from one semantic. A leftover legacy export is now a Warden error (`no-legacy-cli-alias-export`) naming the `surfaceOverlay({ cli: { ... } })` rewrite.
+
+  This is a breaking API removal shipped under the lockstep beta patch convention (pre-1.0 hard-cutover posture, zero external adoption); the removed options have no deprecation window by design.
+
+- [`bafde1f`](https://github.com/outfitter-dev/trails/commit/bafde1fc8172abb8d8617f69a3c7a70667626d10): Fresh derivations now collect app-module overlays through the shared channel compile uses. `@ontrails/adapter-kit` exports `resolveTrailsOverlays()`, the one reader of an app module's `trailsOverlays` export; the compile-path fresh app lease and Warden's fresh topo loading both go through it, making per-namespace drift asymmetry structurally impossible. Warden drift checks (`checkDrift` now accepts derive options carrying overlays) and the topo-aware rule context graph derive with the same overlays the committed lock embeds, so rules like `surface-overlay-coherence` fire on standard runs. Stale drift results name the drifted overlay namespaces (`DriftResult.driftedOverlayNamespaces`) and point at `trails compile` as the remediation.
+- [`b077fb7`](https://github.com/outfitter-dev/trails/commit/b077fb7ba6d9724cac6f0e59bc3fec9aec28984c): Add the export-restructure Regrade class family (TRL-1210). `export-restructure:cli-aliases` inverts legacy `cliAliases`/`trailsCliAliases` exports into `surfaceOverlay({ cli })` bindings inside the module's `trailsOverlays` export — adding the `@ontrails/core` import, deleting the legacy export, and routing anything it cannot prove safe (computed keys, spreads, in-module `aliases:` references) to `needs-review` with the exact target shape named. `export-restructure:mcp-trailheads` projects call-site MCP trailhead maps into `surfaceOverlay({ mcp })` group bindings: it rewrites in place when the same module exports `trailsOverlays`, and otherwise emits a classified `needs-review` handoff naming the module-overlay target while the call-site map stays as the richer-metadata override-in-context. Warden's fix-class union grows to `'export-restructure' | 'term-rewrite'`, `no-legacy-cli-alias-export` now advertises the `export-restructure` class, and `loadWardenRegradeClasses` supersedes `loadWardenTermRewriteClasses` (still exported) as the full Warden-routed class loader. Class-mode Regrade also gains the full plan lifecycle: `trails regrade plan --type class --class-ids ...` writes a `.trails/regrade/<slug>.json` plan carrying class ids, scope, and intent, `regrade check` re-runs the dry run and gates on outstanding rewrites or review, and `regrade apply` applies and graduates the plan to `.trails/regrade/history/<slug>-<hash>.json` — the same plan → check → apply → history evidence trail vocabulary regrades already had, now available to structural transforms. The class family ships for downstream apps bridging the pre-1.0 gap, so pre-cutover alias exports and trailhead maps migrate mechanically instead of by hand.
+- [`81373bc`](https://github.com/outfitter-dev/trails/commit/81373bc5e980bb06d56fb06af4f0986f72e318c7): Wave-2 MCP cutover to the app-authored `surfaces` overlay. The overlay's `mcp` bindings are now the authored, lockable default for the MCP surface: a list binding derives one grouped trailhead tool (member selection in `{ trail, input }`, member identity preserved in `{ trail, output }`, deterministic derived description), and a scalar binding derives an additional tool synonym whose MCP-safe name is published verbatim and must expand to exactly one trail. `deriveMcpTools`/`createServer` accept the new `overlays` option; `@ontrails/core` gains `expandMcpSurfaceBindings` and `deriveMcpTrailheadDescription`.
+
+  The call-site `CreateServerOptions.trailheads` map survives as permanent override-in-context design, not a compatibility bridge: when both channels are present, the call-site map wins at runtime. Warden's new `trailhead-override-divergence` rule (warn) names both sides when a call-site map's binding names or member selectors diverge from the authored overlay default.
+
+  Topographer now derives `graph.trailheads` from the overlay's `mcp` list bindings in both `deriveTopoGraph` and the store-side graph build, so trailhead facts flow from compiled locks into Wayfinder reads for the first time. The never-wired `DeriveTopoGraphOptions.trailheads` option and the `TopoGraphTrailheadDeclaration`/`TopoGraphTrailheadTrailSelector` types are removed — a beta-window hard cutover of an option no caller could reach; author the equivalent `mcp` list binding in `surfaceOverlay({ mcp })` instead.
+
+- [`820b4ad`](https://github.com/outfitter-dev/trails/commit/820b4ad9c40ea383b3c489a05fe7e4b2328e324f): Add `surfaceOverlay` — the shared surface-naming schema (scalar binding = synonym, list binding = grouped entry, singleton list stays a group) with app-authored/adapter-derived overlay provenance enforced at collection and consumption, and the `surface-overlay-coherence` Warden rule. MCP tool-name derivation moves to `@ontrails/core` (`deriveMcpToolName`) so the surface and governance read one projection; `@ontrails/mcp`'s `deriveToolName` now delegates to it. The coherence rule activates on standard warden runs once fresh derivations collect app-module overlays through the shared compile channel (TRL-1209, next in this stack).
+- [`58db715`](https://github.com/outfitter-dev/trails/commit/58db715209442604fe58f5004fec37426c5969b1): `duplicate-public-contract` now includes contour anchoring in the normalized contract fingerprint, so factory CRUD trails derived against different contours (for example two tables' `delete` trails that both normalize to `{ id } → void` with the same intent) are no longer flagged as duplicates. Genuine duplicates — identical facts with the same or no contour anchoring — still warn, and the diagnostic message names contours among the shared facts.
+- [`7cd0576`](https://github.com/outfitter-dev/trails/commit/7cd0576db8bc421cfd441c126f884e425e2254af): `signal-graph-coaching` no longer flags store-derived table signals (`created`/`updated`/`removed`) that have no consumers. Store resources advertise those signals as available capability, so leaving them unconsumed is a legitimate steady state for store-backed apps. Non-store produced signals without consumers still warn, and dead-signal coaching (no producer and no consumer) is unchanged.
+- [`b9e82a3`](https://github.com/outfitter-dev/trails/commit/b9e82a33546356c93fbc302fb934a83f19f1c2c5): Webhook ingress v2 (TRL-1194, absorbing TRL-1174 and TRL-1175): store-verified, per-endpoint webhook ingress becomes framework-expressible. `webhook()` accepts dynamic path segments (`path: '/hooks/:endpoint'`) whose values are delivered as envelope fields, opt-in `rawBody: true` delivery (a non-JSON body is no longer a surface-level failure — the trail owns payload interpretation), an allowlisted `headers` list delivered lowercased, and `resources` that make `verify` resource-capable: the HTTP surface resolves the declared resources into a context for the verifier and releases them afterwards, so signature checks can reach stores holding per-endpoint secrets. Envelope-mode ingress responds 202 Accepted; classic static webhooks keep their exact-match, JSON-gated, 200 behavior. Core exports `parseWebhookPathParams`, `matchWebhookPath`, `webhookPathPatternsOverlap`, and `createResources`. The `webhook-route-collision` Warden rule now also flags dynamic patterns that overlap other webhook or derived routes, not just exact method/path duplicates.
+
+## 1.0.0-beta.38
+
+### Patch Changes
+
+- [`a105127`](https://github.com/outfitter-dev/trails/commit/a105127e5662ed9a6c245125f791fb0182da3f5e): Add the `@ontrails/cloudflare` adapter collection with its first two service subpaths. `@ontrails/cloudflare/workers` exports `createWorkersHandler`, a materializer producing the `{ fetch(request, env, ctx) }` Worker export on the shared HTTP fetch kernel, with an env bridge that re-resolves env-bound resources whenever a new Worker `env` arrives so no resource instance serves a request with a stale env. `@ontrails/cloudflare/kv` exports `cloudflareKv`, a resource definition wrapping a KV namespace binding (`get`/`put`/`delete`/`list` with TTL options) plus an in-memory `createMemoryKv` mock so `testAll` runs configuration-free.
+
+  `@ontrails/core` now guards the default trail context fields: `requestId` falls back to `crypto.randomUUID()` when the `Bun` global is absent, and `cwd`/`env` fall back to `'/'`/`{}` when `process` is absent, so trail execution works on runtimes like Cloudflare Workers.
+
+  `@ontrails/warden` registers the `@ontrails/cloudflare` public barrel in the repo-local `public-export-example-coverage` policy, requiring `@example` TSDoc coverage on `createWorkersHandler` and `cloudflareKv`.
+
+## 1.0.0-beta.37
+
+## 1.0.0-beta.36
+
+### Patch Changes
+
+- [`6e63e48`](https://github.com/outfitter-dev/trails/commit/6e63e483617b84cb6868d0c4d58d5b5a8d3b9ed2): Complete the v1 grouped surface-entry vocabulary cutover from facet to trailhead, including Regrade dogfood support for governed string literal renames and composed AST rewrite application.
+
+## 1.0.0-beta.35
+
+### Patch Changes
+
+- [`1f5659b`](https://github.com/outfitter-dev/trails/commit/1f5659bfe39568f7bbee0503ace8b6e562d3f899): Add the `duplicate-exported-symbol` Warden rule to warn when multiple first-party packages define the same exported symbol name.
+
+## 1.0.0-beta.34
+
+## 1.0.0-beta.33
+
+### Patch Changes
+
+- [`fc002d5`](https://github.com/outfitter-dev/trails/commit/fc002d5669f4303427e99f45f9998fd0b0172bdb): Add governed AST identifier rename helpers and Warden residue detection for
+  active vocabulary symbol transitions.
+- [`6ca0d8f`](https://github.com/outfitter-dev/trails/commit/6ca0d8f776801eee71ddd86cb88c198eaf5815fd): Add a typed governed-vocabulary transition registry that Warden owns and Regrade
+  can consume for migration planning.
+
+## 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
@@ -149,7 +171,7 @@ This is the same factory used internally to build all built-in rule trails.
 | --- | --- |
 | `runWarden(options?)` | Run all rules and drift checks, return a report |
 | `formatWardenReport(report)` | Human-readable report |
-| `checkDrift(rootDir, topo?)` | Check if the lock file matches the current topo |
+| `checkDrift(rootDir, topo?, options?)` | Check if the lock file matches the current topo; pass `{ overlays }` from the app module so the comparison graph carries the overlay content compile embeds. Stale results name `driftedOverlayNamespaces` when overlays diverge |
 | `wardenRules` | Registry of all built-in rules |
 | `builtinWardenRuleMetadata` | Tier, scope, lifecycle, and invariant metadata for built-in rules |
 | `getWardenRuleMetadata(ruleOrName)` | Resolve inline or built-in metadata for a Warden rule |

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.39",
   "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.39",
+    "@ontrails/cli": "^1.0.0-beta.39",
+    "@ontrails/config": "^1.0.0-beta.39",
+    "@ontrails/permits": "^1.0.0-beta.39",
+    "@ontrails/store": "^1.0.0-beta.39",
     "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.39"
   },
   "peerDependencies": {
-    "@ontrails/core": "^1.0.0-beta.30",
-    "@ontrails/topographer": "^1.0.0-beta.30"
+    "@ontrails/core": "^1.0.0-beta.39",
+    "@ontrails/topographer": "^1.0.0-beta.39"
   }
 }

package/src/cli.ts

@@ -8,10 +8,18 @@
 import { isAbsolute, relative, resolve } from 'node:path';
 
 import { resolveTrailsProjectRoot } from '@ontrails/config';
-import type { Topo } from '@ontrails/core';
+import {
+  getContourReferences,
+  matchesAnyPathGlob,
+  resolveSurfaceOverlayBindings,
+  surfaceBindingsFromLockOverlays,
+} from '@ontrails/core';
+import type { SurfaceBindings, Topo } from '@ontrails/core';
 import { deriveTopoGraph } from '@ontrails/topographer';
-import type { TopoGraph } from '@ontrails/topographer';
-import { getContourReferences } from '@ontrails/core';
+import type {
+  TopoGraph,
+  TopoGraphOverlayRegistration,
+} from '@ontrails/topographer';
 
 import type {
   EffectiveWardenConfig,
@@ -20,6 +28,7 @@ import type {
   WardenDepth,
   WardenFailOn,
   WardenFormat,
+  WardenScope,
   WardenLockMode,
 } from './config.js';
 import { runWardenAdapterChecks } from './adapter-check.js';
@@ -27,11 +36,12 @@ import { resolveWardenConfig } from './config.js';
 import { isDraftMarkedFile } from './draft.js';
 import { applySafeFixesToSource, hasSafeFixEdits } from './fix.js';
 import type { DriftResult } from './drift.js';
-import { checkDrift } from './drift.js';
+import { checkDrift, staleDriftMessage } from './drift.js';
 import { loadProjectWardenRules } from './project-rules.js';
 import type { ProjectWardenRules } from './project-rules.js';
 import {
   collectProjectDocumentationImportResolutions,
+  collectProjectExportedSymbolDefinitions,
   collectProjectImportResolutions,
   collectPublicWorkspaces,
 } from './project-context.js';
@@ -56,10 +66,12 @@ import {
   isWardenSourceScanTarget,
 } from './rules/scan.js';
 import type {
+  AuthoredMcpSurfaceBindingSet,
   ProjectAwareWardenRule,
   ProjectContext,
   TopoAwareWardenRule,
   WardenDiagnostic,
+  WardenExportedSymbolDefinition,
   WardenGuidanceLink,
   WardenRule,
   WardenRuleTier,
@@ -74,6 +86,12 @@ export interface WardenTopoTarget {
   readonly graph?: TopoGraph | undefined;
   /** Stable app/topo label used to tag topo-aware diagnostics. */
   readonly name?: string | undefined;
+  /**
+   * App-module overlay registrations collected through the shared
+   * `resolveTrailsOverlays` channel, so fresh drift and topo-aware rule
+   * derivations carry the same overlays the committed lock embeds.
+   */
+  readonly overlays?: readonly TopoGraphOverlayRegistration[] | undefined;
   /** Resolved topo module to inspect. */
   readonly topo: Topo;
 }
@@ -105,6 +123,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 +280,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>;
@@ -328,6 +371,9 @@ interface SourceFile {
 }
 
 interface MutableProjectContext {
+  authoredMcpSurfaceBindingSets:
+    | readonly AuthoredMcpSurfaceBindingSet[]
+    | undefined;
   contourReferencesByName: Map<string, Set<string>>;
   crudTableIds: Set<string>;
   composeTargetTrailIds: Set<string>;
@@ -338,6 +384,10 @@ interface MutableProjectContext {
   knownTrailIds: Set<string>;
   topoTrailIds: Set<string>;
   importResolutionsByFile: Map<string, readonly WardenImportResolution[]>;
+  exportedSymbolDefinitionsByName: Map<
+    string,
+    readonly WardenExportedSymbolDefinition[]
+  >;
   documentedImportResolutionsByFile: Map<
     string,
     readonly WardenImportResolution[]
@@ -349,6 +399,7 @@ interface MutableProjectContext {
 }
 
 const createMutableProjectContext = (): MutableProjectContext => ({
+  authoredMcpSurfaceBindingSets: undefined,
   composeTargetTrailIds: new Set<string>(),
   contourReferencesByName: new Map<string, Set<string>>(),
   crudCoverageByEntity: new Map<string, Set<string>>(),
@@ -357,6 +408,7 @@ const createMutableProjectContext = (): MutableProjectContext => ({
     string,
     readonly WardenImportResolution[]
   >(),
+  exportedSymbolDefinitionsByName: new Map(),
   importResolutionsByFile: new Map<string, readonly WardenImportResolution[]>(),
   knownContourIds: new Set<string>(),
   knownResourceIds: new Set<string>(),
@@ -386,6 +438,9 @@ const addContourReferenceTargets = (
 };
 
 const toProjectContext = (context: MutableProjectContext): ProjectContext => ({
+  ...(context.authoredMcpSurfaceBindingSets === undefined
+    ? {}
+    : { authoredMcpSurfaceBindingSets: context.authoredMcpSurfaceBindingSets }),
   ...(context.contourReferencesByName.size > 0
     ? {
         contourReferencesByName: new Map(
@@ -427,6 +482,12 @@ const toProjectContext = (context: MutableProjectContext): ProjectContext => ({
           context.documentedImportResolutionsByFile,
       }
     : {}),
+  ...(context.exportedSymbolDefinitionsByName.size > 0
+    ? {
+        exportedSymbolDefinitionsByName:
+          context.exportedSymbolDefinitionsByName,
+      }
+    : {}),
   ...(context.onTargetSignalIds.size > 0
     ? { onTargetSignalIds: context.onTargetSignalIds }
     : {}),
@@ -799,6 +860,7 @@ const collectFileImportResolutions = (
   context: MutableProjectContext
 ): void => {
   const resolutionsByFile = collectProjectImportResolutions({
+    publicWorkspaces: context.publicWorkspaces,
     rootDir,
     sourceFiles,
   });
@@ -813,6 +875,7 @@ const collectFileDocumentedImportResolutions = (
   context: MutableProjectContext
 ): void => {
   const resolutionsByFile = collectProjectDocumentationImportResolutions({
+    publicWorkspaces: context.publicWorkspaces,
     rootDir,
     sourceFiles,
   });
@@ -821,19 +884,78 @@ const collectFileDocumentedImportResolutions = (
   }
 };
 
+const collectFileExportedSymbolDefinitions = (
+  rootDir: string,
+  sourceFiles: readonly SourceFile[],
+  context: MutableProjectContext
+): void => {
+  const definitionsByName = collectProjectExportedSymbolDefinitions({
+    publicWorkspaces: context.publicWorkspaces,
+    rootDir,
+    sourceFiles,
+  });
+  for (const [name, definitions] of definitionsByName) {
+    context.exportedSymbolDefinitionsByName.set(name, definitions);
+  }
+};
+
+/**
+ * Resolve per-app authored `mcp` surface bindings across the run's topo
+ * targets, so project-aware source rules can compare call-site surface
+ * options against the authored default of the app they belong to.
+ *
+ * Prefers the serialized graph overlays when a target carries a precomputed
+ * graph; otherwise reads the app-module overlay registrations. Invalid
+ * overlays are skipped here — `surface-overlay-coherence` reports them on
+ * the topo-aware path.
+ */
+const collectAuthoredMcpSurfaceBindingSets = (
+  topoTargets: readonly WardenTopoTarget[]
+): readonly AuthoredMcpSurfaceBindingSet[] | undefined => {
+  const sets: AuthoredMcpSurfaceBindingSet[] = [];
+  for (const target of topoTargets) {
+    let bindings: SurfaceBindings | undefined;
+    try {
+      const graphOverlays = target.graph?.overlays;
+      bindings =
+        graphOverlays === undefined
+          ? resolveSurfaceOverlayBindings(target.overlays)?.mcp
+          : surfaceBindingsFromLockOverlays(graphOverlays)?.mcp;
+    } catch {
+      continue;
+    }
+    if (bindings === undefined) {
+      continue;
+    }
+    sets.push({
+      appName: target.name ?? target.topo.name,
+      bindings,
+      trailIds: [...target.topo.trails.keys()],
+    });
+  }
+  return sets.length > 0 ? sets : undefined;
+};
+
 const buildProjectContext = (
   sourceFiles: readonly SourceFile[],
   rootDir: string,
-  appTopos: readonly Topo[] = []
+  appTopos: readonly Topo[] = [],
+  scope: WardenScope = EMPTY_WARDEN_SCOPE,
+  authoredMcpSurfaceBindingSets:
+    | readonly AuthoredMcpSurfaceBindingSet[]
+    | undefined = undefined
 ): ProjectContext => {
   const context = createMutableProjectContext();
+  context.authoredMcpSurfaceBindingSets = authoredMcpSurfaceBindingSets;
   const typeScriptSourceFiles = sourceFiles.filter(
     (sourceFile) => sourceFile.kind === 'typescript'
   );
   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) {
@@ -857,6 +979,7 @@ const buildProjectContext = (
     documentationSourceFiles,
     context
   );
+  collectFileExportedSymbolDefinitions(rootDir, typeScriptSourceFiles, context);
 
   return toProjectContext(context);
 };
@@ -1015,6 +1138,7 @@ const topoRuleFailureDiagnostic = (
 const lintTopo = async (
   appTopo: Topo,
   graph: TopoGraph | undefined,
+  overlays: readonly TopoGraphOverlayRegistration[] | undefined,
   extraTopoRules: readonly TopoAwareWardenRule[],
   selector: WardenRuleSelector
 ): Promise<readonly WardenDiagnostic[]> => {
@@ -1025,7 +1149,7 @@ const lintTopo = async (
   ].filter((rule) => isSelectedTopoRule(rule, selector));
   let contextGraph: TopoGraph;
   try {
-    contextGraph = graph ?? deriveTopoGraph(appTopo);
+    contextGraph = graph ?? deriveTopoGraph(appTopo, { overlays });
   } catch (error) {
     for (const rule of rules) {
       diagnostics.push(topoRuleFailureDiagnostic(rule, error));
@@ -1110,6 +1234,7 @@ const lintTopoTargets = async (
     const topoDiagnostics = await lintTopo(
       target.topo,
       target.graph,
+      target.overlays,
       extraTopoRules,
       selector
     );
@@ -1145,6 +1270,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 +1285,17 @@ 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,
+    collectAuthoredMcpSurfaceBindingSets(topoTargets)
   );
   const allDiagnostics: WardenDiagnostic[] = [
     ...lintSourceFiles(sourceFiles, context, extraSourceRules, selector),
@@ -1244,11 +1373,18 @@ const checkDriftForTopoTargets = async (
   topoTargets: readonly WardenTopoTarget[]
 ): Promise<DriftResult> => {
   if (topoTargets.length <= 1) {
-    return checkDrift(rootDir, topoTargets[0]?.topo);
+    const [target] = topoTargets;
+    return checkDrift(
+      rootDir,
+      target?.topo,
+      target === undefined ? undefined : { overlays: target.overlays }
+    );
   }
 
   const driftResults = await Promise.all(
-    topoTargets.map((target) => checkDrift(rootDir, target.topo))
+    topoTargets.map((target) =>
+      checkDrift(rootDir, target.topo, { overlays: target.overlays })
+    )
   );
   const committedHashes = new Set(
     driftResults.map((result) => result.committedHash)
@@ -1282,9 +1418,17 @@ const checkDriftForTopoTargets = async (
   }
 
   const currentHash = aggregateDriftHash(topoTargets, driftResults);
+  const driftedOverlayNamespaces = [
+    ...new Set(
+      driftResults.flatMap((result) => result.driftedOverlayNamespaces ?? [])
+    ),
+  ].toSorted();
   return {
     committedHash,
     currentHash,
+    ...(driftedOverlayNamespaces.length === 0
+      ? {}
+      : { driftedOverlayNamespaces }),
     stale: committedHash !== null && committedHash !== currentHash,
   };
 };
@@ -1339,6 +1483,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 +1621,7 @@ export const runWarden = async (
     ? await lintFiles(
         rootDir,
         effectiveConfig.drafts,
+        effectiveConfig.scope,
         topoTargets,
         [...projectRules.topoRules, ...(options.extraTopoRules ?? [])],
         [...projectRules.sourceRules, ...(options.extraSourceRules ?? [])],
@@ -1602,7 +1748,7 @@ const formatDriftSection = (drift: DriftResult | null): string[] => {
     return [`Drift: blocked (${drift.blockedReason})`, ''];
   }
   const label = drift.stale
-    ? 'Drift: trails.lock is stale (regenerate with `trails compile`)'
+    ? `Drift: ${staleDriftMessage(drift)}`
     : 'Drift: clean';
   return [label, ''];
 };