@ontrails/warden 1.0.0-beta.23 → 1.0.0-beta.29

package/CHANGELOG.md

@@ -1,5 +1,118 @@
 # @ontrails/warden
 
+## 1.0.0-beta.29
+
+### Patch Changes
+
+- @ontrails/adapter-kit@1.0.0-beta.29
+- @ontrails/cli@1.0.0-beta.29
+- @ontrails/config@1.0.0-beta.29
+- @ontrails/core@1.0.0-beta.29
+- @ontrails/permits@1.0.0-beta.29
+- @ontrails/store@1.0.0-beta.29
+- @ontrails/topographer@1.0.0-beta.29
+
+## 1.0.0-beta.28
+
+### Patch Changes
+
+- @ontrails/adapter-kit@1.0.0-beta.28
+- @ontrails/cli@1.0.0-beta.28
+- @ontrails/config@1.0.0-beta.28
+- @ontrails/core@1.0.0-beta.28
+- @ontrails/permits@1.0.0-beta.28
+- @ontrails/store@1.0.0-beta.28
+- @ontrails/topographer@1.0.0-beta.28
+
+## 1.0.0-beta.27
+
+### Patch Changes
+
+- @ontrails/adapter-kit@1.0.0-beta.27
+- @ontrails/cli@1.0.0-beta.27
+- @ontrails/config@1.0.0-beta.27
+- @ontrails/core@1.0.0-beta.27
+- @ontrails/permits@1.0.0-beta.27
+- @ontrails/store@1.0.0-beta.27
+- @ontrails/topographer@1.0.0-beta.27
+
+## 1.0.0-beta.26
+
+### Patch Changes
+
+- 1307568: Centralize Trails config module path conventions, move local config overrides to root `trails.config.local.*`, scaffold the matching gitignore entries, and load project-local Warden rules from `.trails/rules.ts` or `.trails/rules/`.
+- ef09e46: Add shared Trails project-root discovery helpers and use them in Warden so nested
+  cwd invocations still load root `trails.config.*` and project-local
+  `.trails/rules*` governance.
+- 38cd9d6: Add a shared Trails config file loader that treats `trails.config.ts` as the natural primary while supporting JSON, JSONC, YAML, and TOML peer formats. Release and Warden config loading now consume the same loader and local overrides can be authored as data files.
+- f8403c4: Collapse normal topo compilation onto one root `trails.lock` envelope that embeds the TopoGraph, hash, and summary while keeping legacy `.trails/trails.lock` plus `.trails/topo.lock` readers for migration compatibility.
+- ff48e41: Harden project-local rule loading: Warden now discovers `.trails/rules.ts` and direct `.trails/rules/*.ts` files only, reports duplicate project-local rule ids, and emits a migration diagnostic for the retired `trails/warden/rules` location.
+- Updated dependencies [1307568]
+- Updated dependencies [ef09e46]
+- Updated dependencies [38cd9d6]
+- Updated dependencies [f8403c4]
+- Updated dependencies [371d19e]
+  - @ontrails/config@1.0.0-beta.26
+  - @ontrails/core@1.0.0-beta.26
+  - @ontrails/topographer@1.0.0-beta.26
+  - @ontrails/adapter-kit@1.0.0-beta.26
+  - @ontrails/cli@1.0.0-beta.26
+  - @ontrails/permits@1.0.0-beta.26
+  - @ontrails/store@1.0.0-beta.26
+
+## 1.0.0-beta.25
+
+### Patch Changes
+
+- a9fdbc7: Clarify surface accommodation doctrine in MCP surface facet metadata and Warden trail-fork coaching guidance.
+- f8fd6ca: Add OXC Walker-backed AST facade helpers for parent-aware traversal, scope-aware traversal, source locations, and safe source edits.
+- 0fcc42b: Add `dead-public-trail` and `duplicate-public-contract` Warden coaching rules so exported public trails stay anchored and duplicate surface contracts become visible drift.
+- c36aca9: Preserve existing Result error boundaries directly and widen Warden pass-through
+  coaching beyond trail blazes.
+- f556559: Adds curated typed AST node guards to the public `@ontrails/warden/ast` helper
+  surface so source consumers can narrow common OXC node shapes without assertion
+  casts.
+- 6250729: Expands the public AST guard/accessor surface and migrates Warden/Regrade AST
+  consumers onto the typed helpers instead of rule-local node-field casts.
+- d73c38e: Warn when Warden rules add raw AST node-field casts where a typed accessor exists.
+- a8e4dc3: Clean up the Wayfinder navigation grammar before RC, including explicit pattern/query/file selectors, target-bound dependency and impact flags, drift-first provenance fields, stricter fires declaration diagnostics, and updated operator dogfood coverage.
+- a4f9cf6: Reserve the `shift` error category and `WorkspaceShiftError` before the stable
+  cutover so surface mappings can distinguish moved-workspace retry verdicts.
+  Update Warden's error-mapping completeness examples to cover the reserved
+  category.
+- 00c0cf8: Add Warden governance for CLI command route and alias coherence.
+- b313c58: Add library projection coherence governance so Warden reports generated library export collisions and stale projection targets before packages materialize.
+- f245fa0: Add advisory trail-fork coaching so Warden can warn when a trail may be hiding
+  several capabilities behind one branching action or operation input.
+- f1e6efa: Recognize module-local helper functions that receive the trail context when checking declared compose usage.
+- caff950: `implementation-returns-result` now recognizes conditional returns whose branches are all recognized Result expressions — both `return cond ? Result.err(...) : Result.ok(...)` statements (including branches that are Result helpers or Result-bound variables) and concise ternary blaze bodies. Previously the idiomatic two-branch ternary was flagged as an error.
+- df13faf: Tighten Wayfinder navigation review findings: carry adapter filters into included adapter facts, keep live-source outline off the operator MCP surface until host-root binding exists, make unknown MCP resources protocol errors, route secondary Wayfinder graph populations through unified flags, and keep undeclared string `ctx.compose()` calls as Warden errors.
+- Updated dependencies [c36aca9]
+- Updated dependencies [3befcf1]
+- Updated dependencies [f1e6efa]
+- Updated dependencies [a4f9cf6]
+- Updated dependencies [9bcf34e]
+- Updated dependencies [f7d97fc]
+- Updated dependencies [59d10da]
+- Updated dependencies [d9c6e50]
+  - @ontrails/core@1.0.0-beta.25
+  - @ontrails/topographer@1.0.0-beta.25
+  - @ontrails/cli@1.0.0-beta.25
+  - @ontrails/adapter-kit@1.0.0-beta.25
+  - @ontrails/permits@1.0.0-beta.25
+  - @ontrails/store@1.0.0-beta.25
+
+## 1.0.0-beta.24
+
+### Patch Changes
+
+- @ontrails/adapter-kit@1.0.0-beta.24
+- @ontrails/cli@1.0.0-beta.24
+- @ontrails/core@1.0.0-beta.24
+- @ontrails/permits@1.0.0-beta.24
+- @ontrails/store@1.0.0-beta.24
+- @ontrails/topographer@1.0.0-beta.24
+
 ## 1.0.0-beta.23
 
 ### Patch Changes

package/README.md

@@ -37,6 +37,39 @@ Rules cover several families:
 
 When adding or auditing rules, follow [Warden Rules](../../docs/contributing/warden-rules.md): name the invariant, import owner-held framework data, choose the narrowest Warden tier, and collapse families only when the data model, traversal, and diagnostic shape are shared.
 
+## Project-local rules
+
+Projects can carry local Warden rules in `.trails/rules.ts` or direct `.trails/rules/*.ts` files. `runWarden()` and `trails warden` load those files by default for lint runs, then run those rules alongside the built-in registries. Drift-only runs do not import project-local rule modules. Embedders that need only built-in or explicitly provided rules can pass `projectRules: false`.
+
+Warden does not recursively discover nested `.trails/rules` files. Use nested files as private helpers and re-export from a direct entrypoint when a local rule grows. Rule ids must be unique across every project-local module. The retired `trails/warden/rules` location reports a migration diagnostic instead of loading.
+
+Warden uses the shared Trails project-root resolver when a caller does not pass `rootDir` or `--root-dir`, so commands launched from nested directories still load the nearest root `trails.config.*` and its `.trails/rules*` files. An explicit root always wins over discovery.
+
+This is the right home for repo-specific migration checks or governance that has not earned a place in `@ontrails/warden` itself.
+
+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
+export const rule = {
+  name: 'local-contract-check',
+  severity: 'error',
+  description: 'Local contract examples keep their migration marker.',
+  check(sourceCode, filePath) {
+    return sourceCode.includes('deprecatedMarker')
+      ? [
+          {
+            filePath,
+            line: 1,
+            message: 'Replace deprecatedMarker before release.',
+            rule: 'local-contract-check',
+            severity: 'error',
+          },
+        ]
+      : [];
+  },
+};
+```
+
 ## Drift detection
 
 Warden integrates with `@ontrails/topographer` to detect when the topo has changed without updating the lock file:
@@ -124,12 +157,13 @@ This is the same factory used internally to build all built-in rule trails.
 | `wardenTopo` | `Topo` of all built-in rule trails (one per rule) |
 | `runWardenTrails(filePath, sourceCode, options?)` | Dispatch file-scoped rule trails for a file, collect diagnostics |
 | `runTopoAwareWardenTrails(topo)` | Dispatch built-in topo-aware rule trails once for a resolved topo |
+| `loadProjectWardenRules(rootDir)` | Load rule modules from `.trails/rules.ts` or direct `.trails/rules/*.ts` children |
 | `formatGitHubAnnotations(report)` | GitHub Actions annotation format |
 | `formatJson(report)` | Machine-readable JSON |
 | `formatSummary(report)` | Compact summary line |
 | `wrapRule(rule)` | Wrap a custom rule as a trail (same factory used for all built-in rule trails) |
 
-AST parser helpers are exported from `@ontrails/warden/ast`, not the root runtime barrel. The stable authoring surface includes `parse`, `walk`, `walkScope`, `offsetToLine`, `findTrailDefinitions`, `findBlazeBodies`, `findContourDefinitions`, `isBlazeCall`, and string-literal helpers.
+AST parser helpers are exported from `@ontrails/warden/ast`, not the root runtime barrel. The stable authoring surface includes `parse`, `walk`, `walkScope`, `walkWithParents`, `walkWithScopeContext`, `offsetToLine`, `offsetToLineColumn`, source-edit helpers, `findTrailDefinitions`, `findBlazeBodies`, `findContourDefinitions`, `isBlazeCall`, and string-literal helpers.
 
 `runWarden({ tier })` can narrow a run to `source-static`, `project-static`, `topo-aware`, `drift`, or `advisory`. Omit `tier` for the default full run.
 

package/package.json

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

package/src/ast.ts

@@ -10,19 +10,128 @@ export {
   findContourDefinitions,
   findStringLiterals,
   findTrailDefinitions,
+  applySourceEdits,
+  createSourceEdit,
+  getNodeAlternate,
+  getNodeArgument,
+  getNodeArguments,
+  getNodeBody,
+  getNodeBodyNode,
+  getNodeBodyStatements,
+  getNodeCallee,
+  getNodeCases,
+  getNodeComputed,
+  getNodeConsequent,
+  getNodeDeclaration,
+  getNodeDeclarations,
+  getNodeDiscriminant,
+  getNodeElements,
+  getNodeExported,
+  getNodeExportKind,
+  getNodeExpression,
+  getNodeId,
+  getNodeImported,
+  getNodeInit,
+  getNodeKey,
+  getNodeKind,
+  getNodeLeft,
+  getNodeLocal,
+  getNodeName,
+  getNodeObject,
+  getNodeOperator,
+  getNodeParam,
+  getNodeParams,
+  getNodeProperties,
+  getNodeProperty,
+  getNodeReturnType,
+  getNodeRight,
+  getNodeSource,
+  getNodeSpecifiers,
+  getNodeSuperClass,
+  getNodeTest,
+  getNodeTypeAnnotation,
+  getNodeValue,
+  getNodeValueNode,
   getStringValue,
+  identifierName,
+  isArrayExpression,
+  isAssignmentPattern,
+  isAstNode,
+  isBinaryExpression,
+  isBlockStatement,
   isBlazeCall,
+  isCallExpression,
+  isClassMember,
+  isDeclarationWithId,
+  isExportAllDeclaration,
+  isExportDeclaration,
+  isExportDefaultDeclaration,
+  isExportNamedDeclaration,
+  isExportSpecifier,
+  isExpressionStatement,
+  isFunctionLike,
+  isIdentifier,
+  isImportDeclaration,
+  isImportSpecifier,
+  isMemberExpression,
+  isObjectExpression,
+  isProgram,
+  isProperty,
+  isRestElement,
+  isReturnStatement,
   isStringLiteral,
+  isUnaryExpression,
+  isVariableDeclaration,
+  isVariableDeclarator,
+  offsetToLineColumn,
   offsetToLine,
   parse,
+  parseWithDiagnostics,
+  validateSourceEdits,
   walk,
+  walkWithParents,
+  walkWithScopeContext,
   walkScope,
 } from './rules/ast.js';
 export type {
+  ArrayExpressionNode,
+  AssignmentPatternNode,
+  AstFieldProjection,
+  AstParentContext,
   AstNode,
+  AstParseDiagnostic,
+  AstParseDiagnosticLabel,
+  AstParseResult,
+  AstScopeContext,
+  AstScopeDeclaration,
+  BinaryExpressionNode,
+  BlockStatementNode,
+  CallExpressionNode,
+  ClassMemberNode,
   ContourDefinition,
+  CuratedAstNode,
+  DeclarationWithIdNode,
+  ExportDeclarationNode,
+  ExportSpecifierNode,
+  ExpressionStatementNode,
   FindContourDefinitionsOptions,
   FrameworkNamespaceContext,
+  FunctionLikeNode,
+  IdentifierNode,
+  ImportDeclarationNode,
+  ImportSpecifierNode,
+  MemberExpressionNode,
+  ObjectExpressionNode,
+  ProgramNode,
+  PropertyNode,
+  RestElementNode,
+  ReturnStatementNode,
+  SourceEdit,
+  SourceLocation,
   StringLiteralMatch,
+  StringLiteralNode,
   TrailDefinition,
+  UnaryExpressionNode,
+  VariableDeclarationNode,
+  VariableDeclaratorNode,
 } from './rules/ast.js';

package/src/cli.ts

@@ -7,6 +7,7 @@
 
 import { isAbsolute, relative, resolve } from 'node:path';
 
+import { resolveTrailsProjectRoot } from '@ontrails/config';
 import type { Topo } from '@ontrails/core';
 import { deriveTopoGraph } from '@ontrails/topographer';
 import type { TopoGraph } from '@ontrails/topographer';
@@ -27,16 +28,18 @@ import { isDraftMarkedFile } from './draft.js';
 import { applySafeFixesToSource, hasSafeFixEdits } from './fix.js';
 import type { DriftResult } from './drift.js';
 import { checkDrift } from './drift.js';
+import { loadProjectWardenRules } from './project-rules.js';
+import type { ProjectWardenRules } from './project-rules.js';
 import {
   collectProjectDocumentationImportResolutions,
   collectProjectImportResolutions,
   collectPublicWorkspaces,
 } from './project-context.js';
 import {
+  collectComposeTargetTrailIds,
   collectContourDefinitionIds,
   collectContourReferenceTargetsByName,
   collectCrudTableIds as collectCrudTableIdsFromAst,
-  collectComposeTargetTrailIds,
   collectOnTargetSignalIds as collectOnTargetSignalIdsFromAst,
   collectReconcileTableIds as collectReconcileTableIdsFromAst,
   collectResourceDefinitionIds,
@@ -119,6 +122,15 @@ export interface WardenRunOptions {
    * lint rule dispatch. `lintOnly` and `driftOnly` remain compatibility shims.
    */
   readonly tier?: WardenRuleTier | undefined;
+  /**
+   * Load project-local Warden rules from `.trails/rules.ts` or `.trails/rules/`.
+   *
+   * Enabled by default for normal runs so a Trails app can carry migration or
+   * repo-local governance with the project instead of shipping it from
+   * `@ontrails/warden`. Set to `false` for narrow tests or embedders that need
+   * only built-in and explicitly provided rules.
+   */
+  readonly projectRules?: boolean | undefined;
   /**
    * App topology for drift detection. When provided, enables real topology
    * drift comparison and unlocks the topo-aware rule dispatch path.
@@ -324,6 +336,7 @@ interface MutableProjectContext {
   knownResourceIds: Set<string>;
   knownSignalIds: Set<string>;
   knownTrailIds: Set<string>;
+  topoTrailIds: Set<string>;
   importResolutionsByFile: Map<string, readonly WardenImportResolution[]>;
   documentedImportResolutionsByFile: Map<
     string,
@@ -352,6 +365,7 @@ const createMutableProjectContext = (): MutableProjectContext => ({
   onTargetSignalIds: new Set<string>(),
   publicWorkspaces: new Map(),
   reconcileTableIds: new Set<string>(),
+  topoTrailIds: new Set<string>(),
   trailIntentsById: new Map<string, 'destroy' | 'read' | 'write'>(),
 });
 
@@ -401,6 +415,9 @@ const toProjectContext = (context: MutableProjectContext): ProjectContext => ({
   knownResourceIds: context.knownResourceIds,
   knownSignalIds: context.knownSignalIds,
   knownTrailIds: context.knownTrailIds,
+  ...(context.topoTrailIds.size > 0
+    ? { topoTrailIds: context.topoTrailIds }
+    : {}),
   ...(context.importResolutionsByFile.size > 0
     ? { importResolutionsByFile: context.importResolutionsByFile }
     : {}),
@@ -635,6 +652,7 @@ const collectTopoKnownIds = (
 
   for (const id of appTopo.trails.keys()) {
     context.knownTrailIds.add(id);
+    context.topoTrailIds.add(id);
   }
 
   for (const id of appTopo.resources.keys()) {
@@ -854,6 +872,23 @@ const createOptionsDiagnostic = (message: string): WardenDiagnostic => ({
   severity: 'error',
 });
 
+const emptyProjectWardenRules = (): ProjectWardenRules => ({
+  diagnostics: [],
+  sourceRules: [],
+  topoRules: [],
+});
+
+const loadProjectRulesForRun = async (
+  rootDir: string,
+  options: WardenRunOptions,
+  runLint: boolean
+): Promise<ProjectWardenRules> => {
+  if (!runLint || options.projectRules === false) {
+    return emptyProjectWardenRules();
+  }
+  return loadProjectWardenRules(rootDir);
+};
+
 interface WardenRuleSelector {
   readonly depth?: WardenDepth | undefined;
   readonly tier?: WardenRuleTier | undefined;
@@ -1411,7 +1446,10 @@ export const applySafeFixesToFiles = async (
 export const runWarden = async (
   options: WardenRunOptions = {}
 ): Promise<WardenReport> => {
-  const rootDir = resolve(options.rootDir ?? process.cwd());
+  const { rootDir } = resolveTrailsProjectRoot({
+    explicitRootDir: options.rootDir,
+    startDir: process.cwd(),
+  });
   const { diagnostics: configDiagnostics, effectiveConfig } =
     resolveWardenConfig({
       cli: buildCliConfigLayer(options),
@@ -1433,13 +1471,14 @@ export const runWarden = async (
   } satisfies WardenRuleSelector;
   const runLint = shouldRunLint(options);
   const runDrift = shouldRunDrift(options, effectiveConfig);
+  const projectRules = await loadProjectRulesForRun(rootDir, options, runLint);
   const lintResult = runLint
     ? await lintFiles(
         rootDir,
         effectiveConfig.drafts,
         topoTargets,
-        options.extraTopoRules ?? [],
-        options.extraSourceRules ?? [],
+        [...projectRules.topoRules, ...(options.extraTopoRules ?? [])],
+        [...projectRules.sourceRules, ...(options.extraSourceRules ?? [])],
         selector
       )
     : { diagnostics: [], sourceFiles: [] };
@@ -1447,6 +1486,7 @@ export const runWarden = async (
 
   const rawDiagnostics = [
     ...configDiagnostics,
+    ...projectRules.diagnostics,
     ...optionDiagnostics,
     ...lintResult.diagnostics,
     ...adapterDiagnostics,

package/src/command.ts

@@ -14,6 +14,10 @@ import type {
 } from '@ontrails/cli';
 import type { Topo } from '@ontrails/core';
 import { AmbiguousError, NotFoundError } from '@ontrails/core';
+import {
+  loadTrailsConfigValue,
+  resolveTrailsProjectRoot,
+} from '@ontrails/config';
 
 import type {
   WardenConfigInput,
@@ -57,13 +61,6 @@ interface MutableWardenConfigLayer {
   noLockMutation?: boolean | undefined;
 }
 
-const CONFIG_CANDIDATES = [
-  'trails.config.ts',
-  'trails.config.mts',
-  'trails.config.js',
-  'trails.config.mjs',
-] as const;
-
 const diagnostic = ({
   filePath = '<warden-cli>',
   message,
@@ -176,7 +173,7 @@ interface WardenValueAliasTarget {
   readonly configKey: AliasConfigKey;
 }
 
-const wardenAliasSpecs = [
+const wardenAliasSpecs: readonly WardenAliasSpec[] = [
   {
     aliases: true,
     choices: wardenFormatValues,
@@ -203,7 +200,7 @@ const wardenAliasSpecs = [
     configKey: 'drafts',
     flagName: 'drafts',
   },
-] satisfies readonly WardenAliasSpec[];
+];
 
 const wardenValueAliasTargets: readonly WardenValueAliasTarget[] =
   wardenAliasSpecs.flatMap((spec) =>
@@ -491,12 +488,7 @@ const findConfigPath = (
         };
   }
 
-  const candidate = CONFIG_CANDIDATES.map((entry) =>
-    resolve(rootDir, entry)
-  ).find((entry) => existsSync(entry));
-  return candidate === undefined
-    ? { diagnostics: [] }
-    : { configPath: candidate, diagnostics: [] };
+  return { diagnostics: [] };
 };
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -529,14 +521,6 @@ const extractWardenConfig = (value: unknown): WardenConfigInput | undefined =>
     ? (value['warden'] as WardenConfigInput)
     : undefined;
 
-const importConfigModule = async (
-  configPath: string
-): Promise<Record<string, unknown>> => {
-  const url = pathToFileURL(configPath);
-  url.searchParams.set('t', Date.now().toString());
-  return (await import(url.href)) as Record<string, unknown>;
-};
-
 export const loadWardenConfig = async ({
   configPath,
   env = {},
@@ -547,29 +531,32 @@ export const loadWardenConfig = async ({
   readonly rootDir: string;
 }): Promise<WardenConfigLoadResult> => {
   const located = findConfigPath(rootDir, configPath);
-  if (located.configPath === undefined) {
+  if (configPath !== undefined && located.configPath === undefined) {
     return located;
   }
 
   try {
-    const mod = await importConfigModule(located.configPath);
-    const exported = mod['default'] ?? mod;
+    const loaded = await loadTrailsConfigValue({ configPath, rootDir });
+    const exported = loaded.value;
+    if (exported === undefined) {
+      return located;
+    }
     if (isResolvableConfig(exported)) {
       const resolved = await exported.resolve({ cwd: rootDir, env });
       if (isResultLike(resolved)) {
         if (resolved.isOk()) {
           return {
             config: extractWardenConfig(resolved.value),
-            configPath: located.configPath,
+            configPath: loaded.configPath,
             diagnostics: located.diagnostics,
           };
         }
         return {
-          configPath: located.configPath,
+          configPath: loaded.configPath,
           diagnostics: [
             ...located.diagnostics,
             diagnostic({
-              filePath: located.configPath,
+              filePath: loaded.configPath ?? rootDir,
               message: `Failed to resolve Warden config: ${errorMessage(resolved.error)}`,
               rule: 'warden-config',
             }),
@@ -578,22 +565,22 @@ export const loadWardenConfig = async ({
       }
       return {
         config: extractWardenConfig(resolved),
-        configPath: located.configPath,
+        configPath: loaded.configPath,
         diagnostics: located.diagnostics,
       };
     }
     return {
       config: extractWardenConfig(exported),
-      configPath: located.configPath,
+      configPath: loaded.configPath,
       diagnostics: located.diagnostics,
     };
   } catch (error) {
     return {
-      configPath: located.configPath,
+      configPath: located.configPath ?? configPath,
       diagnostics: [
         ...located.diagnostics,
         diagnostic({
-          filePath: located.configPath,
+          filePath: located.configPath ?? rootDir,
           message: `Failed to load Warden config: ${errorMessage(error)}`,
           rule: 'warden-config',
         }),
@@ -906,7 +893,10 @@ export const runWardenCommand = async ({
   env = {},
 }: RunWardenCommandOptions): Promise<WardenCommandResult> => {
   const parsed = parseWardenCommandArgs(args);
-  const rootDir = resolve(cwd, parsed.rootDir ?? '.');
+  const { rootDir } = resolveTrailsProjectRoot({
+    explicitRootDir: parsed.rootDir,
+    startDir: cwd,
+  });
   const loadedConfig = await loadWardenConfig({
     configPath: parsed.configPath,
     env,

package/src/drift.ts

@@ -1,9 +1,9 @@
 /**
- * Topo lock drift detection.
+ * Trails lock drift detection.
  *
- * Compares the `topo.lock` artifact hash listed in `trails.lock` against a
- * freshly generated TopoGraph hash to detect when the trail topology has
- * changed without updating the artifact family.
+ * Compares the committed `trails.lock` TopoGraph hash against a freshly
+ * generated TopoGraph hash to detect when the trail topology changed without
+ * updating the committed resolved truth.
  */
 
 import { existsSync, statSync } from 'node:fs';
@@ -20,6 +20,7 @@ import {
   deriveTopoGraphHash,
   isTopoArtifactRegenerationError,
   readLockManifest,
+  readTrailsLock,
 } from '@ontrails/topographer';
 import type { LockManifest } from '@ontrails/topographer';
 
@@ -57,11 +58,26 @@ const blockedLockRead = (reason: string): BlockedLockRead => ({
 const readCommittedLockManifest = async (
   rootDir: string
 ): Promise<BlockedLockRead | LockManifest | null> => {
-  const trailsDir = deriveTrailsDir({ rootDir });
   try {
-    return existsSync(rootDir) && statSync(rootDir).isDirectory()
-      ? await readLockManifest({ dir: trailsDir })
-      : null;
+    if (!(existsSync(rootDir) && statSync(rootDir).isDirectory())) {
+      return null;
+    }
+    const rootLock = await readTrailsLock({ dir: rootDir });
+    if (rootLock !== null) {
+      return {
+        artifacts: [
+          {
+            path: 'topo.lock',
+            role: 'topo',
+            sha256: rootLock.topoGraphHash,
+          },
+        ],
+        scope: rootLock.scope,
+        summary: rootLock.summary,
+        version: 3,
+      };
+    }
+    return await readLockManifest({ dir: deriveTrailsDir({ rootDir }) });
   } catch (error) {
     if (isTopoArtifactRegenerationError(error)) {
       return blockedLockRead(error.message);