@ontrails/trails 1.0.0-beta.45 → 1.0.0-beta.47

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # trails
 
+## 1.0.0-beta.47
+
+### Minor Changes
+
+- [`90d394c`](https://github.com/outfitter-dev/trails/commit/90d394c005fdf6b898ba7052d0b56755af0f4954): Derive nested worktree, repository, and submodule collection boundaries in the
+  shared Source walker. Regrade and Warden now observe one directly targeted
+  working tree per run, and Regrade audit summaries expose boundary skip counts.
+
+## 1.0.0-beta.46
+
+### Minor Changes
+
+- [`701ab85`](https://github.com/outfitter-dev/trails/commit/701ab85bd237e5fcf03725c56b70adb3612d6c15): Reuse fresh Regrade apply preflight evaluations without persisting cache state or weakening completion scans.
+- [`c83d0b6`](https://github.com/outfitter-dev/trails/commit/c83d0b67ac928af1b44c1f2d2c4b36aa09a24a70): Inventory parser-native source comments and TSDoc as exact review-only entries
+  for governed classified vocabulary transitions across CLI, MCP, and audit.
+- [`93757ba`](https://github.com/outfitter-dev/trails/commit/93757ba102ae7ba8d9a7a6c17f119cda47d342a7): Expose ordered Regrade lifecycle phases and wall-clock timings across CLI and
+  MCP completion results, with concise human CLI progress isolated on stderr.
+  Keep topo-scoped JSON and JSONL environment selectors effective when the
+  operator does not explicitly choose an output mode.
+- [`fb0ba0a`](https://github.com/outfitter-dev/trails/commit/fb0ba0ab706bbdce470123e9a6fb2ef9f1822806): Convert the eight committed governed Regrade histories to canonical v3 receipts and remove the temporary schema-v2 compatibility path after migration.
+- [`9a8b6e4`](https://github.com/outfitter-dev/trails/commit/9a8b6e4af394c76c11e6d0007e0f5f94d0be2cb3): Persist Regrade lifecycle runs as canonical v3 receipts with exact Git blob evidence and authored field provenance, and validate their compact classified-form projection independently in Warden.
+
+### Patch Changes
+
+- [`768cc79`](https://github.com/outfitter-dev/trails/commit/768cc79ca10947b8808b376e281e1a81131b4acc): Close missed projection vocabulary residue in Regrade internals and public
+  error-rendering guidance, and keep lifecycle-ambiguous governed identifiers in
+  the Warden review inventory instead of assigning them an unsafe automatic
+  target.
+
 ## 1.0.0-beta.45
 
 ### Patch Changes

package/README.md

@@ -18,7 +18,7 @@ Common workflows:
 - `trails wayfind`, `trails wayfind --trails --intent read`, `trails wayfind <id> --contract`, `trails wayfind <id> --deps`, `trails wayfind <id> --impact`, `trails wayfind pattern "wayfind.*"`, `trails wayfind query "release drift"`, and `trails wayfind diff ...` read graph artifacts through Wayfinder. `trails wayfind file <file> --outline` is the operator-owned live-source exception, assembled with `@ontrails/source` and enriched with saved graph context when available.
 - `trails schema <command...>` shows accepted CLI routes, aliases, flags, and schemas for an operator command or command namespace.
 - `trails warden` runs Trails governance checks for contract and architecture drift. Use `--scope-exclude <glob>` or project `warden.scope.exclude` config when local notes, scratch space, or generated state should not be governed by Warden.
-- `trails regrade plan <from> <to> --root-dir <path> --json` writes an active Regrade plan, `trails regrade plan --expand` stages wide-net review candidates in that plan, `trails regrade preview` reruns it without writing, and `trails regrade apply` consumes the plan and writes history. The minimal `from`/`to` seed is the primary workflow: planning deterministically derives morphology proposals, source-observed naming and public-identifier review candidates, review-only filename moves with reference-closure evidence, a namespace census, and current live-topo API preserves into the artifact's `derivation` section. Each derived item records provenance; uncertain forms and file moves remain review inventory until explicitly authored into the plan. A malformed or incompatible `trails.lock` fails planning instead of silently dropping live-API preserves. Use `plan --expand --dry-run` to inspect additional observed candidates without writing the active plan, and add `--dry-run` to `apply` to prove the apply path without mutating source. Use `trails regrade plans` and `trails regrade check` when a workspace has active plans that need inspection before apply. MCP exposes the same artifact and lifecycle as `trails_plan_regrade`, `trails_list_regrades`, `trails_check_regrade`, `trails_preview_regrade`, and `trails_apply_regrade`.
+- `trails regrade plan <from> <to> --root-dir <path> --json` writes an active Regrade plan, `trails regrade plan --expand` stages wide-net review candidates in that plan, `trails regrade preview` reruns it without writing, and `trails regrade apply` consumes the plan and writes history. The minimal `from`/`to` seed is the primary workflow: planning deterministically derives morphology proposals, source-observed naming and public-identifier review candidates, review-only filename moves with reference-closure evidence, a namespace census, and current live-topo API preserves into the artifact's `derivation` section. Each derived item records provenance; uncertain forms and file moves remain review inventory until explicitly authored into the plan. A malformed or incompatible `trails.lock` fails planning instead of silently dropping live-API preserves. Use `plan --expand --dry-run` to inspect additional observed candidates without writing the active plan, and add `--dry-run` to `apply` to prove the apply path without mutating source. Use `trails regrade plans` and `trails regrade check` when a workspace has active plans that need inspection before apply. Human CLI runs stream concise phase progress to stderr; `--json` and `--jsonl` keep that channel quiet while returning phase names and timings in the structured result. MCP returns the same lifecycle facts from `trails_plan_regrade`, `trails_check_regrade`, `trails_preview_regrade`, `trails_apply_regrade`, and `trails_adjust_regrade` and forwards progress notifications when the caller supplies a progress token. Lifecycle timings describe the command invocation and are never persisted into plans or history receipts. Apply reuses its command-local preflight evaluation only when exact source bytes plus plan, policy, scope, lock, and tool identities still match. Any stale or unreadable fact fails closed; no prepared handle is written to disk or required for receipt regeneration, and the post-apply completion scan still runs independently.
 - `trails guide` remains available for compatibility; prefer `trails wayfind --source live --module <app-module>` or saved-artifact Wayfinder reads for agent navigation.
 
 Trails is contract-first: define trails once with typed input, Result output, examples, and meta; the framework derives CLI, MCP, HTTP, and future surfaces from the same contracts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/trails",
-  "version": "1.0.0-beta.45",
+  "version": "1.0.0-beta.47",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/outfitter-dev/trails.git",
@@ -32,25 +32,25 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
-    "@ontrails/adapter-kit": "^1.0.0-beta.45",
-    "@ontrails/cli": "^1.0.0-beta.45",
-    "@ontrails/commander": "^1.0.0-beta.45",
-    "@ontrails/config": "^1.0.0-beta.45",
-    "@ontrails/core": "^1.0.0-beta.45",
-    "@ontrails/http": "^1.0.0-beta.45",
-    "@ontrails/mcp": "^1.0.0-beta.45",
-    "@ontrails/observability": "^1.0.0-beta.45",
-    "@ontrails/permits": "^1.0.0-beta.45",
-    "@ontrails/regrade": "^1.0.0-beta.45",
-    "@ontrails/source": "^1.0.0-beta.45",
-    "@ontrails/topography": "^1.0.0-beta.45",
-    "@ontrails/warden": "^1.0.0-beta.45",
+    "@ontrails/adapter-kit": "^1.0.0-beta.47",
+    "@ontrails/cli": "^1.0.0-beta.47",
+    "@ontrails/commander": "^1.0.0-beta.47",
+    "@ontrails/config": "^1.0.0-beta.47",
+    "@ontrails/core": "^1.0.0-beta.47",
+    "@ontrails/http": "^1.0.0-beta.47",
+    "@ontrails/mcp": "^1.0.0-beta.47",
+    "@ontrails/observability": "^1.0.0-beta.47",
+    "@ontrails/permits": "^1.0.0-beta.47",
+    "@ontrails/regrade": "^1.0.0-beta.47",
+    "@ontrails/source": "^1.0.0-beta.47",
+    "@ontrails/topography": "^1.0.0-beta.47",
+    "@ontrails/warden": "^1.0.0-beta.47",
     "commander": "^14.0.3",
     "typescript": "^5.9.3",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/cloudflare": "^1.0.0-beta.45",
-    "@ontrails/testing": "^1.0.0-beta.45"
+    "@ontrails/cloudflare": "^1.0.0-beta.47",
+    "@ontrails/testing": "^1.0.0-beta.47"
   }
 }

package/src/cli.ts

@@ -18,6 +18,7 @@ import type {
 } from '@ontrails/cli';
 import { createProgram } from '@ontrails/commander';
 import type { CreateProgramOptions } from '@ontrails/commander';
+import { createTrailContext } from '@ontrails/core';
 import { resolvePermitFromBearerToken } from '@ontrails/permits';
 import { deriveTopoGraph } from '@ontrails/topography';
 
@@ -25,6 +26,7 @@ import { app, trailsCliIncludedTrails, trailsOverlays } from './app.js';
 import { resolveInputWithClack } from './clack.js';
 import { getRetiredTopoCommandDiagnostic } from './retired-topo-command.js';
 import { attachCompletionsInstallCommand } from './run-completions-install.js';
+import { usesStructuredCliOutput } from './run-regrade-progress.js';
 import { attachSchemaCommand } from './run-schema.js';
 import {
   applyAdapterCheckExitCode,
@@ -302,6 +304,17 @@ const runSurfaceOnce = async (): Promise<void> => {
   const session = maybeInstallTraceSession();
   try {
     const surfaceOptions = {
+      createContext: () =>
+        createTrailContext({
+          progress: (event) => {
+            if (
+              !usesStructuredCliOutput(process.argv, process.env) &&
+              event.message?.startsWith('Regrade:') === true
+            ) {
+              process.stderr.write(`${event.message}\n`);
+            }
+          },
+        }),
       description: 'Agent-native, contract-first TypeScript framework',
       include: trailsCliIncludedTrails,
       name: 'trails',

package/src/regrade/audit.ts

@@ -13,6 +13,7 @@ import {
   runVocabularyRegrade,
   vocabularyDispositionValues,
   vocabularyRegradePlanForInput,
+  vocabularyRegradeTransitionForInput,
 } from '@ontrails/regrade';
 import type { VocabularyRegradePlan } from '@ontrails/regrade';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
@@ -21,9 +22,21 @@ import { z } from 'zod';
 
 import { deriveLiveApiPreserveInventory } from './live-api-preserve.js';
 import {
-  regradePlanArtifactSchema,
-  rootRelativePath,
-} from './plan-artifact.js';
+  readRegradeHistoryArtifact,
+  regradeHistoryPathForPlan,
+} from './history.js';
+import { rootRelativePath } from './plan-artifact.js';
+
+const sourceCommentExtensions = [
+  '.cjs',
+  '.cts',
+  '.js',
+  '.jsx',
+  '.mjs',
+  '.mts',
+  '.ts',
+  '.tsx',
+] as const;
 
 export const regradeAuditInputSchema = z.object({
   failOnOpen: z
@@ -49,7 +62,7 @@ const regradeAuditTransitionSchema = z.object({
           z.enum(vocabularyDispositionValues),
           z.number().int().nonnegative()
         )
-        .describe('Current Markdown occurrence counts by classification'),
+        .describe('Current source occurrence counts by classification'),
       entries: regradeReportOutput.shape.entries
         .readonly()
         .describe('Actionable file-level residue details'),
@@ -57,13 +70,16 @@ const regradeAuditTransitionSchema = z.object({
         .number()
         .int()
         .nonnegative()
-        .describe('Total classified Markdown occurrences'),
+        .describe('Total classified current-source occurrences'),
       open: z
         .number()
         .int()
         .nonnegative()
-        .describe('Unresolved Markdown occurrences'),
+        .describe('Unresolved current-source occurrences'),
       scanned: z.number().int().nonnegative().describe('Files scanned'),
+      skippedByReason: z
+        .record(z.string(), z.number().int().nonnegative())
+        .describe('Collection skips grouped by machine-readable reason'),
       status: z.enum(['green', 'open']).describe('Transition audit status'),
     })
     .describe('Concise current-tree audit of the latest applied plan'),
@@ -87,11 +103,6 @@ export const regradeAuditOutputSchema = z.object({
     .describe('Applied vocabulary transitions audited against current source'),
 });
 
-const regradeAuditHistoryPlanSchema = z.object({
-  id: z.string().min(1),
-  runs: z.array(z.object({ plan: regradePlanArtifactSchema })).min(1),
-});
-
 export type RegradeAuditInput = z.output<typeof regradeAuditInputSchema>;
 export type RegradeAuditOutput = z.output<typeof regradeAuditOutputSchema>;
 
@@ -101,18 +112,36 @@ interface RegradeAuditCandidate {
   readonly transitionId: string;
 }
 
-const historyTransitionId = (rawHistory: unknown): string | undefined => {
+/**
+ * Read the governed transition id from legacy history or v3 embedded intent.
+ *
+ * @internal
+ */
+export const historyTransitionId = (
+  rawHistory: unknown
+): string | undefined => {
   if (!isPlainObject(rawHistory)) {
     return undefined;
   }
   const { id, runs } = rawHistory;
-  const latestRun = Array.isArray(runs) ? runs.at(-1) : undefined;
+  const historyRuns = Array.isArray(runs) ? runs : [];
+  const latestRun = historyRuns.at(-1);
   const planArtifact = isPlainObject(latestRun) ? latestRun['plan'] : undefined;
   const plan = isPlainObject(planArtifact) ? planArtifact['plan'] : undefined;
   const planId = isPlainObject(plan) ? plan['id'] : undefined;
   if (typeof planId === 'string') {
     return planId;
   }
+  for (const run of historyRuns.toReversed()) {
+    const intent = isPlainObject(run) ? run['intent'] : undefined;
+    const intentPlan = isPlainObject(intent) ? intent['plan'] : undefined;
+    const intentPlanId = isPlainObject(intentPlan)
+      ? intentPlan['id']
+      : undefined;
+    if (typeof intentPlanId === 'string') {
+      return intentPlanId;
+    }
+  }
   return typeof id === 'string' ? id : undefined;
 };
 
@@ -125,7 +154,9 @@ const selectedHistoryFileNamesFor = (
       ? []
       : [...selectedTransitionIds].flatMap((transitionId) => {
           const plan = registryPlansById.get(transitionId);
-          return plan === undefined ? [] : [`${plan.from}-to-${plan.to}.json`];
+          return plan === undefined
+            ? []
+            : [basename(regradeHistoryPathForPlan('.', plan))];
         })
   );
 
@@ -239,21 +270,17 @@ const readRegradeAuditCandidates = (
     ) {
       continue;
     }
-    const history = regradeAuditHistoryPlanSchema.safeParse(rawHistory);
-    if (!history.success) {
-      return Result.err(
-        new ValidationError('Invalid Regrade history audit plan.', {
-          context: { historyFile, issues: history.error.issues },
-        })
-      );
+    const history = readRegradeHistoryArtifact(historyFile);
+    if (history.isErr()) {
+      return history;
     }
-    const latestPlan = history.data.runs.at(-1)?.plan.plan as
+    const latestPlan = history.value.runs.at(-1)?.plan.plan as
       | VocabularyRegradePlan
       | undefined;
     if (latestPlan?.kind !== 'vocabulary') {
       continue;
     }
-    const transitionId = latestPlan.id ?? history.data.id;
+    const transitionId = latestPlan.id ?? history.value.id;
     if (
       selectedTransitionIds !== null &&
       !selectedTransitionIds.has(transitionId)
@@ -281,10 +308,35 @@ type VocabularyPolicyClassified = NonNullable<
   NonNullable<VocabularyRegradePlan['scope']>['policyClassified']
 >;
 
+/**
+ * Select full evidence for classified paths and comments elsewhere.
+ *
+ * @internal
+ */
+export const sourceKindForRegradeAuditPath = (
+  path: string,
+  policyClassified: VocabularyPolicyClassified | undefined
+): 'all' | 'comments' => {
+  const isPolicyClassified = policyClassified?.some((policy) =>
+    matchesAnyPathGlob(path, policy.paths)
+  );
+  return sourceCommentExtensions.includes(
+    extname(path) as (typeof sourceCommentExtensions)[number]
+  ) && !isPolicyClassified
+    ? 'comments'
+    : 'all';
+};
+
 export const projectPolicyClassifiedForMarkdownAudit = (
-  plan: VocabularyRegradePlan
-): VocabularyPolicyClassified | undefined =>
-  plan.scope?.policyClassified
+  plan: VocabularyRegradePlan,
+  includeCodeComments = false
+): VocabularyPolicyClassified | undefined => {
+  const auditedExtensions = new Set<string>([
+    '.md',
+    '.mdx',
+    ...(includeCodeComments ? sourceCommentExtensions : []),
+  ]);
+  return plan.scope?.policyClassified
     ?.map((policy) => ({
       ...policy,
       paths: policy.paths.filter(
@@ -297,18 +349,40 @@ export const projectPolicyClassifiedForMarkdownAudit = (
     }))
     .filter((policy) => policy.paths.length > 0)
     .map((policy) => {
-      const hasExplicitMarkdownPath = policy.paths.some((path) => {
+      const hasAuditablePath = policy.paths.some((path) => {
         const extension = extname(path);
-        return extension === '.md' || extension === '.mdx';
+        if (auditedExtensions.has(extension)) {
+          return true;
+        }
+        const terminalPattern = basename(path);
+        const trailingWildcards = terminalPattern.match(/[*?]+$/)?.[0];
+        const canSelectAuditedExtension =
+          extension === '' &&
+          trailingWildcards !== undefined &&
+          [...auditedExtensions].some(
+            (auditedExtension) =>
+              trailingWildcards.includes('*') ||
+              (trailingWildcards.length >= auditedExtension.length &&
+                (terminalPattern.length > trailingWildcards.length ||
+                  trailingWildcards.length > auditedExtension.length))
+          );
+        return (
+          includeCodeComments &&
+          (canSelectAuditedExtension ||
+            [...auditedExtensions].some((auditedExtension) =>
+              matchesAnyPathGlob(auditedExtension, [extension])
+            ))
+        );
       });
-      if (policy.expectMatches !== true || hasExplicitMarkdownPath) {
+      if (policy.expectMatches !== true || hasAuditablePath) {
         return policy;
       }
-      // A Markdown-only audit cannot prove evidence for extensionless source
-      // globs. Markdown evidence requirements must name .md/.mdx explicitly.
+      // An extension-filtered audit cannot prove evidence for a path whose
+      // authored pattern does not identify one of the audited file families.
       const { expectMatches: _, ...markdownPolicy } = policy;
       return markdownPolicy;
     });
+};
 
 export const projectExcludesForMarkdownAudit = (
   plan: VocabularyRegradePlan,
@@ -342,8 +416,12 @@ const runRegradeAuditCandidate = async (
   input: RegradeAuditInput,
   rootDir: string
 ): Promise<TrailsResult<RegradeAuditOutput['transitions'][number], Error>> => {
+  const includeCodeComments =
+    vocabularyRegradeTransitionForInput(candidate.plan.from, candidate.plan.to)
+      ?.target.kind === 'classified';
   const policyClassified = projectPolicyClassifiedForMarkdownAudit(
-    candidate.plan
+    candidate.plan,
+    includeCodeComments
   );
   const exclude = projectExcludesForMarkdownAudit(
     candidate.plan,
@@ -357,7 +435,11 @@ const runRegradeAuditCandidate = async (
     ...candidate.plan,
     scope: {
       ...candidate.plan.scope,
-      extensions: ['.md', '.mdx'],
+      extensions: [
+        '.md',
+        '.mdx',
+        ...(includeCodeComments ? sourceCommentExtensions : []),
+      ],
       ...(exclude === undefined ? {} : { exclude }),
       ...(include === undefined ? {} : { include }),
       ...(policyClassified === undefined ? {} : { policyClassified }),
@@ -378,6 +460,12 @@ const runRegradeAuditCandidate = async (
       ? {}
       : { preserveInventory: preserveResult.value }),
     root: rootDir,
+    ...(includeCodeComments
+      ? {
+          sourceKindForPath: (path: string) =>
+            sourceKindForRegradeAuditPath(path, policyClassified),
+        }
+      : {}),
   });
   if (reportResult.isErr()) {
     return reportResult;
@@ -404,6 +492,7 @@ const runRegradeAuditCandidate = async (
       occurrences: run.ledger.occurrences.length,
       open: run.report.open,
       scanned: reportResult.value.scanned,
+      skippedByReason: reportResult.value.skipsByReason,
       status: run.report.gate.status,
     },
     source: candidate.source,