@llman-sdd/core 0.3.0 → 0.5.0

package/src/validation/changeCheck.ts

@@ -1,6 +1,13 @@
-import { readBinding } from '../change/frontmatter.ts';
+import { stageFor, walkActiveChangeDirs } from '../change/collect.ts';
+import {
+  extractFrontmatter,
+  readBinding,
+  readNeedsSpecsChange,
+  specsLanded,
+} from '../change/frontmatter.ts';
+import { CLOSE_OUT_TASK_HINT, closeOutTaskLines, parseTaskCheckboxes } from '../change/tasks.ts';
 /**
- * Change-domain validation (v1 `commands/validate.rs` change path parity):
+ * Change-domain validation (predecessor `commands/validate.rs` change path parity):
  * frontmatter/depends_on gates, design/tasks constraints, completeness stage
  * INFO, pattern gate and task gates. IO + git injected (pure).
  */
@@ -10,7 +17,7 @@ export type ChangeIssueLevel = 'ERROR' | 'WARNING' | 'INFO';
 
 export interface ChangeIssue {
   level: ChangeIssueLevel;
-  /** v1-style anchor (issue path), e.g. `proposal.md/frontmatter.depends_on`. */
+  /** predecessor-style anchor (issue path), e.g. `proposal.md/frontmatter.depends_on`. */
   path: string;
   message: string;
 }
@@ -25,7 +32,6 @@ export interface ChangeCheckInput {
 
 export interface ChangeCheckConfig {
   strict_defer?: boolean | null;
-  min_completion_ratio?: number | null;
   change_id_pattern?: string | null;
 }
 
@@ -38,6 +44,62 @@ export interface ChangeFsIoLite {
 
 export const STAGE_ORDER = ['draft', 'designed', 'planned', 'full'] as const;
 
+/**
+ * r73 dependency-reference resolution: `active` matches a leaf change dir by
+ * name (nested groups included — same caliber as the CLI change scan),
+ * `archived` matches an `archive/<YYYY-MM-DD>-<id>` dir OR a flat frozen card
+ * `archive/<YYYY-MM-DD>-<id>.yaml` exactly (a suffix like
+ * `2026-01-01-the-other` must NOT satisfy id `other`). A missing
+ * `archive/` dir reads as empty and never throws.
+ */
+function resolveChangeRef(
+  io: ChangeFsIoLite,
+  changesRoot: string,
+  id: string,
+): 'active' | 'archived' | 'unknown' {
+  let active = false;
+  walkActiveChangeDirs(io, changesRoot, (_dir, name) => {
+    if (name === id) active = true;
+  });
+  if (active) return 'active';
+  const archive = `${changesRoot}/archive`;
+  const entries = io.exists(archive) && io.isDirectory(archive) ? io.listDir(archive) : [];
+  // `YYYY-MM-DD-` is 11 chars; the remainder must equal the id exactly.
+  const archived = entries.some((name) => {
+    if (!/^\d{4}-\d{2}-\d{2}-/u.test(name)) return false;
+    const base = name.endsWith('.yaml') ? name.slice(0, -'.yaml'.length) : name;
+    return base.slice(11) === id;
+  });
+  return archived ? 'archived' : 'unknown';
+}
+
+/**
+ * r87: global change-id uniqueness gate. Enumerates active change ids (leaf
+ * dir names), archived dir ids and frozen-card ids, and returns every id that
+ * appears more than once across the whole set. This is the cheap, enumerable
+ * form of the uniqueness contract: frozen ids are no longer hidden inside the
+ * cold backup, so collisions are checkable without thawing.
+ */
+export function checkGlobalChangeIdUniqueness(io: ChangeFsIoLite, changesRoot: string): string[] {
+  const archive = `${changesRoot}/archive`;
+  const entries = io.exists(archive) && io.isDirectory(archive) ? io.listDir(archive) : [];
+  const counts = new Map<string, number>();
+  walkActiveChangeDirs(io, changesRoot, (_dir, name) => {
+    counts.set(name, (counts.get(name) ?? 0) + 1);
+  });
+  for (const name of entries) {
+    if (!/^\d{4}-\d{2}-\d{2}-/u.test(name)) continue;
+    const base = name.endsWith('.yaml') ? name.slice(0, -'.yaml'.length) : name;
+    const id = base.slice(11);
+    if (id === '') continue;
+    counts.set(id, (counts.get(id) ?? 0) + 1);
+  }
+  return [...counts]
+    .filter(([, n]) => n > 1)
+    .map(([id]) => id)
+    .toSorted((a, b) => a.localeCompare(b));
+}
+
 export type StageGate = (typeof STAGE_ORDER)[number];
 
 export interface ChangeCheckResult {
@@ -46,11 +108,14 @@ export interface ChangeCheckResult {
   issues: ChangeIssue[];
 }
 
-/** Legacy pure gate (r47 surface) — kept for existing callers/tests. */
+/**
+ * Legacy pure gate (r47 surface) — structural checks only (tasks, binding,
+ * pattern); the stage-ordinal branch was removed with the dual-caliber gate
+ * (the artifact-presence `--stage` gate lives in validateChange).
+ */
 export function checkChangeDoc(
   input: ChangeCheckInput,
   config: ChangeCheckConfig,
-  opts: { stage?: StageGate } = {},
 ): ChangeCheckResult {
   const issues: ChangeIssue[] = [];
   if (input.totalTasks > 0 && input.completedTasks < input.totalTasks) {
@@ -61,18 +126,6 @@ export function checkChangeDoc(
       message: `${pending} unchecked task(s) in tasks.md`,
     });
   }
-  if (
-    config.min_completion_ratio !== undefined &&
-    config.min_completion_ratio !== null &&
-    input.totalTasks > 0 &&
-    input.completedTasks / input.totalTasks < config.min_completion_ratio
-  ) {
-    issues.push({
-      level: 'ERROR',
-      path: 'tasks.md',
-      message: `completion ratio below archive.min_completion_ratio (${config.min_completion_ratio})`,
-    });
-  }
   if (!input.hasBinding) {
     issues.push({
       level: 'WARNING',
@@ -81,23 +134,20 @@ export function checkChangeDoc(
     });
   }
   if (config.change_id_pattern) {
-    const re = new RegExp(config.change_id_pattern, 'u');
-    if (!re.test(input.name)) {
+    try {
+      const re = new RegExp(config.change_id_pattern, 'u');
+      if (!re.test(input.name)) {
+        issues.push({
+          level: 'ERROR',
+          path: 'change-id',
+          message: `Change id '${input.name}' does not match change_id.pattern '${config.change_id_pattern}' (active changes only; archived changes are not re-checked).`,
+        });
+      }
+    } catch (error) {
       issues.push({
         level: 'ERROR',
         path: 'change-id',
-        message: `Change id '${input.name}' does not match change_id.pattern '${config.change_id_pattern}' (sdd-workflow r29; scope: active changes only, archive/legacy shapes are not back-checked).`,
-      });
-    }
-  }
-  if (opts.stage !== undefined) {
-    const currentIdx = STAGE_ORDER.indexOf(input.stage);
-    const requiredIdx = STAGE_ORDER.indexOf(opts.stage);
-    if (currentIdx < requiredIdx) {
-      issues.push({
-        level: 'ERROR',
-        path: 'stage',
-        message: `stage \`${input.stage}\` is below the required \`${opts.stage}\``,
+        message: `change_id.pattern is not a valid regular expression: ${(error as Error).message}`,
       });
     }
   }
@@ -108,17 +158,17 @@ export type ChangeValidationConfig = ChangeCheckConfig;
 
 const COMPLETENESS: Record<string, string> = {
   draft:
-    "Change is in 'draft' stage (next: add design.md + tasks.md, then `llman sdd change start <id>` to enter a feature branch)",
+    "Change is in 'draft' stage (next: add design.md + tasks.md, then `llman-sdd change start <id>` to enter a feature branch)",
   designed:
-    "Change is in 'designed' stage (next: add tasks.md to reach 'planned', then `llman sdd change start` to enter feature branch and reach 'full')",
+    "Change is in 'designed' stage (next: add tasks.md to reach 'planned', then `llman-sdd change start` to enter feature branch and reach 'full')",
   planned:
-    "Change is in 'planned' stage (next: `llman sdd change start` to enter feature branch and reach 'full')",
-  full: "Change is bound and stage is 'full' (verify readiness via `llman sdd show <id> --json` readyToImplement)",
+    "Change is in 'planned' stage (next: `llman-sdd change start` to enter feature branch and reach 'full')",
+  full: "Change is bound and stage is 'full' (verify readiness via `llman-sdd show <id> --json` readyToImplement)",
 };
 
 /**
- * File-aware change validation with v1 messages/paths (used by the validate
- * command). `strict` escalates WARNING issues to ERROR (v1 build_report).
+ * File-aware change validation with predecessor messages/paths (used by the validate
+ * command). `strict` escalates WARNING issues to ERROR (predecessor build_report).
  * `git` (optional) enables the r63 completeness WARNINGs — Full-not-ready
  * with skill guidance, per change.
  */
@@ -137,12 +187,15 @@ export function validateChange(
   const dir = `${root}/llmanspec/changes/${id}/`;
   const baseDir = `${root}/llmanspec/changes`;
   const proposal = `${dir}proposal.md`;
+  // Probed once here: shared by the stage inference below and the --stage
+  // artifact gate at the end (predecessor issue order preserved).
+  const hasDesign = io.exists(`${dir}design.md`);
+  const hasTasks = io.exists(`${dir}tasks.md`);
   if (!io.exists(proposal)) {
     push('ERROR', 'proposal.md', 'Change is missing proposal.md.');
   } else {
     const text = io.readText(proposal);
-    const fmMatch = text.match(/^---\n([\s\S]*?)\n---/u);
-    const fm = fmMatch?.[1] ?? '';
+    const fm = extractFrontmatter(text) ?? '';
     const fmLines = fm.split('\n').map((l) => l.trim());
 
     for (const key of ['depends_on', 'blocks'] as const) {
@@ -180,13 +233,7 @@ export function validateChange(
           );
           continue;
         }
-        const depDir = `${baseDir}/${item}`;
-        const archived = `${baseDir}/archive`;
-        if (
-          !io.exists(`${depDir}/proposal.md`) &&
-          !io.exists(dir.replace(/\/[^/]+\/$/u, '/archive/')) &&
-          !io.listDir(archived).some((n) => n.endsWith(`-${item}`))
-        ) {
+        if (resolveChangeRef(io, baseDir, item) === 'unknown') {
           push(
             'ERROR',
             `proposal.md/frontmatter.${key}`,
@@ -196,7 +243,7 @@ export function validateChange(
       }
     }
 
-    // Unknown frontmatter field gate (v1).
+    // Unknown frontmatter field gate (predecessor).
     for (const l of fmLines) {
       if (l === '' || l.startsWith('-') || l.startsWith('#')) continue;
       const m = l.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*:/u);
@@ -204,22 +251,14 @@ export function validateChange(
         push(
           'ERROR',
           'proposal.md/frontmatter',
-          `proposal.md frontmatter has unknown field '${m[1]}'; allowed fields are: ${ALLOWED_FIELDS.join(', ')}. Stage is inferred from on-disk artifacts (run \`llman sdd show\` / \`llman sdd list\`); do not store lifecycle state in frontmatter.`,
+          `proposal.md frontmatter has unknown field '${m[1]}'; allowed fields are: ${ALLOWED_FIELDS.join(', ')}. Stage is inferred from on-disk artifacts (run \`llman-sdd show\` / \`llman-sdd list\`); do not store lifecycle state in frontmatter.`,
         );
       }
     }
 
-    const hasDesign = io.exists(`${dir}design.md`);
-    const hasTasks = io.exists(`${dir}tasks.md`);
     const binding = readBinding(text);
-    const stage =
-      hasDesign && hasTasks
-        ? binding !== null
-          ? 'full'
-          : 'planned'
-        : hasDesign
-          ? 'designed'
-          : 'draft';
+    // stageFor (change/collect) is the monotonic stage SSOT (r34).
+    const stage = stageFor(hasDesign, hasTasks, binding !== null);
 
     if (hasTasks && !hasDesign) {
       push(
@@ -230,16 +269,7 @@ export function validateChange(
     }
 
     if (hasTasks) {
-      const tasks = io.readText(`${dir}tasks.md`);
-      let total = 0;
-      let completed = 0;
-      for (const line of tasks.split('\n')) {
-        const m = line.match(/^\s*-\s+\[( |x|X)\]/u);
-        if (m) {
-          total += 1;
-          if (m[1] !== ' ') completed += 1;
-        }
-      }
+      const { completed, total, pendingLines } = parseTaskCheckboxes(io.readText(`${dir}tasks.md`));
       if (total > 0 && completed < total) {
         const n = total - completed;
         push(
@@ -248,31 +278,41 @@ export function validateChange(
           `${n} unchecked task(s) in tasks.md`,
         );
       }
+      // D9/B23 (active changes only — validate domain): an unchecked task whose
+      // title starts with a close-out verb is a pipeline-step pseudo-task; the
+      // task gate requires every task checked, so it can never legitimately
+      // stay as a task. Match on the leading verb only, so "fix finalize task
+      // gate" (a task ABOUT close-out) is not flagged.
+      for (const line of closeOutTaskLines(pendingLines)) {
+        const title = line.replace(/^-\s+\[ \]\s*/u, '').trim();
+        push(
+          'WARNING',
+          'tasks',
+          `task "${title}" looks like a close-out step; ${CLOSE_OUT_TASK_HINT}`,
+        );
+      }
     }
 
-    // completeness INFO (v1 surface).
+    // completeness INFO (predecessor surface).
     push('INFO', 'completeness', COMPLETENESS[stage] ?? '');
 
-    // r63: Full-but-not-ready WARNING with skill guidance (v1 r1 surface).
+    // r63: Full-but-not-ready WARNING with skill guidance (predecessor r1 surface).
     if (opts.git !== undefined && binding !== null && stage === 'full') {
-      const needs =
-        text.match(/^needs_specs_change:\s*(true|false)\s*$/mu)?.[1] !== undefined
-          ? text.match(/^needs_specs_change:\s*(true|false)\s*$/mu)?.[1] === 'true'
-          : true;
-      const touched =
-        opts.git.runOpt(['diff', '--name-only', `${binding.baseBranch}...${binding.branch}`]) ?? '';
-      const landed = touched.includes('llmanspec/specs/');
+      const needs = readNeedsSpecsChange(fm);
+      const landed = specsLanded(opts.git, binding);
       if (!landed && needs) {
         push(
           'WARNING',
           'proposal.md',
-          `specs not landed: change bound to \`${binding.branch}\` but no changes under \`llmanspec/specs/\` on its bound branch. Edit live specs there and commit (or set \`needs_specs_change: false\` if this change has no live contract edits). Skill: llman-sdd-propose — do NOT re-run change start when already attached; apply only when \`llman-sdd show <id> --json\` reports readyToImplement=true (llman-sdd-apply).`,
+          `specs not landed: change bound to \`${binding.branch}\` but no changes under \`llmanspec/specs/\` on its bound branch. Edit live specs there and commit (or set \`needs_specs_change\` to false in the frontmatter if this change has no live contract edits). Skill: llman-sdd-propose — do NOT re-run change start when already attached; start llman-sdd-apply once the specs-landed gate passes (see \`llman-sdd show <id>\` gateChecks).`,
         );
       }
     }
   }
 
-  // pattern gate (v1 change-id path).
+  // pattern gate (predecessor change-id path). loadConfig compiles the pattern first
+  // on the CLI path; this branch defends direct core callers that build a
+  // ChangeCheckConfig without going through loadConfig.
   if (config.change_id_pattern) {
     try {
       const re = new RegExp(config.change_id_pattern, 'u');
@@ -280,18 +320,20 @@ export function validateChange(
         push(
           'ERROR',
           'change-id',
-          `Change id '${id}' does not match change_id.pattern '${config.change_id_pattern}' (sdd-workflow r29; scope: active changes only, archive/legacy shapes are not back-checked).`,
+          `Change id '${id}' does not match change_id.pattern '${config.change_id_pattern}' (active changes only; archived changes are not re-checked).`,
         );
       }
-    } catch {
-      /* compile already validated at load; ignore */
+    } catch (error) {
+      push(
+        'ERROR',
+        'change-id',
+        `change_id.pattern is not a valid regular expression: ${(error as Error).message}`,
+      );
     }
   }
 
-  // stage gate (v1 --stage: artifact presence per gate).
+  // stage gate (predecessor --stage: artifact presence per gate).
   if (opts.stage !== undefined) {
-    const hasDesign = io.exists(`${dir}design.md`);
-    const hasTasks = io.exists(`${dir}tasks.md`);
     if (opts.stage === 'designed' && !hasDesign) {
       push('ERROR', 'design.md', `Stage forced to 'designed' but design.md is missing`);
     }
@@ -320,22 +362,3 @@ const ALLOWED_FIELDS = [
   'base_sha',
   'needs_specs_change',
 ];
-
-export interface PlaceholderTarget {
-  featureDir: string;
-  featureName: string;
-  featurePath: string;
-}
-
-/** True when run_command carries any r48 placeholder. */
-export function hasPlaceholders(runCommand: string): boolean {
-  return /\{feature_dir\}|\{feature_name\}|\{feature_path\}/u.test(runCommand);
-}
-
-/** Expand {feature_dir}/{feature_name}/{feature_path} for one target (r48). */
-export function expandRunCommand(runCommand: string, target: PlaceholderTarget): string {
-  return runCommand
-    .replaceAll('{feature_dir}', target.featureDir)
-    .replaceAll('{feature_name}', target.featureName)
-    .replaceAll('{feature_path}', target.featurePath);
-}

package/src/validation/harness.ts

@@ -0,0 +1,161 @@
+/**
+ * BDD harness execution for validate (validation capability, r13/r48):
+ * expands bdd.run_command per capability, executes each expanded command
+ * string at most once per validate invocation (batch-once), and maps results
+ * to per-capability issues. Pure — the subprocess runs through the injected
+ * HarnessRunner; this module never reads the environment or the wall clock
+ * (the nested-invocation guard is read by the CLI and passed in as a
+ * parameter).
+ */
+import type { ValidationItem } from './validate.ts';
+
+/**
+ * Harness runner port (r13/r48): executes one expanded bdd.run_command
+ * string; the CLI adapter owns the subprocess (and the nested-invocation
+ * guard env it exports). exitCode is null only when the command could not
+ * start (spawnError then carries the reason). Lives here rather than in
+ * ports.ts so the validation module gains no new cross-module edge (r72).
+ */
+export interface HarnessRunner {
+  run(
+    command: string,
+    cwd: string,
+  ): {
+    exitCode: number | null;
+    output: string;
+    spawnError?: string;
+  };
+}
+
+export interface HarnessTarget {
+  /** Capability id ({feature_name}). */
+  capability: string;
+  /** Repo-root-relative path of the capability's main .feature file. */
+  featurePath: string;
+}
+
+/** Trigger state assembled by the CLI (env guard + flags + config + runner). */
+export interface HarnessGate {
+  /** LLMAN_SDD_HARNESS_ACTIVE=1 was set by an enclosing validate invocation. */
+  nested: boolean;
+  check: 'default' | 'on' | 'off';
+  /** Undefined when bdd.run_command is not configured (non-empty string). */
+  runner: HarnessRunner | undefined;
+  runCommand: string | null;
+  /** Project root — the cwd every harness subprocess runs in. */
+  cwd: string;
+  /** CLI emits its one-line stderr banner through this hook before the first execution. */
+  onBeforeFirstRun?: (expanded: string) => void;
+}
+
+export interface HarnessRunOutcome {
+  /** Harness issues per capability, in target order. */
+  issuesByCapability: Map<string, ValidationItem[]>;
+  /** True when at least one command actually executed in this call. */
+  executed: boolean;
+}
+
+/** Plain-text placeholder expansion — capability ids are kebab-constrained. */
+export function expandRunCommand(command: string, target: HarnessTarget): string {
+  const dirEnd = target.featurePath.lastIndexOf('/');
+  const featureDir = dirEnd === -1 ? target.featurePath : target.featurePath.slice(0, dirEnd);
+  return command
+    .replaceAll('{feature_path}', target.featurePath)
+    .replaceAll('{feature_dir}', featureDir)
+    .replaceAll('{feature_name}', target.capability);
+}
+
+interface CacheEntry {
+  success: boolean;
+  /** First ERROR message (≤200 chars) so a cached failure points at the cause. */
+  failureSummary: string | null;
+}
+
+const OUTPUT_TAIL = 200;
+
+/**
+ * Trigger matrix (r13): --no-check skips silently; a nested invocation skips
+ * with a per-spec INFO; an explicit --check without a configured run_command
+ * yields a single INFO on the first spec; otherwise every expanded command
+ * executes at most once (cache keyed by the expanded string).
+ */
+export function runHarnessForSpecs(
+  targets: readonly HarnessTarget[],
+  gate: HarnessGate,
+): HarnessRunOutcome {
+  const issuesByCapability = new Map<string, ValidationItem[]>();
+  if (gate.check === 'off') return { issuesByCapability, executed: false };
+  if (gate.nested) {
+    for (const target of targets) {
+      issuesByCapability.set(target.capability, [
+        {
+          level: 'INFO',
+          id: target.featurePath,
+          message: 'bdd harness skipped: nested invocation',
+        },
+      ]);
+    }
+    return { issuesByCapability, executed: false };
+  }
+  if (gate.runner === undefined || gate.runCommand === null || gate.runCommand === '') {
+    if (gate.check === 'on' && targets.length > 0) {
+      const first = targets[0] as HarnessTarget;
+      issuesByCapability.set(first.capability, [
+        {
+          level: 'INFO',
+          id: first.featurePath,
+          message: '--check has no effect: bdd.run_command is not configured',
+        },
+      ]);
+    }
+    return { issuesByCapability, executed: false };
+  }
+  const cache = new Map<string, CacheEntry>();
+  let executed = false;
+  let announced = false;
+  for (const target of targets) {
+    const expanded = expandRunCommand(gate.runCommand, target);
+    const cached = cache.get(expanded);
+    let issues: ValidationItem[];
+    if (cached !== undefined) {
+      issues = cached.success
+        ? [
+            {
+              level: 'INFO',
+              id: target.featurePath,
+              message: `bdd harness passed (cached): ${expanded}`,
+            },
+          ]
+        : [
+            {
+              level: 'ERROR',
+              id: target.featurePath,
+              message: `bdd harness failed (cached result of ${expanded}): ${cached.failureSummary}`,
+            },
+          ];
+    } else {
+      if (!announced) {
+        gate.onBeforeFirstRun?.(expanded);
+        announced = true;
+      }
+      executed = true;
+      const result = gate.runner.run(expanded, gate.cwd);
+      const firstError =
+        result.spawnError !== undefined
+          ? `bdd harness could not start: ${expanded}: ${result.spawnError}`
+          : result.exitCode === 0
+            ? null
+            : `bdd harness failed (exit ${result.exitCode}): ${expanded}: ${result.output.slice(-OUTPUT_TAIL)}`;
+      issues =
+        firstError === null
+          ? [{ level: 'INFO', id: target.featurePath, message: `bdd harness passed: ${expanded}` }]
+          : [{ level: 'ERROR', id: target.featurePath, message: firstError }];
+      cache.set(expanded, {
+        success: firstError === null,
+        failureSummary: firstError === null ? null : firstError.slice(0, OUTPUT_TAIL),
+      });
+    }
+    issuesByCapability.set(target.capability, issues);
+  }
+  return { issuesByCapability, executed };
+}

package/src/validation/staleness.ts

@@ -1,5 +1,5 @@
 /**
- * Staleness evaluator (validation/staleness parity): v1 `sdd/spec/staleness.rs`
+ * Staleness evaluator (validation/staleness parity): predecessor `sdd/spec/staleness.rs`
  * observable contract — status/baseRef/scope/touchedPaths/specUpdated/dirty/
  * notes plus per-capability staleness issues. Pure: git + env are injected.
  */
@@ -62,9 +62,9 @@ const BASE_MISSING_MSG =
   "Note: Unable to resolve base ref for staleness check. Set LLMANSPEC_BASE_REF (e.g. 'main' or 'origin/main'), or upgrade llman if below 0.0.60.";
 
 /**
- * Evaluate staleness for one capability spec — v1 status semantics.
+ * Evaluate staleness for one capability spec — predecessor status semantics.
  * Returns the info object plus warning/info issues (strict escalation is the
- * caller's job, matching v1 `apply_strict`).
+ * caller's job, matching predecessor `apply_strict`).
  */
 export function evaluateStaleness(deps: StalenessDeps): {
   info: StalenessInfo;
@@ -125,7 +125,7 @@ export function evaluateStaleness(deps: StalenessDeps): {
     }
   }
 
-  // Tolerant: outside a git repo (or on git failure) treat as dirty (v1 unwrap_or(true)).
+  // Tolerant: outside a git repo (or on git failure) treat as dirty (predecessor unwrap_or(true)).
   const dirty = (git.runOpt(['status', '--porcelain']) ?? 'dirty') !== '';
   if (dirty) {
     if (status === 'OK' || status === 'STALE') status = 'INFO';
@@ -143,13 +143,17 @@ export function evaluateStaleness(deps: StalenessDeps): {
   }
 }
 
-const STALE_MSG = 'Note: Spec files changed on the base branch; re-review the spec.';
+const STALE_MSG =
+  "Note: Code in this spec's scope changed on this branch but the spec was not updated; re-review the spec.";
 const SPEC_UPDATED_MSG = 'Note: Spec updated on this branch.';
 
 function revParse(git: GitLike, ref: string): string | null {
   return git.runOpt(['rev-parse', '--verify', '--quiet', ref]) ?? null;
 }
 
+// Deliberately NOT shared with defaultBranch() in git/spawnGit.ts — this
+// predecessor staleness probe is local-only (main → master, 'main' fallback, no origin
+// consultation). Do not merge the two.
 function defaultBranchNameFn(git: GitLike): string {
   if (git.runOpt(['show-ref', '--verify', '--quiet', 'refs/heads/main']) !== null) return 'main';
   if (git.runOpt(['show-ref', '--verify', '--quiet', 'refs/heads/master']) !== null)