dorfl 0.0.0 → 0.1.0

package/src/frontmatter.ts

@@ -0,0 +1,485 @@
+/**
+ * Minimal, dependency-free parser for the small subset of YAML frontmatter the
+ * `work/` contract uses: top-level scalar keys and string lists (inline `[a, b]`
+ * or block `- a` form). It deliberately does NOT implement general YAML — only
+ * what `work/` task frontmatter needs (slug, humanOnly, blockedBy, ...).
+ */
+
+/**
+ * **Origin-trust PROVENANCE** (task `untrusted-origin-forces-build-propose`).
+ * How a prd/task was BORN and the AUTHOR-TRUST verdict at birth, stamped so the
+ * signal SURVIVES the prd/task merge boundary (a landed-on-`main` artifact would
+ * otherwise erase how it was created — the laundering gap).
+ *
+ * - `origin` — `human` (the default / unset: a human authored it locally; a local
+ *   intake with no `--origin-trust` is ALSO this) | `issue` (the CI intake
+ *   front-door stamped it from a public issue).
+ * - `originTrust` — `trusted` | `untrusted`, the `author_association` verdict at
+ *   birth (only meaningful when `origin: issue`). UNSET ⇒ `trusted` (the normal
+ *   human path; ZERO behaviour change). `untrusted` forces the task's BUILD
+ *   transition to `propose` so a human reviews the becomes-code change (an
+ *   explicit `--merge` still overrides — the operator is present).
+ *
+ * `intake.ts` does NOT resolve the trust verdict itself (the `intake.ts` ~L296
+ * boundary: trust is CI's POLICY); the CI shell passes it IN via `--origin-trust`.
+ */
+export type Origin = 'human' | 'issue';
+export type OriginTrust = 'trusted' | 'untrusted';
+
+export interface Frontmatter {
+	/**
+	 * How the artifact was BORN (`human`|`issue`). `undefined` when omitted
+	 * (⇒ `human`/trusted: the normal local-author path, no behaviour change).
+	 * Stamped `issue` by the CI intake front-door so the becomes-code checkpoint is
+	 * not laundered at the merge boundary.
+	 */
+	origin: Origin | undefined;
+	/**
+	 * The author-trust verdict at birth (`trusted`|`untrusted`); only meaningful
+	 * when `origin: issue`. `undefined` when omitted (⇒ `trusted`: the normal path,
+	 * zero behaviour change). An `untrusted` task forces its BUILD transition to
+	 * `propose` (overridable by an explicit `--merge`).
+	 */
+	originTrust: OriginTrust | undefined;
+	/** Content-derived slug id (frontmatter `slug:`). */
+	slug: string | undefined;
+	/**
+	 * Source SPEC slug (frontmatter `spec:`); the spec lives at
+	 * `work/specs/ready/<spec>.md`. The `spec` vocabulary name for the parent-spec
+	 * pointer (prd `prd-to-spec-vocabulary-cutover-and-migration-command`). This is
+	 * the EXPAND-step ADDITION beside {@link prd}: `parseFrontmatter` populates BOTH
+	 * from EITHER the `spec:` OR the `prd:` key with the SAME value, so a caller
+	 * reading either sees the parent-spec slug. The migrate batches move `fm.prd`
+	 * reads onto `fm.spec` one at a time; the contract task removes `prd`.
+	 */
+	spec: string | undefined;
+	/**
+	 * Source spec slug (frontmatter `prd:`); the spec lives at
+	 * `work/specs/ready/<prd>.md`. The LEGACY vocabulary name for the parent-spec
+	 * pointer, kept BESIDE {@link spec} through the expand→migrate→contract cutover
+	 * (prd `prd-to-spec-vocabulary-cutover-and-migration-command`) so every existing
+	 * `fm.prd` reader keeps working; populated from EITHER the `spec:` or `prd:` key.
+	 */
+	prd: string | undefined;
+	/**
+	 * The GitHub issue number an `intake`-emitted artifact was transformed from
+	 * (frontmatter `issue:`). Parsed so the `issue: N` intake writes is
+	 * MACHINE-READABLE — the close JOB (`runner-in-ci`'s) reaches it to resolve the
+	 * issue from folder + field state. Carried on EITHER:
+	 *
+	 * - a **prd** (`intake`'s prd outcome) — a fanned task reaches it via
+	 *   `task.prd: → work/prds/ready/<prd>.md → prd issue:` (the number lives
+	 *   ONLY on the prd, never duplicated across the N fanned tasks); OR
+	 * - a **lone task** (`intake`'s TASK outcome, no `prd:`) — the provider-agnostic
+	 *   closure link for a task that closes its own issue directly (replaces the old
+	 *   GitHub-only `Fixes #N` body line, which is now a deferred optimisation).
+	 *
+	 * INVARIANT — one closure path per task: a task uses `issue:` XOR `prd:`, never
+	 * both. Either it closes its own issue directly (`issue:`) or it contributes to a
+	 * prd that closes the issue (`prd:` → prd `issue:`). This is NOT enforced by a
+	 * throwing validator (there is no frontmatter-validation layer): intake never
+	 * emits both — its task / prd dispatch branches are mutually exclusive — so only
+	 * a human hand-edit could produce both, and the precedence rule (`prd:` wins,
+	 * `issue:` ignored) is the future close-job's concern (see {@link
+	 * resolveClosingIssue}), degrading a typo to "use the prd's number" rather than
+	 * crashing. `undefined` when omitted (every non-intake prd and most tasks).
+	 */
+	issue: number | undefined;
+	/**
+	 * Autonomy gate axis 1 (DECIDED). `true` when the item declares itself
+	 * human-only (a human must drive it regardless of how complete the spec is);
+	 * `undefined` when omitted (undeclared — most items). Present on both tasks
+	 * and prds.
+	 */
+	humanOnly: boolean | undefined;
+	/**
+	 * Autonomy gate axis 2 (DISCOVERED). `true` when the item has unresolved
+	 * questions blocking autonomous progress (the open questions live in the body);
+	 * `undefined` when omitted. Orthogonal to `humanOnly`; present on both tasks
+	 * and prds.
+	 */
+	needsAnswers: boolean | undefined;
+	/**
+	 * The triage SETTLED marker (US #30). A non-empty `triaged:` value (e.g.
+	 * `keep` / `duplicate`) means a human (or the conservative auto-disposition)
+	 * has SETTLED this observation, so it DROPS OUT of the triage candidate pool
+	 * and is never re-asked. `undefined` when omitted (an UNTRIAGED observation,
+	 * still in the pool). Carried so the lifecycle-pool enumeration
+	 * (`advance-autopick-lifecycle-pools`) can exclude settled observations from
+	 * the triage selection.
+	 */
+	triaged: string | undefined;
+	/** Slugs this item is blocked by; `[]` when omitted or empty. */
+	blockedBy: string[];
+	/**
+	 * Prd-only: slugs of prds that must already be TASKED before this prd may be
+	 * tasked (resolved against `work/prds/tasked/` residence, NOT `done/`). `[]` when
+	 * omitted or empty. Parsed here so the auto-tasker can read it; enforcement
+	 * lives in the `auto-slice` capability, not in eligibility.
+	 */
+	taskedAfter: string[];
+	/**
+	 * The per-item override layer for the `promptGuidance` NUDGE namespace
+	 * (task `prompt-guidance-testfirst-item-override`, prd US #5). A task or
+	 * prd may carry one or more `promptGuidance.<member>: true | false`
+	 * frontmatter lines to OVERRIDE the resolved repo policy for THAT ITEM only.
+	 * Each member is `undefined` when omitted (⇒ inherit the next layer down in
+	 * the precedence chain: per-task > per-prd > repo-resolved). The override
+	 * is honoured at the prompt-assembly seam (`prompt.ts`); it never affects
+	 * the `verify` gate.
+	 *
+	 * Parsed from the DOTTED scalar form `promptGuidance.testFirst: true`
+	 * (single-line, mirroring the flat shape `humanOnly`/`needsAnswers` use at the
+	 * item level). A mistyped value (e.g. `"yes"`) reads as `undefined`, the same
+	 * silent-on-malformed behaviour the existing `humanOnly` parsing has — no
+	 * silent coerce to true/false.
+	 */
+	promptGuidance: {testFirst: boolean | undefined};
+}
+
+/**
+ * Extract the raw frontmatter block (the lines between the leading `---` and the
+ * next `---`). Returns `undefined` when the document does not start with a
+ * frontmatter fence.
+ */
+function extractBlock(content: string): string | undefined {
+	const normalized = content.replace(/\r\n/g, '\n').replace(/^\uFEFF/, '');
+	if (!normalized.startsWith('---\n') && normalized !== '---') {
+		return undefined;
+	}
+	const lines = normalized.split('\n');
+	// First line is the opening fence.
+	const closing = lines.indexOf('---', 1);
+	if (closing === -1) {
+		return undefined;
+	}
+	return lines.slice(1, closing).join('\n');
+}
+
+/** Strip surrounding single or double quotes from a scalar token. */
+function unquote(value: string): string {
+	const trimmed = value.trim();
+	if (trimmed.length >= 2) {
+		const first = trimmed[0];
+		const last = trimmed[trimmed.length - 1];
+		if ((first === '"' || first === "'") && last === first) {
+			return trimmed.slice(1, -1);
+		}
+	}
+	return trimmed;
+}
+
+/**
+ * Extract the `[...]` body of a YAML flow-style inline list, IGNORING anything
+ * after the matching closing `]` (notably a trailing `# comment`, the documented
+ * house style on `blockedBy: [] # startable now`). Quote-aware: a `]` inside a
+ * single/double-quoted item is data, not the list terminator. Returns the inner
+ * text (between the brackets), or `undefined` if no matching `]` is found
+ * (malformed — caller treats it as empty).
+ */
+function inlineListInner(value: string): string | undefined {
+	const trimmed = value.trim();
+	if (trimmed[0] !== '[') {
+		return undefined;
+	}
+	let quote: "'" | '"' | undefined;
+	for (let i = 1; i < trimmed.length; i++) {
+		const ch = trimmed[i];
+		if (quote) {
+			if (ch === quote) {
+				quote = undefined;
+			}
+			continue;
+		}
+		if (ch === "'" || ch === '"') {
+			quote = ch;
+			continue;
+		}
+		if (ch === ']') {
+			return trimmed.slice(1, i);
+		}
+	}
+	return undefined;
+}
+
+function parseInlineList(value: string): string[] {
+	const body = inlineListInner(value);
+	if (body === undefined) {
+		return [];
+	}
+	const inner = body.trim();
+	if (inner === '') {
+		return [];
+	}
+	return inner
+		.split(',')
+		.map((item) => unquote(item))
+		.filter((item) => item !== '');
+}
+
+function toBoolean(value: string): boolean | undefined {
+	const v = unquote(value).toLowerCase();
+	if (v === 'true') {
+		return true;
+	}
+	if (v === 'false') {
+		return false;
+	}
+	return undefined;
+}
+
+/**
+ * Set (or clear) the top-level `needsAnswers:` frontmatter marker on a `work/`
+ * markdown document, returning the new content. Used by the tasker review→edit
+ * LOOP's verdict sink (`slicer-review-edit-loop`) to emit a specific uncertain
+ * candidate task as `needsAnswers: true` (open questions block autonomous build;
+ * a human must answer them). If a `needsAnswers:` line already exists it is
+ * REPLACED (idempotent); otherwise it is appended as the last line inside the
+ * frontmatter fence. A document with NO frontmatter fence gets one PREPENDED (see
+ * {@link setFrontmatterMarker}) — observations are born fence-less (the
+ * `capture-signal` skill writes prose), so the tooling-owned `needsAnswers` axis
+ * MUST be settable on them rather than silently dropped.
+ */
+export function setNeedsAnswersMarker(content: string, value: boolean): string {
+	return setFrontmatterMarker(content, 'needsAnswers', String(value));
+}
+
+/**
+ * Set (or replace) a top-level scalar `<key>: <value>` frontmatter marker on a
+ * `work/` markdown document, returning the new content. The generalised form of
+ * {@link setNeedsAnswersMarker} the advance APPLY rung uses to stamp a
+ * `triaged: keep` marker (US #30) on an item a human answered "keep" — so a
+ * settled observation drops out of the candidate pool and is never re-asked. If a
+ * `<key>:` line already exists it is REPLACED (idempotent); otherwise it is
+ * appended as the last line inside the frontmatter fence.
+ *
+ * A document with NO frontmatter fence gets ONE PREPENDED carrying just this
+ * marker (`---\n<key>: <value>\n---\n\n<body>`). This is the load-bearing fix for
+ * `sidecar-without-needsAnswers`: observations are routinely created fence-less
+ * (the `capture-signal` skill writes free-form prose), and the OLD behaviour
+ * silently returned the body UNCHANGED — so `persistSurfacedQuestions` wrote the
+ * sidecar while the `needsAnswers:true` flag it believed it set was discarded,
+ * tearing the `needsAnswers ⟺ active sidecar` invariant a later tick refused to
+ * classify. These markers (`needsAnswers`, `triaged`) are tooling-owned axes, not
+ * prose, so the tool is entitled to introduce the fence it needs.
+ *
+ * The ONE remaining return-unchanged case is a MALFORMED doc that opens a fence
+ * (`---\n`) but never closes it: rewriting that risks corrupting hand-authored
+ * content, so it is left untouched (a degenerate input no writer produces).
+ */
+export function setFrontmatterMarker(
+	content: string,
+	key: string,
+	value: string,
+): string {
+	const normalized = content.replace(/\r\n/g, '\n');
+	if (!normalized.startsWith('---\n')) {
+		// Fence-less document: PREPEND a minimal fence carrying just this marker,
+		// preserving the body verbatim (no leading blank between fence and body is
+		// collapsed — exactly one blank line separates the fence from the content).
+		const body = normalized.replace(/^\n+/, '');
+		return `---\n${key}: ${value}\n---\n\n${body}`;
+	}
+	const lines = normalized.split('\n');
+	const closing = lines.indexOf('---', 1);
+	if (closing === -1) {
+		// Malformed: an opening fence with no close. Leave it untouched rather than
+		// risk corrupting hand-authored content.
+		return content;
+	}
+	const pattern = new RegExp(`^${key}\\s*:`);
+	for (let i = 1; i < closing; i++) {
+		if (pattern.test(lines[i])) {
+			lines[i] = `${key}: ${value}`;
+			return lines.join('\n');
+		}
+	}
+	lines.splice(closing, 0, `${key}: ${value}`);
+	return lines.join('\n');
+}
+
+/**
+ * PROPAGATE the origin-trust PROVENANCE (`origin` + `originTrust`) from a SOURCE
+ * artifact (a prd) onto a TARGET artifact's content (an emitted task), returning
+ * the new content (task `untrusted-origin-forces-build-propose`). The tasker
+ * calls this so a task born from an untrusted-origin prd carries the stamp the
+ * BUILD transition reads. IDEMPOTENT: each present source field is written via
+ * {@link setFrontmatterMarker} (replace-or-append). When the source has NO `origin`
+ * (a human/local-authored prd ⇒ trusted), the target is returned UNCHANGED — the
+ * normal path is never stamped (zero behaviour change). When a stamp IS applied to
+ * a fence-less target, {@link setFrontmatterMarker} now prepends a fence to carry
+ * it (tasks the tasker emits always have a fence, so this is the defensive path).
+ */
+export function propagateOrigin(
+	source: Pick<Frontmatter, 'origin' | 'originTrust'>,
+	targetContent: string,
+): string {
+	if (source.origin === undefined && source.originTrust === undefined) {
+		return targetContent;
+	}
+	let next = targetContent;
+	if (source.origin !== undefined) {
+		next = setFrontmatterMarker(next, 'origin', source.origin);
+	}
+	if (source.originTrust !== undefined) {
+		next = setFrontmatterMarker(next, 'originTrust', source.originTrust);
+	}
+	return next;
+}
+
+export function parseFrontmatter(content: string): Frontmatter {
+	const block = extractBlock(content);
+	const result: Frontmatter = {
+		origin: undefined,
+		originTrust: undefined,
+		slug: undefined,
+		spec: undefined,
+		prd: undefined,
+		issue: undefined,
+		humanOnly: undefined,
+		needsAnswers: undefined,
+		triaged: undefined,
+		blockedBy: [],
+		taskedAfter: [],
+		promptGuidance: {testFirst: undefined},
+	};
+	if (block === undefined) {
+		return result;
+	}
+
+	const lines = block.split('\n');
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		// Skip blank lines and comments and non top-level (indented) lines; block
+		// list items are consumed inline below.
+		if (line.trim() === '' || line.trimStart().startsWith('#')) {
+			continue;
+		}
+		// Top-level keys are alphanumeric / `_`; the dot is allowed so the per-item
+		// override for the `promptGuidance` namespace can be parsed in its DOTTED
+		// scalar form (e.g. `promptGuidance.testFirst: true`) without introducing a
+		// nested-mapping parser.
+		const match = /^([A-Za-z0-9_.]+)\s*:\s*(.*)$/.exec(line);
+		if (!match) {
+			continue;
+		}
+		const key = match[1];
+		const rawValue = match[2].trim();
+
+		if (key === 'origin') {
+			// Provenance: how the artifact was born. Only the known values map;
+			// anything else (or empty) reads as undefined (⇒ the human/trusted default).
+			const v = unquote(rawValue).toLowerCase();
+			result.origin = v === 'human' || v === 'issue' ? v : undefined;
+		} else if (key === 'originTrust') {
+			// The author-trust verdict at birth. Only the known values map; anything
+			// else (or empty) reads as undefined (⇒ trusted, the zero-change default).
+			const v = unquote(rawValue).toLowerCase();
+			result.originTrust = v === 'trusted' || v === 'untrusted' ? v : undefined;
+		} else if (key === 'slug') {
+			result.slug = rawValue === '' ? undefined : unquote(rawValue);
+		} else if (key === 'spec' || key === 'prd') {
+			// EXPAND step (prd `prd-to-spec-vocabulary-cutover-and-migration-command`):
+			// the parent-spec pointer is written under EITHER the new `spec:` key or the
+			// legacy `prd:` key. Populate BOTH `fm.spec` and `fm.prd` with the same value
+			// so a caller reading either field sees it. `spec:` wins if both are present
+			// (the canonical key takes precedence over the legacy alias); an empty value
+			// on one key does NOT clobber a non-empty value already read from the other.
+			const value = rawValue === '' ? undefined : unquote(rawValue);
+			if (key === 'spec') {
+				// The canonical key wins: overwrite whatever `prd:` may have set.
+				if (value !== undefined) {
+					result.spec = value;
+					result.prd = value;
+				}
+			} else if (result.spec === undefined) {
+				// Legacy `prd:` only fills in when `spec:` has not already set the pair.
+				result.spec = value;
+				result.prd = value;
+			}
+		} else if (key === 'issue') {
+			// Integer issue link (`intake`'s prd-emit OR a lone-task emit). A
+			// non-integer / empty value reads as undefined (the field is absent rather
+			// than malformed).
+			const n = Number(unquote(rawValue));
+			result.issue =
+				rawValue !== '' && Number.isInteger(n) && n > 0 ? n : undefined;
+		} else if (key === 'promptGuidance.testFirst') {
+			// Per-item override for the `promptGuidance.testFirst` nudge. An empty or
+			// malformed value reads as `undefined` (⇒ inherit the next layer), the
+			// same silent-on-malformed shape `humanOnly` uses — never a silent coerce.
+			result.promptGuidance.testFirst =
+				rawValue === '' ? undefined : toBoolean(rawValue);
+		} else if (key === 'humanOnly') {
+			result.humanOnly = rawValue === '' ? undefined : toBoolean(rawValue);
+		} else if (key === 'needsAnswers') {
+			result.needsAnswers = rawValue === '' ? undefined : toBoolean(rawValue);
+		} else if (key === 'triaged') {
+			// The SETTLED marker: a non-empty value (`keep`/`duplicate`) drops the
+			// observation out of the triage pool. An empty value reads as undefined
+			// (undeclared — still untriaged).
+			result.triaged = rawValue === '' ? undefined : unquote(rawValue);
+		} else if (key === 'blockedBy' || key === 'taskedAfter') {
+			let list: string[];
+			if (rawValue.startsWith('[')) {
+				list = parseInlineList(rawValue);
+			} else if (rawValue === '') {
+				// Block-style list: consume following indented `- item` lines.
+				const items: string[] = [];
+				let j = i + 1;
+				while (j < lines.length) {
+					const itemMatch = /^\s+-\s*(.+)$/.exec(lines[j]);
+					if (!itemMatch) {
+						break;
+					}
+					const item = unquote(itemMatch[1]);
+					if (item !== '') {
+						items.push(item);
+					}
+					j++;
+				}
+				list = items;
+				i = j - 1;
+			} else {
+				list = [];
+			}
+			if (key === 'blockedBy') {
+				result.blockedBy = list;
+			} else {
+				result.taskedAfter = list;
+			}
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Resolve, from a parsed artifact's frontmatter, HOW it closes its source issue:
+ * the `prd:` hop or the lone-task `issue:` field. A PURE helper for the FUTURE
+ * CI close-job (`runner-in-ci`'s) — it is NOT wired into intake or any reader
+ * today; it merely pins the one-closure-path PRECEDENCE in one place.
+ *
+ * Encodes the invariant: a task uses `issue:` XOR `prd:`. When (only a human
+ * hand-edit could) BOTH are present, `prd:` WINS — the close-job hops to the prd's
+ * `issue:` and IGNORES the task's own `issue:` (the fanned-prd path is the
+ * authoritative one; a lone `issue:` on a `prd:`-bearing task is a contradiction
+ * that degrades to "use the prd" rather than crashing).
+ *
+ * Returns:
+ * - `{via: 'spec', spec}` when a `spec:` is present (hop to the spec's `issue:`; the
+ *   caller resolves the spec file to read its number);
+ * - `{via: 'issue', issue}` when only a lone-task `issue:` is present;
+ * - `undefined` when neither is present (no closure path).
+ */
+export function resolveClosingIssue(
+	frontmatter: Pick<Frontmatter, 'spec' | 'issue'>,
+): {via: 'spec'; spec: string} | {via: 'issue'; issue: number} | undefined {
+	if (frontmatter.spec !== undefined) {
+		return {via: 'spec', spec: frontmatter.spec};
+	}
+	if (frontmatter.issue !== undefined) {
+		return {via: 'issue', issue: frontmatter.issue};
+	}
+	return undefined;
+}

package/src/gate-readiness.ts

@@ -0,0 +1,147 @@
+import {existsSync} from 'node:fs';
+import {join} from 'node:path';
+import {run} from './git.js';
+import {resolvePrepareCommands, type PrepareConfig} from './prepare.js';
+
+/**
+ * Pre-claim / pre-build startup GUARD for the fresh-worktree acceptance gate
+ * (task `do-fails-fast-when-acceptance-gate-statically-unrunnable`).
+ *
+ * The fresh-worktree gate (`gate-on-rebased-tip-fresh-worktree`, ON by default)
+ * runs `prepare` then `verify` in a CLEAN throwaway worktree with NO
+ * `node_modules`. If `prepare` resolves to no commands AND the repo has a
+ * lockfile (evidence that an install IS required), the gate will provably fail
+ * with "command not found" — a STATICALLY-detectable misconfiguration we can
+ * surface at second zero, BEFORE wasting a claim + agent build + a routed
+ * needs-attention.
+ *
+ * Critical non-regression: `prepare` resolving to no commands is a DELIBERATE
+ * no-op (`prepare.ts`: "a repo with no deps needs none; we never invent a
+ * default that would run `pnpm install` in a repo that has no lockfile"). So
+ * the guard KEYS off LOCKFILE-PRESENT evidence — never off `prepare`-unset
+ * alone — and a genuinely dep-free repo (no lockfile) PROCEEDS unchanged.
+ *
+ * There is NO "verify unset" case: {@link resolveVerifyCommands} substitutes
+ * `DEFAULT_VERIFY_COMMAND` when `verify` is unset OR all-blank, so `verify` is
+ * NEVER statically unrunnable-because-unset. A "verify unset → STOP" guard
+ * would be dead code (or fire wrongly on the default). The guard is deps-only.
+ *
+ * The guard is also gated on `freshWorktreeGate === true` for THIS invocation:
+ * when the gate is OFF (`--no-fresh-worktree-gate`) the acceptance gate runs in
+ * the agent's BUILD worktree (which HAS deps), so the throwaway-worktree
+ * reasoning does not apply.
+ */
+
+/**
+ * The lockfile basenames whose presence implies an install is required. Order
+ * is the search order (first match wins — its basename is the one named in the
+ * guard message).
+ */
+export const LOCKFILE_BASENAMES = [
+	'pnpm-lock.yaml',
+	'package-lock.json',
+	'yarn.lock',
+] as const;
+
+/**
+ * Probe `cwd` for one of {@link LOCKFILE_BASENAMES} on disk and return the
+ * first match (or `undefined`). The standard probe for the in-place / job-
+ * worktree paths where the repo is materialised on disk.
+ */
+export function detectLockfileOnDisk(cwd: string): string | undefined {
+	return LOCKFILE_BASENAMES.find((name) => existsSync(join(cwd, name)));
+}
+
+/**
+ * Probe a BARE mirror's `main` ref via `git ls-tree` for one of
+ * {@link LOCKFILE_BASENAMES} and return the first match (or `undefined`). Used
+ * by the no-checkout `do --remote` path, which has no working tree until AFTER
+ * the claim; this lets the guard fire BEFORE the claim. Best-effort: a missing
+ * `main` ref or a failing `git ls-tree` returns `undefined` (the guard then
+ * stays quiet and any genuine plumbing error surfaces later as a usage error).
+ */
+export function detectLockfileOnMirrorMain(
+	mirrorPath: string,
+	env?: NodeJS.ProcessEnv,
+): string | undefined {
+	const res = run(
+		'git',
+		['ls-tree', '--name-only', 'main', ...LOCKFILE_BASENAMES],
+		mirrorPath,
+		{env},
+	);
+	if (res.status !== 0) {
+		return undefined;
+	}
+	const present = new Set(
+		res.stdout
+			.split('\n')
+			.map((line) => line.trim())
+			.filter((line) => line !== ''),
+	);
+	return LOCKFILE_BASENAMES.find((name) => present.has(name));
+}
+
+export interface GatePreconditionInput {
+	/**
+	 * The resolved fresh-worktree-gate flag for THIS invocation
+	 * (flag > env > per-repo > global > default `true`). The guard ONLY fires when
+	 * this is exactly `true` — `false`/`undefined` ⇒ the throwaway-worktree
+	 * reasoning does not apply and the guard returns `undefined`.
+	 */
+	freshWorktreeGate: boolean | undefined;
+	/** The resolved `prepare` config (unset / string / list). */
+	prepare?: PrepareConfig;
+	/**
+	 * The lockfile basename probed for this repo (one of
+	 * {@link LOCKFILE_BASENAMES}), or `undefined` for the intentional dep-free
+	 * case. The caller picks the probe ({@link detectLockfileOnDisk} for the
+	 * in-place / job-worktree paths, {@link detectLockfileOnMirrorMain} for the
+	 * no-checkout `do --remote` path).
+	 */
+	lockfile: string | undefined;
+}
+
+export interface GatePreconditionFailure {
+	/** The lockfile basename (from {@link LOCKFILE_BASENAMES}) that tripped the guard. */
+	lockfile: string;
+	/** A precise, actionable error message naming the lockfile and the two ways out. */
+	message: string;
+}
+
+/**
+ * Check the fresh-worktree-gate startup preconditions. Returns the failure
+ * (with a precise message) when the gate is STATICALLY unrunnable for the
+ * deps-only reason; returns `undefined` otherwise (proceed normally).
+ *
+ * NOTE — deps-only, not verify-presence: see the file-level doc.
+ */
+export function checkGatePreconditions(
+	input: GatePreconditionInput,
+): GatePreconditionFailure | undefined {
+	// Gate OFF for THIS invocation ⇒ no throwaway worktree ⇒ the deps reasoning
+	// does not apply. (The default is ON; the guard fires when ON.)
+	if (input.freshWorktreeGate !== true) {
+		return undefined;
+	}
+	// `prepare` resolves to at least one command ⇒ the throwaway worktree will
+	// install (or codegen, etc.); not statically unrunnable. Covers BOTH `prepare`
+	// unset AND an all-blank list returning `[]` via the SAME `resolvePrepareCommands`.
+	if (resolvePrepareCommands(input.prepare).length > 0) {
+		return undefined;
+	}
+	// No lockfile ⇒ the intentional dep-free repo (the design point preserved):
+	// `prepare` unset is a DELIBERATE no-op and `verify` runs against a repo that
+	// needs no install — proceed.
+	if (input.lockfile === undefined) {
+		return undefined;
+	}
+	return {
+		lockfile: input.lockfile,
+		message:
+			'the fresh-worktree gate is on but no `prepare` step is configured, ' +
+			`and a lockfile (${input.lockfile}) is present — the throwaway worktree ` +
+			'will have no installed deps, so the gate cannot run. Add a `prepare` ' +
+			'(e.g. `pnpm install --frozen-lockfile`) or pass --no-fresh-worktree-gate.',
+	};
+}