@llman-sdd/core 0.3.1 → 0.5.0

package/src/change/tasks.ts

@@ -0,0 +1,59 @@
+/**
+ * tasks.md checkbox parsing — single source of truth shared by change
+ * collection (change/collect), change validation (validation/changeCheck),
+ * the archive task gate (change/lifecycle) and the CLI archive gate.
+ * predecessor line shape: `^\s*-\s+\[( |x|X)\]`.
+ *
+ * D9 close-out pseudo-task detection (B23): tasks.md must list implementation
+ * and verification tasks only — `change finalize`/`change archive` are
+ * pipeline steps and MUST NOT be tasks (their task gate requires every task
+ * checked, so a close-out "task" is self-contradictory: checking it lies,
+ * leaving it blocks). The hint constant is the single shared text; validate
+ * reports it as a WARNING and finalize/archive append it to the gate error
+ * when a matching unchecked task exists.
+ */
+
+/** Regex: a task title whose verb (after the `T<n>[a-z]?:` numbering) starts
+ * with a close-out step. Chinese verbs plus finalize/archive keywords. */
+export const CLOSE_OUT_TASK_PATTERN = /^(收口|归档|finalize\b|archive\b)/iu;
+
+/** The exact remediation hint — single definition (D9: 文案常量单一定义). */
+export const CLOSE_OUT_TASK_HINT =
+  'finalize is a pipeline step — remove it from tasks.md (finalize/archive require every task checked)';
+
+/** Strip an optional `T<n>[a-z]?:` numbering prefix from a task title. */
+export function stripTaskNumbering(title: string): string {
+  return title.replace(/^T\d+[a-z]?:\s*/u, '');
+}
+
+/** True when the title (after numbering) starts with a close-out verb. */
+export function isCloseOutTaskTitle(title: string): boolean {
+  return CLOSE_OUT_TASK_PATTERN.test(stripTaskNumbering(title));
+}
+
+/** The unchecked pending lines in tasks.md that look like close-out steps. */
+export function closeOutTaskLines(pendingLines: readonly string[]): string[] {
+  return pendingLines.filter((line) => isCloseOutTaskTitle(line.replace(/^-\s+\[ \]\s*/u, '')));
+}
+
+export interface ParsedTaskCheckboxes {
+  completed: number;
+  total: number;
+  /** Trimmed source lines of unchecked tasks, e.g. `- [ ] draft spec`. */
+  pendingLines: string[];
+}
+
+export function parseTaskCheckboxes(tasksMd: string): ParsedTaskCheckboxes {
+  let completed = 0;
+  let total = 0;
+  const pendingLines: string[] = [];
+  for (const line of tasksMd.split('\n')) {
+    const m = line.match(/^\s*-\s+\[( |x|X)\]/u);
+    if (m) {
+      total += 1;
+      if (m[1] !== ' ') completed += 1;
+      else pendingLines.push(line.trim());
+    }
+  }
+  return { completed, total, pendingLines };
+}

package/src/config/changeId.ts

@@ -1,12 +1,11 @@
 /**
  * change_id contract (r59/r60): pattern compile-check at load time, validate
  * ERROR for active changes violating the pattern, and `change new --from`
- * template rendering (nunjucks Strict) with the v1 preset variables.
+ * template rendering (Strict via templates/engine.ts) with the predecessor preset vars.
  */
 
-import nunjucks from 'nunjucks';
-
 import { harvestUniqueNumbers, type NextIdIo } from '../change/nextId.ts';
+import { renderTemplate } from '../templates/engine.ts';
 
 export class ChangeIdError extends Error {}
 
@@ -21,7 +20,7 @@ export function compileChangeIdPattern(pattern: string | null | undefined): RegE
 }
 
 export interface ChangeIdVars {
-  /** whole-tree next free number (v1 llman_sdd_unique_id) */
+  /** whole-tree next free number (predecessor llman_sdd_unique_id) */
   llman_sdd_unique_id: number;
   /** explicit --verb value; undefined when not provided (Strict render errors) */
   verb?: string;
@@ -32,12 +31,14 @@ export interface ChangeIdVars {
 }
 
 /**
- * Render a change_id.template with v1 preset vars (r60). Strict semantics:
- * referencing a variable that was not provided errors out (v1 parity —
- * `{{ verb }}` without --verb fails).
+ * Render a change_id.template with predecessor preset vars (r60). Strict semantics:
+ * referencing a variable that was not provided errors out (predecessor parity —
+ * `{{ verb }}` without --verb fails). Rendering converges on
+ * templates/engine.ts (Q3): template calls single-point, no loader,
+ * autoescape:false — this file no longer imports the adapter directly.
  */
 export function renderChangeIdTemplate(template: string, vars: ChangeIdVars): string {
-  // Named pre-check (v1 parity): referencing an unprovided variable errors with
+  // Named pre-check (predecessor parity): referencing an unprovided variable errors with
   // the variable name and the preset list, instead of a generic render error.
   const provided = new Set(
     Object.keys(vars).filter((k) => vars[k as keyof ChangeIdVars] !== undefined),
@@ -50,8 +51,9 @@ export function renderChangeIdTemplate(template: string, vars: ChangeIdVars): st
       );
     }
   }
-  const env = new nunjucks.Environment(undefined, { throwOnUndefined: true });
-  const rendered = env.renderString(template, vars as unknown as Record<string, unknown>).trim();
+  const rendered = renderTemplate(template, new Map(), vars as unknown as Record<string, string>, {
+    throwOnUndefined: true,
+  }).trim();
   if (rendered === '') throw new ChangeIdError('change_id.template rendered to an empty id');
   return rendered;
 }
@@ -64,9 +66,9 @@ export function nextUniqueNumber(io: NextIdIo, llmanspecRoot: string): number {
 const VERB_TABLE = ['add', 'update', 'remove', 'refactor', 'fix'] as const;
 
 /**
- * v1 `new.rs::split_verb` parity: the subject is the derived id minus a
+ * predecessor `new.rs::split_verb` parity: the subject is the derived id minus a
  * detected table-verb prefix; the verb is the explicit override when given,
- * otherwise the auto-detected one (v1 renders `{{ verb }}` without --verb for
+ * otherwise the auto-detected one (predecessor renders `{{ verb }}` without --verb for
  * descriptions that carry a verb token).
  */
 export function splitVerb(

package/src/config/load.ts

@@ -8,6 +8,7 @@
  */
 import { parse } from 'yaml';
 
+import { compileChangeIdPattern } from './changeId.ts';
 import { sddConfigSchema, type SddConfig } from './schema.ts';
 
 export const MAX_REPORTED_ISSUES = 5;
@@ -44,5 +45,18 @@ export function loadConfig(source: string): SddConfig {
     });
     throw new ConfigValidationError(issues);
   }
+  // r59: compile change_id.pattern at load time so EVERY config-reading
+  // command path (archive/skeleton/review included) fails fast on an invalid
+  // regex instead of silently passing it through.
+  const pattern = result.data.change_id?.pattern;
+  if (pattern !== undefined && pattern !== null && pattern !== '') {
+    try {
+      compileChangeIdPattern(pattern);
+    } catch (error) {
+      // ChangeIdError message already carries the change_id.pattern path and
+      // the regex engine's original error.
+      throw new ConfigValidationError([(error as Error).message]);
+    }
+  }
   return result.data;
 }

package/src/config/schema.ts

@@ -1,8 +1,8 @@
 /**
  * llmanspec/config.yaml contract (config-schema capability): field-for-field
- * alignment with v1 (crates/llman-sdd/src/sdd/project/config.rs). Unknown
- * keys are tolerated (v1 schema sets no additionalProperties:false); field
- * names stay snake_case for v1-config readability.
+ * alignment with predecessor (crates/llman-sdd/src/sdd/project/config.rs). Unknown
+ * keys are tolerated (predecessor schema sets no additionalProperties:false); field
+ * names stay snake_case for predecessor-config readability.
  */
 import { z } from 'zod';
 
@@ -15,28 +15,6 @@ export const EXTRA_SKILLS = [
   'llman-sdd-research',
 ] as const;
 
-export const tagsBindingSchema = z
-  .object({
-    kind: z.literal('tags').describe('Tag predicate source kind.'),
-    tags: z.array(z.string()).min(1).describe('Required tag names (leading `@` optional).'),
-  })
-  .describe('A scenario is bound when its tags contain ALL listed tags.');
-
-export const scenarioAttrsBindingSchema = z
-  .object({
-    kind: z.literal('scenario-attrs').describe('Per-scenario attribute source kind.'),
-    files: z
-      .array(z.string())
-      .min(1)
-      .describe('Glob patterns of source files to scan for scenario attribute blocks.'),
-  })
-  .describe('Extract path/name literal pairs from scenario attribute blocks in matched files.');
-
-export const bindingSchema = z.discriminatedUnion('kind', [
-  tagsBindingSchema,
-  scenarioAttrsBindingSchema,
-]);
-
 export const bddSchema = z.object({
   framework: z
     .string()
@@ -44,22 +22,13 @@ export const bddSchema = z.object({
     .describe(
       'BDD framework identifier (optional). Only used to derive a default run_command when run_command is unset.',
     ),
-  feature_dir: z
-    .string()
-    .nullish()
-    .describe('Root directory for .feature files, relative to project root.'),
-  default_language: z
-    .string()
-    .nullish()
-    .describe("Gherkin parsing language code (e.g. 'en', 'zh-CN'). Default: 'en'."),
   run_command: z
     .string()
     .nullish()
     .describe(
-      'Custom test run command. Placeholders: {feature_dir}, {feature_name}, {feature_path}. Without placeholders, validate --all/--specs runs the command at most once per batch (batch-once).',
+      'Harness command executed by validate for spec targets (skip with --no-check). Placeholders: {feature_path}, {feature_dir}, {feature_name}; without placeholders it runs once per validate invocation (batch-once).',
     ),
   verify_prompt: z.string().nullish().describe('Extra prompt text injected during verify phase.'),
-  bindings: z.array(bindingSchema).nullish().describe('Declared harness-binding sources.'),
 });
 
 export const archiveSchema = z.object({
@@ -69,12 +38,6 @@ export const archiveSchema = z.object({
     .describe(
       'When true, unchecked tasks without a defer link are errors (not just warnings). Default: false.',
     ),
-  min_completion_ratio: z
-    .number()
-    .nullish()
-    .describe(
-      'Minimum task completion ratio (0.0-1.0) required for archiving. Default: none (disabled).',
-    ),
 });
 
 export const sddSchema = z.object({

package/src/config/surface.ts

@@ -1,22 +1,19 @@
 /**
- * `config` command surface (r37/r38): read-only overview rendering and
- * non-interactive extra_skills management with comment-preserving writeback.
+ * `config` command surface (r37/r38): read-only overview rendering and the
+ * skills listing shape (the extra_skills write path was removed with
+ * config-command r38).
  */
 
-import { parseDocument } from 'yaml';
-
 import { loadConfig } from './load.ts';
 import { EXTRA_SKILLS } from './schema.ts';
 
-/** Render the five-element overview (v1 parity wording). */
+/** Render the five-element overview (predecessor parity wording). */
 export function renderConfigOverview(source: string): string[] {
   const config = loadConfig(source);
   const enabled = (config.extra_skills ?? []).length;
   const archive = config.archive;
   const archiveConfigured =
-    archive !== null &&
-    archive !== undefined &&
-    (archive.strict_defer || archive.min_completion_ratio !== undefined);
+    archive !== null && archive !== undefined && archive.strict_defer === true;
   return [
     `schema: ${config.schema}`,
     `locale: ${config.locale}`,
@@ -26,34 +23,7 @@ export function renderConfigOverview(source: string): string[] {
   ];
 }
 
-export class ExtraSkillsError extends Error {}
-
-/**
- * Add/remove extra_skills entries with full comment preservation: only the
- * `extra_skills` list node is touched, everything else (including the
- * `$schema` header comment) stays byte-identical.
- */
-export function setExtraSkills(
-  source: string,
-  change: { set?: readonly string[]; unset?: readonly string[] },
-): string {
-  for (const name of [...(change.set ?? []), ...(change.unset ?? [])]) {
-    if (!(EXTRA_SKILLS as readonly string[]).includes(name)) {
-      throw new ExtraSkillsError(`unknown extra skill: ${name}`);
-    }
-  }
-  const wanted = new Set<string>(loadConfig(source).extra_skills ?? []);
-  for (const name of change.set ?? []) wanted.add(name);
-  for (const name of change.unset ?? []) wanted.delete(name);
-
-  const doc = parseDocument(source);
-  const list = [...wanted].toSorted();
-  if (list.length > 0) doc.set('extra_skills', list);
-  else doc.delete('extra_skills');
-  return doc.toString();
-}
-
-/** Shape of `config skills --json` (v1 parity). */
+/** Shape of `config skills --json` (predecessor parity). */
 export function skillsJson(source: string): { enabled: string[]; available: readonly string[] } {
   return { enabled: [...(loadConfig(source).extra_skills ?? [])], available: EXTRA_SKILLS };
 }

package/src/context/indexStore.ts

@@ -21,6 +21,10 @@ export interface IndexIo {
   listDir(path: string): string[];
   mkdirp(path: string): void;
   processAlive(pid: number): boolean;
+  /** Current process id for the rebuild lock (side effect injected, r3). */
+  currentPid(): number;
+  /** Wall clock for lock timestamps / staleness (side effect injected, r3). */
+  now(): Date;
 }
 
 export interface RebuildOpts {
@@ -46,14 +50,14 @@ function acquireLock(io: IndexIo, lockPath: string): void {
     const parsed = parseLock(io.readText(lockPath));
     const stale =
       parsed === null ||
-      Date.now() - Date.parse(parsed.startedAt) > LOCK_MAX_AGE_MS ||
+      io.now().getTime() - Date.parse(parsed.startedAt) > LOCK_MAX_AGE_MS ||
       !io.processAlive(parsed.pid);
     if (!stale) throw new Error(`rebuild already in progress (lock: ${lockPath})`);
     io.remove(lockPath);
   }
   io.writeText(
     lockPath,
-    `pid = ${process.pid}\nstarted_at = "${new Date().toISOString()}"\nchunks_total = 1\nchunks_done = 1\nprogress_pct = 100\n`,
+    `pid = ${io.currentPid()}\nstarted_at = "${io.now().toISOString()}"\nchunks_total = 1\nchunks_done = 1\nprogress_pct = 100\n`,
   );
 }
 
@@ -69,7 +73,7 @@ export function rebuildIndex(
     const specHash = computeSpecHash(specsDir, io);
     const tree = buildTreeIndex(entries, {
       specHash,
-      buildTimestamp: opts.buildTimestamp ?? new Date().toISOString(),
+      buildTimestamp: opts.buildTimestamp ?? io.now().toISOString(),
       chatModel: opts.chatModel,
     });
     io.mkdirp(PAGEINDEX_DIR_REL);

package/src/context/retrieve.ts

@@ -5,7 +5,7 @@
  * direct/related classification (direct wins). r29 pins the output contract:
  * quality ∈ {agentic, unavailable}, exhaustion degrades to agentic +
  * truncation note, failures emit summary {totalSpecs:0, error:true}.
- * Env contract mirrors v1: LLMAN_SDD_INDEX_CHAT_MODEL (required) /
+ * Env contract mirrors predecessor: LLMAN_SDD_INDEX_CHAT_MODEL (required) /
  * LLMAN_SDD_INDEX_CHAT_API_HOST|KEY with LLMAN_SDD_INDEX_OPENAI_* fallbacks.
  */
 import type { SerializedTreeIndex } from './tree.ts';
@@ -52,7 +52,7 @@ export interface ContextSuccessSummary {
   paths: string[];
 }
 
-/** r29: failures collapse to v1's print_err two-field error summary. */
+/** r29: failures collapse to predecessor's print_err two-field error summary. */
 export interface ContextErrorSummary {
   totalSpecs: 0;
   error: true;
@@ -165,7 +165,7 @@ function parseTiers(content: string): { direct: TierEntry[]; related: TierEntry[
 
 /**
  * r28: the model may classify one spec into both tiers (observed with real
- * models; v1 passes duplicates through). Cross-tier duplicates keep the direct
+ * models; predecessor passes duplicates through). Cross-tier duplicates keep the direct
  * entry, in-tier duplicates keep the first occurrence; summary counts are
  * computed after this runs.
  */
@@ -194,13 +194,11 @@ export interface RetrieveDeps extends TreeToolDeps {
   task: string;
   paths?: string;
   top?: number;
-  maxRounds?: number;
   fetchImpl?: typeof fetch;
 }
 
 export async function runContextRetrieval(deps: RetrieveDeps): Promise<ContextResult> {
   const fetchImpl = deps.fetchImpl ?? fetch;
-  const maxRounds = deps.maxRounds ?? MAX_TOOL_ROUNDS;
   const messages: Record<string, unknown>[] = [
     { role: 'system', content: SYSTEM_PROMPT },
     {
@@ -212,8 +210,8 @@ export async function runContextRetrieval(deps: RetrieveDeps): Promise<ContextRe
   let tiers: { direct: TierEntry[]; related: TierEntry[] } | null = null;
   let toolCalls = 0;
   try {
-    for (let round = 0; round <= maxRounds && tiers === null; round += 1) {
-      const forceFinal = round === maxRounds;
+    for (let round = 0; round <= MAX_TOOL_ROUNDS && tiers === null; round += 1) {
+      const forceFinal = round === MAX_TOOL_ROUNDS;
       const body: Record<string, unknown> = {
         model: deps.config.model,
         messages,
@@ -262,19 +260,19 @@ export async function runContextRetrieval(deps: RetrieveDeps): Promise<ContextRe
       tiers = parseTiers(message.content ?? '');
     }
   } catch (error) {
-    // v1 print_err semantics: network/transport/parse failures degrade to
+    // predecessor print_err semantics: network/transport/parse failures degrade to
     // unavailable + api_error, never crash the CLI without JSON output.
     return errorResult(`retrieval failed: ${(error as Error).message}`, 'api_error');
   }
   if (tiers === null) {
     // r29: loop exhaustion degrades to agentic + truncation note + empty
-    // tiers (v1 truncated RetrievalOutput), with the success summary shape.
+    // tiers (predecessor truncated RetrievalOutput), with the success summary shape.
     const noTiers: TierEntry[] = [];
     return {
       status: {
         ok: true,
         quality: 'agentic',
-        qualityNote: `agentic loop hit the ${maxRounds}-round tool-call limit; result may be incomplete`,
+        qualityNote: `agentic loop hit the ${MAX_TOOL_ROUNDS}-round tool-call limit; result may be incomplete`,
       },
       direct: noTiers,
       related: [],

package/src/context/tree.ts

@@ -1,11 +1,12 @@
 /**
  * Pageindex tree (context-index capability, r26): specs IR serialized as a
  * tree — building is LLM-free. Serialization keys are snake_case, matching
- * v1's tree.json so retrieval IDs stay comparable.
+ * predecessor's tree.json so retrieval IDs stay comparable.
  */
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 
+import { specIdOf } from '../spec/ir.ts';
 import type { SpecEntry } from '../validation/validate.ts';
 
 export const TREE_VERSION = 1;
@@ -40,7 +41,7 @@ export interface SerializedTreeIndex {
 }
 
 function joinSteps(
-  steps: { kind: string; text: string }[],
+  steps: readonly { kind: string; text: string }[],
   kind: 'given' | 'when' | 'then',
 ): string {
   return steps
@@ -52,28 +53,31 @@ function joinSteps(
 export function buildDocs(entries: readonly SpecEntry[]): SerializedDocNode[] {
   return entries
     .map((entry) => {
-      const cap = entry.doc.header.capability ?? entry.fileName;
-      const reqs = entry.doc.scenarios
-        .filter((s) => s.classification === 'human')
-        .map((s) => ({
-          req_id: s.reqIds[0] ?? '',
-          title: s.name,
-          statement: s.statement
-            .split('\n')
-            .map((l) => l.replace(/^-\s+/u, ''))
-            .join('\n'),
-        }));
-      const scenarios = entry.doc.scenarios
-        .filter((s) => s.classification === 'executable')
-        .map((s) => ({
-          req_id: s.reqIds[0] ?? '',
-          id: s.name,
-          given: joinSteps(s.steps, 'given'),
-          when: joinSteps(s.steps, 'when'),
-          // `then` is the tree.json contract key, not a thenable
-          // oxlint-disable-next-line unicorn/no-thenable
-          then: joinSteps(s.steps, 'then'),
-        }));
+      const cap = specIdOf(entry);
+      const reqs = entry.doc.rules.map((r) => ({
+        req_id: r.reqId,
+        title: r.title,
+        statement: r.description
+          .split('\n')
+          .map((l) => l.replace(/^-\s+/u, ''))
+          .join('\n'),
+      }));
+      const scenOf = (
+        s: { name: string; steps: readonly { kind: string; text: string }[] },
+        reqId: string,
+      ): SerializedScenarioNode => ({
+        req_id: reqId,
+        id: s.name,
+        given: joinSteps(s.steps, 'given'),
+        when: joinSteps(s.steps, 'when'),
+        // `then` is the tree.json contract key, not a thenable
+        // oxlint-disable-next-line unicorn/no-thenable
+        then: joinSteps(s.steps, 'then'),
+      });
+      const scenarios = [
+        ...entry.doc.rules.flatMap((r) => r.scenarios.map((s) => scenOf(s, r.reqId))),
+        ...entry.doc.orphans.map((s) => scenOf(s, '')),
+      ];
       return { spec_id: cap, purpose: entry.doc.header.purpose ?? '', reqs, scenarios };
     })
     .toSorted((a, b) => a.spec_id.localeCompare(b.spec_id));

package/src/git/spawnGit.ts

@@ -55,6 +55,8 @@ export function isCleanTree(git: GitLike): boolean {
 }
 
 /** Local-first default branch resolution: main → master → origin/HEAD → origin/*. */
+// Deliberately NOT shared with defaultBranchNameFn() in validation/staleness.ts
+// (that probe is local-only with a 'main' fallback — predecessor staleness parity). Do not merge.
 export function defaultBranch(git: GitLike): string {
   for (const candidate of ['main', 'master']) {
     if (git.runOpt(['show-ref', '--verify', '--quiet', `refs/heads/${candidate}`]) !== null) {
@@ -80,14 +82,100 @@ export function revParseHead(git: GitLike): string {
   return git.run(['rev-parse', 'HEAD']);
 }
 
-/** Count uncommitted files (v1 "dirty tree: N uncommitted files"). */
+/** Count uncommitted files (predecessor "dirty tree: N uncommitted files"). */
 export function dirtyCount(git: GitLike): number {
   const s = git.run(['status', '--porcelain']);
   if (s === '') return 0;
   return s.split('\n').filter((l) => l.trim() !== '').length;
 }
 
-/** Fork-point sha of `current` relative to `other` (v1 merge-base semantics). */
+/** Fork-point sha of `current` relative to `other` (predecessor merge-base semantics). */
 export function mergeBase(git: GitLike, current: string, other: string): string {
   return git.runOpt(['merge-base', current, other]) ?? git.run(['rev-parse', current]);
 }
+
+export interface WorktreeEntry {
+  /** Absolute worktree path as reported by `git worktree list --porcelain`. */
+  path: string;
+  head: string | null;
+  /** Checked-out local branch (`refs/heads/` stripped); null when detached/bare. */
+  branch: string | null;
+}
+
+/** Parse `git worktree list --porcelain` into entries (r69 held-target detection). */
+export function worktreeList(git: GitLike): WorktreeEntry[] {
+  const out = git.run(['worktree', 'list', '--porcelain']);
+  const entries: WorktreeEntry[] = [];
+  let current: WorktreeEntry | null = null;
+  for (const line of out.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      if (current !== null) entries.push(current);
+      current = { path: line.slice('worktree '.length), head: null, branch: null };
+    } else if (current === null) {
+      continue;
+    } else if (line.startsWith('HEAD ')) {
+      current.head = line.slice('HEAD '.length);
+    } else if (line.startsWith('branch ')) {
+      current.branch = line.slice('branch '.length).replace(/^refs\/heads\//u, '');
+    }
+    // `detached` / `bare` marker lines leave branch null on purpose.
+  }
+  if (current !== null) entries.push(current);
+  return entries;
+}
+
+export interface MainCheckoutProbe {
+  /** Resolved default branch name (local-first main → master → origin/*). */
+  defaultBranch: string | null;
+  /** Absolute path of the executing worktree; null when unresolvable. */
+  here: string | null;
+  /**
+   * Absolute path of the worktree holding the default branch (the main
+   * checkout); null when no worktree holds it.
+   */
+  main: string | null;
+}
+
+/**
+ * r24: best-effort main-checkout probe — the main checkout is the worktree
+ * holding the default branch. Any git failure (no resolvable default branch,
+ * worktree list failure, outside a repo) yields nulls so callers skip the
+ * warning instead of failing the command.
+ */
+export function probeMainCheckout(git: GitLike): MainCheckoutProbe {
+  try {
+    const def = defaultBranch(git);
+    const here = git.runOpt(['rev-parse', '--show-toplevel']);
+    let main: string | null = null;
+    for (const entry of worktreeList(git)) {
+      if (entry.branch === def) {
+        main = entry.path;
+        break;
+      }
+    }
+    const norm = (p: string | null): string | null => (p === null ? null : p.replace(/\/+$/u, ''));
+    return { defaultBranch: def, here: norm(here), main: norm(main) };
+  } catch {
+    return { defaultBranch: null, here: null, main: null };
+  }
+}
+
+/**
+ * r24: freeze/thaw warning line when executed outside the main checkout —
+ * names the non-main checkout, the possibly-incomplete cold backup, and the
+ * main-checkout recommendation; null when at the main checkout or when the
+ * probe could not resolve the executing worktree at all.
+ */
+export function nonMainCheckoutWarning(probe: MainCheckoutProbe): string | null {
+  if (probe.here === null || probe.here === probe.main) return null;
+  const mainDesc =
+    probe.main !== null
+      ? probe.main
+      : 'not checked out in any worktree (cannot return to a main checkout)';
+  return (
+    `WARNING: this is a non-main checkout (${probe.here}); the main checkout holding ` +
+    `\`${probe.defaultBranch ?? '<unknown>'}\` is: ${mainDesc} — the cold backup may be ` +
+    'incomplete and freeze/thaw effects are only visible in this worktree; ' +
+    'prefer running freeze/thaw from the main checkout'
+  );
+}