@cleocode/core 2026.9.9 → 2026.9.10

package/dist/git/work-tree.d.ts

@@ -1,6 +1,7 @@
 /**
- * Whether a directory can host a `git`/`gh` evidence invocation, and what to
- * say when it cannot (gh#1462).
+ * Whether a directory can host a `git`/`gh` evidence invocation, which tree to
+ * run in when the CLEO root is not itself a checkout, and what to say when no
+ * tree can be found (gh#1462).
  *
  * `pr:` and `commit:` atoms shell out to `gh` / `git` from a working directory.
  * `gh` does its OWN repo discovery: it walks up from its cwd and, finding no
@@ -30,35 +31,139 @@
  */
 export declare const E_EVIDENCE_GIT_ROOT: "E_EVIDENCE_GIT_ROOT";
 /**
- * True when `dir` is inside a git work tree — its own checkout or a descendant
- * of one, since git walks up. False when the directory is missing, is not a
- * work tree, or `git` itself cannot be spawned.
+ * Environment variable naming the checkout that evidence tools must run in.
+ *
+ * The CLEO-specific override, and the one the failure message points at. It
+ * beats every other signal because it is the only one that can only have been
+ * set on purpose for this invocation.
+ *
+ * @task T12308
+ */
+export declare const EVIDENCE_GIT_ROOT_ENV = "CLEO_EVIDENCE_GIT_ROOT";
+/**
+ * True when `dir` is inside a git work tree of its own — its own checkout or a
+ * descendant of one, since git walks up. False when the directory is missing,
+ * is not a work tree, or `git` itself cannot be spawned.
+ *
+ * Ambient `GIT_DIR`/`GIT_WORK_TREE` are ignored on purpose; see
+ * {@link GIT_AMBIENT_REPO_VARS}.
  *
  * @param dir - Directory the tools would run in.
  * @task gh#1462
  */
 export declare function isGitWorkTree(dir: string): boolean;
+/**
+ * Absolute toplevel of the checkout containing `dir`, or `null` when there is
+ * none.
+ *
+ * @param dir - Directory to resolve from.
+ * @task T12308
+ */
+export declare function gitToplevel(dir: string): string | null;
+/**
+ * Every git work tree directly below `dir`, in stable sorted order.
+ *
+ * One level only, on purpose. A CLEO root that parents its checkouts — the
+ * layout gh#1462 reports — has the repositories as direct children, while a
+ * recursive search would descend into `node_modules` and vendored trees.
+ * Dot-directories are skipped so `.cleo/`, `.git/` and editor state are never
+ * candidates.
+ *
+ * @param dir - Candidate parent directory (the CLEO store root).
+ * @returns Canonical absolute paths; empty when there are none.
+ * @task T12308
+ */
+export declare function findNestedGitWorkTrees(dir: string): string[];
 /**
  * The single git work tree directly below `dir`, or `null` when there is none
  * or more than one.
  *
- * One level only, on purpose. A CLEO root that parents its checkout — the
- * layout gh#1462 reports — has the repository as a direct child, while a
- * recursive search would descend into `node_modules` and vendored trees and
- * would still have to guess which repository a `pr:` atom was about. Ambiguity
- * returns `null` so the caller can report it instead of picking one.
+ * Ambiguity returns `null` so the caller can report it — or disambiguate with
+ * {@link findWorkTreeContainingCommit} — instead of picking one.
  *
  * @param dir - Candidate parent directory (the CLEO store root).
  * @task gh#1462
  */
 export declare function findNestedGitWorkTree(dir: string): string | null;
 /**
- * Reason text for {@link E_EVIDENCE_GIT_ROOT}: names the directory that was
- * tried and the two environment variables that pin a checkout CLEO could not
- * find on its own.
+ * The one candidate checkout that contains `sha`, or `null` when none or
+ * several do.
+ *
+ * This is what makes a multi-repo CLEO root resolvable WITHOUT configuration:
+ * a `commit:` atom is a statement about exactly one repository, and "which of
+ * these checkouts has this object" has a single correct answer almost always.
+ * Several matches (shared history) or none stay unresolved rather than being
+ * guessed, so the caller reports the ambiguity.
+ *
+ * @param candidates - Checkouts to search, e.g. from {@link findNestedGitWorkTrees}.
+ * @param sha - Commit SHA the evidence is about.
+ * @task T12308
+ */
+export declare function findWorkTreeContainingCommit(candidates: readonly string[], sha: string): string | null;
+/** An evidence git root the operator declared, and where the declaration came from. */
+export interface DeclaredEvidenceGitRoot {
+    /** Absolute path exactly as declared (resolved against the store root when relative). */
+    path: string;
+    /** Human-readable provenance, used verbatim in failure text. */
+    source: string;
+}
+/**
+ * The checkout the operator declared for evidence execution, if any.
+ *
+ * Precedence, most to least specific:
+ *
+ *  1. `CLEO_EVIDENCE_GIT_ROOT` — set for this invocation, for this purpose.
+ *  2. `GIT_WORK_TREE` — git's own override, and the one the old failure text
+ *     advertised. It is honoured by RUNNING in that tree, which is the part
+ *     that was missing: setting it alone never helped, because every tool
+ *     still ran with its cwd at the CLEO root.
+ *  3. `.cleo/project-context.json` → `evidence.gitRoot` — the durable,
+ *     committed answer for a root that parents several repositories.
+ *
+ * The result is NOT validated here. A declared path that is not a work tree
+ * must fail loudly and by name rather than falling back to a different tree
+ * and attesting against it, so validation belongs to the caller's guard.
+ *
+ * @param storeRoot - CLEO store root; relative declarations resolve against it.
+ * @param env - Environment to read. Defaults to the current process env.
+ * @task T12308
+ */
+export declare function resolveDeclaredEvidenceGitRoot(storeRoot: string, env?: NodeJS.ProcessEnv): DeclaredEvidenceGitRoot | null;
+/** Context that makes {@link describeMissingGitWorkTree} name the actual fix. */
+export interface MissingGitWorkTreeContext {
+    /** CLEO store root, when it differs from the directory that was tried. */
+    storeRoot?: string;
+    /** Checkouts found directly below the store root. */
+    candidates?: readonly string[];
+    /** Provenance of a declared root that turned out not to be a work tree. */
+    declaredFrom?: string;
+}
+/**
+ * Reason text for {@link E_EVIDENCE_GIT_ROOT}.
+ *
+ * The previous text offered `GIT_DIR`/`GIT_WORK_TREE` as the remedy. That
+ * advice could not work: the guard asks whether the *current directory* is
+ * inside a work tree, and the CLEO root never is, so following it produced the
+ * identical error and left the reader with nothing to try. Every branch here
+ * therefore names a remedy that has a test proving it resolves the layout.
  *
  * @param dir - Directory the tools would have run in.
+ * @param context - What else is known about the layout.
  * @task gh#1462
+ * @task T12308
+ */
+export declare function describeMissingGitWorkTree(dir: string, context?: MissingGitWorkTreeContext): string;
+/**
+ * The complete {@link E_EVIDENCE_GIT_ROOT} reason for a store root whose
+ * resolved execution root turned out not to be a checkout.
+ *
+ * Composed here, beside the resolution inputs it reports on, so the message
+ * and the resolution order cannot drift apart: a declaration that was honoured
+ * is named, otherwise the sibling checkouts that made the choice ambiguous are.
+ *
+ * @param storeRoot - Absolute CLEO store root.
+ * @param executionRoot - Root the tools would have run in.
+ * @task T12308
  */
-export declare function describeMissingGitWorkTree(dir: string): string;
+export declare function describeUnusableEvidenceGitRoot(storeRoot: string, executionRoot: string): string;
 //# sourceMappingURL=work-tree.d.ts.map

package/dist/git/work-tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"work-tree.d.ts","sourceRoot":"","sources":["../../src/git/work-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAG,qBAA8B,CAAC;AAElE;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAWlD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAqBhE;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ9D"}
+{"version":3,"file":"work-tree.d.ts","sourceRoot":"","sources":["../../src/git/work-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAG,qBAA8B,CAAC;AAElE;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAgE9D;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAgB5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,CAQf;AAED,uFAAuF;AACvF,MAAM,WAAW,uBAAuB;IACtC,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;CAChB;AA4BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,uBAAuB,GAAG,IAAI,CAmBhC;AAED,iFAAiF;AACjF,MAAM,WAAW,yBAAyB;IACxC,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,yBAA8B,GACtC,MAAM,CA8CR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,+BAA+B,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAOhG"}

package/dist/git/work-tree.js

@@ -1,6 +1,7 @@
 /**
- * Whether a directory can host a `git`/`gh` evidence invocation, and what to
- * say when it cannot (gh#1462).
+ * Whether a directory can host a `git`/`gh` evidence invocation, which tree to
+ * run in when the CLEO root is not itself a checkout, and what to say when no
+ * tree can be found (gh#1462).
  *
  * `pr:` and `commit:` atoms shell out to `gh` / `git` from a working directory.
  * `gh` does its OWN repo discovery: it walks up from its cwd and, finding no
@@ -19,8 +20,8 @@
  * @task gh#1462
  */
 import { execFileSync } from 'node:child_process';
-import { existsSync, readdirSync, realpathSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
 /**
  * Error code for "no git work tree at or above the evidence execution root".
  *
@@ -33,79 +34,308 @@ import { join } from 'node:path';
  */
 export const E_EVIDENCE_GIT_ROOT = 'E_EVIDENCE_GIT_ROOT';
 /**
- * True when `dir` is inside a git work tree — its own checkout or a descendant
- * of one, since git walks up. False when the directory is missing, is not a
- * work tree, or `git` itself cannot be spawned.
+ * Environment variable naming the checkout that evidence tools must run in.
  *
- * @param dir - Directory the tools would run in.
- * @task gh#1462
+ * The CLEO-specific override, and the one the failure message points at. It
+ * beats every other signal because it is the only one that can only have been
+ * set on purpose for this invocation.
+ *
+ * @task T12308
  */
-export function isGitWorkTree(dir) {
+export const EVIDENCE_GIT_ROOT_ENV = 'CLEO_EVIDENCE_GIT_ROOT';
+/**
+ * Git's own repo-pointing variables, removed before any DISCOVERY probe.
+ *
+ * `git rev-parse --is-inside-work-tree` answers about the *ambient* repository
+ * when `GIT_DIR`/`GIT_WORK_TREE` are set, not about `dir`. That is precisely
+ * what made the remediation this module used to print unusable: from a parent
+ * of the checkout, `GIT_DIR=<repo>/.git GIT_WORK_TREE=<repo> git rev-parse
+ * --is-inside-work-tree` prints `false` (cwd is outside the declared tree) and
+ * exits 0, so the guard rejected the very layout the advice was meant to fix.
+ *
+ * Probes therefore ask the unambiguous question — "is THIS directory in a
+ * checkout of its own" — and the declared roots are honoured explicitly, by
+ * {@link resolveDeclaredEvidenceGitRoot}, rather than by hoping git's ambient
+ * state happens to agree.
+ *
+ * @task T12308
+ */
+const GIT_AMBIENT_REPO_VARS = [
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_COMMON_DIR',
+    'GIT_INDEX_FILE',
+    'GIT_OBJECT_DIRECTORY',
+];
+/**
+ * A copy of `env` with git's ambient repo-pointing variables removed.
+ *
+ * @param env - Source environment. Defaults to the current process env.
+ * @returns Environment safe for directory-discovery probes.
+ * @task T12308
+ */
+function discoveryEnv(env = process.env) {
+    const copy = { ...env };
+    for (const key of GIT_AMBIENT_REPO_VARS)
+        delete copy[key];
+    return copy;
+}
+/** Run a `git` probe in `dir`, returning trimmed stdout or `null` on any failure. */
+function gitProbe(dir, args) {
     try {
-        const out = execFileSync('git', ['rev-parse', '--is-inside-work-tree'], {
+        const out = execFileSync('git', [...args], {
             cwd: dir,
             encoding: 'utf-8',
+            env: discoveryEnv(),
             stdio: ['ignore', 'pipe', 'ignore'],
         });
-        return out.trim() === 'true';
+        return out.trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve symlinks where possible, falling back to a plain absolute path. */
+function canonical(path) {
+    try {
+        return realpathSync(path);
     }
     catch {
-        return false;
+        return resolve(path);
     }
 }
 /**
- * The single git work tree directly below `dir`, or `null` when there is none
- * or more than one.
+ * True when `dir` is inside a git work tree of its own — its own checkout or a
+ * descendant of one, since git walks up. False when the directory is missing,
+ * is not a work tree, or `git` itself cannot be spawned.
  *
- * One level only, on purpose. A CLEO root that parents its checkout — the
- * layout gh#1462 reports — has the repository as a direct child, while a
- * recursive search would descend into `node_modules` and vendored trees and
- * would still have to guess which repository a `pr:` atom was about. Ambiguity
- * returns `null` so the caller can report it instead of picking one.
+ * Ambient `GIT_DIR`/`GIT_WORK_TREE` are ignored on purpose; see
+ * {@link GIT_AMBIENT_REPO_VARS}.
  *
- * @param dir - Candidate parent directory (the CLEO store root).
+ * @param dir - Directory the tools would run in.
  * @task gh#1462
  */
-export function findNestedGitWorkTree(dir) {
+export function isGitWorkTree(dir) {
+    return gitProbe(dir, ['rev-parse', '--is-inside-work-tree']) === 'true';
+}
+/**
+ * Absolute toplevel of the checkout containing `dir`, or `null` when there is
+ * none.
+ *
+ * @param dir - Directory to resolve from.
+ * @task T12308
+ */
+export function gitToplevel(dir) {
+    const top = gitProbe(dir, ['rev-parse', '--show-toplevel']);
+    return top === null || top.length === 0 ? null : canonical(top);
+}
+/**
+ * Every git work tree directly below `dir`, in stable sorted order.
+ *
+ * One level only, on purpose. A CLEO root that parents its checkouts — the
+ * layout gh#1462 reports — has the repositories as direct children, while a
+ * recursive search would descend into `node_modules` and vendored trees.
+ * Dot-directories are skipped so `.cleo/`, `.git/` and editor state are never
+ * candidates.
+ *
+ * @param dir - Candidate parent directory (the CLEO store root).
+ * @returns Canonical absolute paths; empty when there are none.
+ * @task T12308
+ */
+export function findNestedGitWorkTrees(dir) {
     let entries;
     try {
         entries = readdirSync(dir);
     }
     catch {
-        return null;
+        return [];
     }
     const found = [];
     for (const entry of entries) {
         if (entry.startsWith('.'))
             continue;
+        if (entry === 'node_modules')
+            continue;
         const child = join(dir, entry);
         if (!existsSync(join(child, '.git')))
             continue;
-        found.push(child);
+        found.push(canonical(child));
     }
-    const only = found[0];
-    if (only === undefined || found.length !== 1)
+    return found.sort();
+}
+/**
+ * The single git work tree directly below `dir`, or `null` when there is none
+ * or more than one.
+ *
+ * Ambiguity returns `null` so the caller can report it — or disambiguate with
+ * {@link findWorkTreeContainingCommit} — instead of picking one.
+ *
+ * @param dir - Candidate parent directory (the CLEO store root).
+ * @task gh#1462
+ */
+export function findNestedGitWorkTree(dir) {
+    const found = findNestedGitWorkTrees(dir);
+    return found.length === 1 ? found[0] : null;
+}
+/**
+ * The one candidate checkout that contains `sha`, or `null` when none or
+ * several do.
+ *
+ * This is what makes a multi-repo CLEO root resolvable WITHOUT configuration:
+ * a `commit:` atom is a statement about exactly one repository, and "which of
+ * these checkouts has this object" has a single correct answer almost always.
+ * Several matches (shared history) or none stay unresolved rather than being
+ * guessed, so the caller reports the ambiguity.
+ *
+ * @param candidates - Checkouts to search, e.g. from {@link findNestedGitWorkTrees}.
+ * @param sha - Commit SHA the evidence is about.
+ * @task T12308
+ */
+export function findWorkTreeContainingCommit(candidates, sha) {
+    if (!/^[0-9a-f]{7,40}$/i.test(sha))
         return null;
+    const matches = [];
+    for (const candidate of candidates) {
+        if (gitProbe(candidate, ['cat-file', '-e', `${sha}^{commit}`]) !== null)
+            matches.push(candidate);
+    }
+    return matches.length === 1 ? matches[0] : null;
+}
+/**
+ * Read `evidence.gitRoot` out of `.cleo/project-context.json`.
+ *
+ * Parsed here with a bare `readFileSync` rather than through
+ * `loadProjectContext` so this module stays a leaf: the evidence resolver is
+ * synchronous and sits below the agents layer, and a static import back into
+ * it would close a cycle. A malformed or absent file simply yields `null` —
+ * this tier has always been optional.
+ *
+ * @param storeRoot - CLEO store root holding `.cleo/`.
+ * @task T12308
+ */
+function readConfiguredGitRoot(storeRoot) {
     try {
-        return realpathSync(only);
+        const raw = readFileSync(join(storeRoot, '.cleo', 'project-context.json'), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        const evidence = parsed.evidence;
+        if (evidence === null || typeof evidence !== 'object' || Array.isArray(evidence))
+            return null;
+        const gitRoot = evidence.gitRoot;
+        return typeof gitRoot === 'string' && gitRoot.trim().length > 0 ? gitRoot.trim() : null;
     }
     catch {
-        return only;
+        return null;
     }
 }
 /**
- * Reason text for {@link E_EVIDENCE_GIT_ROOT}: names the directory that was
- * tried and the two environment variables that pin a checkout CLEO could not
- * find on its own.
+ * The checkout the operator declared for evidence execution, if any.
+ *
+ * Precedence, most to least specific:
+ *
+ *  1. `CLEO_EVIDENCE_GIT_ROOT` — set for this invocation, for this purpose.
+ *  2. `GIT_WORK_TREE` — git's own override, and the one the old failure text
+ *     advertised. It is honoured by RUNNING in that tree, which is the part
+ *     that was missing: setting it alone never helped, because every tool
+ *     still ran with its cwd at the CLEO root.
+ *  3. `.cleo/project-context.json` → `evidence.gitRoot` — the durable,
+ *     committed answer for a root that parents several repositories.
+ *
+ * The result is NOT validated here. A declared path that is not a work tree
+ * must fail loudly and by name rather than falling back to a different tree
+ * and attesting against it, so validation belongs to the caller's guard.
+ *
+ * @param storeRoot - CLEO store root; relative declarations resolve against it.
+ * @param env - Environment to read. Defaults to the current process env.
+ * @task T12308
+ */
+export function resolveDeclaredEvidenceGitRoot(storeRoot, env = process.env) {
+    const fromEnv = (key) => {
+        const value = env[key]?.trim();
+        if (value === undefined || value.length === 0)
+            return null;
+        return {
+            path: isAbsolute(value) ? value : resolve(storeRoot, value),
+            source: `${key}=${value}`,
+        };
+    };
+    const explicit = fromEnv(EVIDENCE_GIT_ROOT_ENV) ?? fromEnv('GIT_WORK_TREE');
+    if (explicit !== null)
+        return explicit;
+    const configured = readConfiguredGitRoot(storeRoot);
+    if (configured === null)
+        return null;
+    return {
+        path: isAbsolute(configured) ? configured : resolve(storeRoot, configured),
+        source: `.cleo/project-context.json evidence.gitRoot="${configured}"`,
+    };
+}
+/**
+ * Reason text for {@link E_EVIDENCE_GIT_ROOT}.
+ *
+ * The previous text offered `GIT_DIR`/`GIT_WORK_TREE` as the remedy. That
+ * advice could not work: the guard asks whether the *current directory* is
+ * inside a work tree, and the CLEO root never is, so following it produced the
+ * identical error and left the reader with nothing to try. Every branch here
+ * therefore names a remedy that has a test proving it resolves the layout.
  *
  * @param dir - Directory the tools would have run in.
+ * @param context - What else is known about the layout.
  * @task gh#1462
+ * @task T12308
  */
-export function describeMissingGitWorkTree(dir) {
-    return (`No git work tree at or above ${dir}, so git and gh cannot run there. ` +
+export function describeMissingGitWorkTree(dir, context = {}) {
+    const { storeRoot, candidates = [], declaredFrom } = context;
+    if (declaredFrom !== undefined) {
+        return (`Declared evidence git root ${dir} (from ${declaredFrom}) is not a git work tree, ` +
+            `so git and gh cannot run there. CLEO honours the declaration rather than ` +
+            `silently measuring a different checkout. Point it at a directory that is ` +
+            `inside a git repository, or unset it to let CLEO resolve one.`);
+    }
+    const head = `No git work tree at or above ${dir}, so git and gh cannot run there. ` +
         `This is a directory/layout problem — not a failing PR, a missing commit, ` +
-        `or a broken gh. If the checkout lives elsewhere, point the tools at it ` +
-        `explicitly: GIT_DIR=<repo>/.git GIT_WORK_TREE=<repo> cleo verify ... ` +
+        `or a broken gh.`;
+    if (candidates.length > 1) {
+        const root = storeRoot ?? dir;
+        return (`${head} The CLEO root ${root} parents ${candidates.length} checkouts ` +
+            `(${candidates.join(', ')}), and this atom does not say which one it is about, ` +
+            `so CLEO will not guess. Declare it once, durably, by adding to ` +
+            `${join(root, '.cleo', 'project-context.json')}: ` +
+            `"evidence": { "gitRoot": "<subdirectory>" } — or, for a single invocation, ` +
+            `${EVIDENCE_GIT_ROOT_ENV}=<repo> cleo verify ... . ` +
+            `(A commit: atom naming a SHA that exists in exactly one of these checkouts ` +
+            `resolves automatically and needs no configuration.)`);
+    }
+    if (candidates.length === 1) {
+        return (`${head} The one checkout below the CLEO root, ${candidates[0]}, could not be used. ` +
+            `Run the command from inside it, or declare it with ` +
+            `${EVIDENCE_GIT_ROOT_ENV}=${candidates[0]}.`);
+    }
+    return (`${head} No checkout was found below the CLEO root either. If the repository ` +
+        `lives elsewhere, declare it: ${EVIDENCE_GIT_ROOT_ENV}=<repo> cleo verify ... , ` +
+        `or add "evidence": { "gitRoot": "<path>" } to ` +
+        `${join(storeRoot ?? dir, '.cleo', 'project-context.json')} ` +
         `(or run the command from inside the checkout).`);
 }
+/**
+ * The complete {@link E_EVIDENCE_GIT_ROOT} reason for a store root whose
+ * resolved execution root turned out not to be a checkout.
+ *
+ * Composed here, beside the resolution inputs it reports on, so the message
+ * and the resolution order cannot drift apart: a declaration that was honoured
+ * is named, otherwise the sibling checkouts that made the choice ambiguous are.
+ *
+ * @param storeRoot - Absolute CLEO store root.
+ * @param executionRoot - Root the tools would have run in.
+ * @task T12308
+ */
+export function describeUnusableEvidenceGitRoot(storeRoot, executionRoot) {
+    const declared = resolveDeclaredEvidenceGitRoot(storeRoot);
+    return describeMissingGitWorkTree(executionRoot, {
+        storeRoot,
+        candidates: findNestedGitWorkTrees(storeRoot),
+        ...(declared === null ? {} : { declaredFrom: declared.source }),
+    });
+}
 //# sourceMappingURL=work-tree.js.map

package/dist/git/work-tree.js.map

@@ -1 +1 @@
-{"version":3,"file":"work-tree.js","sourceRoot":"","sources":["../../src/git/work-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,qBAA8B,CAAC;AAElE;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,uBAAuB,CAAC,EAAE;YACtE,GAAG,EAAE,GAAG;YACR,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACpC,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,IAAI,EAAE,KAAK,MAAM,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QACpC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC/B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAAE,SAAS;QAC/C,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACpB,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACtB,IAAI,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1D,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAW;IACpD,OAAO,CACL,gCAAgC,GAAG,oCAAoC;QACvE,2EAA2E;QAC3E,yEAAyE;QACzE,uEAAuE;QACvE,gDAAgD,CACjD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"work-tree.js","sourceRoot":"","sources":["../../src/git/work-tree.ts"],"names":[],"mappings":"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"}

package/dist/internal.d.ts

@@ -324,6 +324,7 @@ export { validateLabels } from './tasks/add.js';
 export { computeTaskView, computeTaskViews } from './tasks/compute-task-view.js';
 export { type AtomValidation, CALLSITE_COVERAGE_LABEL, CANONICAL_TOOLS, checkCallsiteCoverageAtom, checkEngineMigrationLocDrop, checkGateEvidenceMinimum, checkGateEvidenceMinimumDetailed, composeGateEvidence, ENGINE_MIGRATION_MIN_REDUCTION_PCT, type EvidenceTool, GATE_EVIDENCE_MINIMUMS, isValidToolName, type ParsedAtom, type ParsedEvidence, parseEvidence, type RevalidateOptions, type RevalidationResult, revalidateEvidence, TOOL_COMMANDS, VALID_TOOLS, validateAtom, } from './tasks/evidence.js';
 export { appendForceBypassLine, appendGateAuditLine, type ForceBypassRecord, type GateAuditRecord, getForceBypassPath, getGateAuditPath, } from './tasks/gate-audit.js';
+export { previewTaskGates, type TaskGatePreview } from './tasks/gate-preview.js';
 export type { RunGatesOptions } from './tasks/gate-runner.js';
 export { extractTypedGates, runGates } from './tasks/gate-runner.js';
 export type { BuildGenericTreeOptions, GenericTreeEdgeType, GenericTreeMetadata, GenericTreeResult, } from './tasks/generic-tree.js';