dorfl 0.0.0 → 0.1.0

package/src/mint-adr.ts

@@ -0,0 +1,362 @@
+import {readFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {run, type RunResult} from './git.js';
+import {
+	createItemThroughCas,
+	type CasContentionBudget,
+	type CreateItemThroughCasResult,
+} from './advancing-lock.js';
+import {resolveSidecarIdentity, sidecarPathFor} from './sidecar.js';
+
+/**
+ * The **ADR-MINT route** (prd
+ * `agentic-question-resolution-retire-disposition-vocabulary` US #2, task
+ * `agentic-apply-mint-adr-route`) — the SIBLING of {@link
+ * import('./triage-persist.js').promoteObservation}, for the agentic apply
+ * `mint-adr` verdict.
+ *
+ * Why a SIBLING and not an `adr` artifact type on `promoteObservation`
+ * (recorded `## Decisions`): `promoteObservation` is `work/`-folder-SHAPED — it
+ * targets `work/tasks/ready` / `work/prds/proposed` via `workItemRel`, and builds
+ * a task/prd body (a `## What to build` / `## Problem Statement` lead + an
+ * `## Open questions` block, with `needsAnswers` carried). An ADR is DIFFERENT in
+ * EVERY one of those: it lives in `docs/adr/` (OUTSIDE the work board, so the
+ * `work/`-layout path builder does not fit), it carries NO `needsAnswers`/open-
+ * questions block (an ADR records a SETTLED decision, the antithesis of an open
+ * question), and its body is the ADR-FORMAT shape (a context/decision/why record).
+ * Forking the body+target branch inside `promoteObservation` would make that
+ * function mean two unrelated things; a sibling that REUSES the shared CAS-create
+ * primitive (and nothing else) is the cleaner seam.
+ *
+ * It REUSES the keystone's guarantees verbatim, because both go through the SAME
+ * {@link createItemThroughCas} primitive (the new-item-creation CAS from
+ * `advancing-lock-borrow`): the source observation + its answered sidecar are
+ * `git rm`-ed IN THE SAME atomic commit as the ADR create (delete-on-promote),
+ * and a CAS LOSER — which never reaches the commit — backs off WITHOUT deleting
+ * the source (left intact for a retry). The ONLY differences from
+ * `promoteObservation` are the TARGET path (`docs/adr/<slug>.md`) and the BODY
+ * shape (the ADR record).
+ */
+
+function gitSoft(
+	args: string[],
+	cwd: string,
+	env: NodeJS.ProcessEnv | undefined,
+): RunResult {
+	return run('git', args, cwd, {env});
+}
+
+function resolveBy(cwd: string, env: NodeJS.ProcessEnv | undefined): string {
+	const name = gitSoft(['config', 'user.name'], cwd, env);
+	if (name.status === 0 && name.stdout.trim() !== '') {
+		return name.stdout.trim();
+	}
+	const e = env ?? process.env;
+	return e.USER ?? e.USERNAME ?? '';
+}
+
+/** Read the observation body from the tree (committed) then the working file. */
+function readItem(
+	cwd: string,
+	itemPath: string,
+	env: NodeJS.ProcessEnv | undefined,
+): string {
+	const show = gitSoft(['show', `:${itemPath}`], cwd, env);
+	if (show.status === 0) {
+		return show.stdout;
+	}
+	try {
+		return readFileSync(join(cwd, itemPath), 'utf8');
+	} catch {
+		throw new MintAdrError(
+			`cannot read observation body for '${itemPath}' (the ADR-mint route needs the item file)`,
+		);
+	}
+}
+
+/** Raised for usage errors (an empty slug, an unreadable observation). */
+export class MintAdrError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'MintAdrError';
+	}
+}
+
+/**
+ * The repo-relative `docs/adr/` home for minted ADRs. ADRs live OUTSIDE the
+ * `work/` governance tree (so they are NOT in `work-layout.ts`'s registry); this
+ * is the single literal the route roots its target on. `docs/adr/` is created
+ * lazily by {@link createItemThroughCas} (it `mkdir -p`s the target's dirname).
+ */
+export const ADR_DIR_REL = 'docs/adr';
+
+/** The repo-relative path of a minted ADR file: `docs/adr/<slug>.md`. */
+export function adrItemRel(slug: string): string {
+	return `${ADR_DIR_REL}/${slug}.md`;
+}
+
+export interface MintAdrOptions {
+	/** Working clone/worktree the mint runs in. */
+	cwd: string;
+	/** The namespaced source identity (`observation:<slug>`). */
+	item: string;
+	/** The source item file path RELATIVE to `cwd` (e.g. `work/notes/observations/foo.md`). */
+	itemPath: string;
+	/**
+	 * The ADR slug to draft. Defaults to the source observation's own slug, so the
+	 * minted ADR is `docs/adr/<obs-slug>.md`. The CAS is keyed on the new ADR's
+	 * PATH, so a same-slug ADR race ⇒ the loser fails the CAS and backs off.
+	 */
+	adrSlug?: string;
+	/**
+	 * The ADR's short title (the `# {title}` heading line). Defaults to the slug
+	 * when absent.
+	 */
+	adrTitle?: string;
+	/**
+	 * The ADR's content — the markdown AFTER the frontmatter (the
+	 * context/decision/why record). When omitted, a SELF-CONTAINED body is built
+	 * FROM the source observation + its answered question(s) (see
+	 * {@link buildAdrBody}), so the decision's WHY is carried in and the source is
+	 * safely deletable.
+	 */
+	adrBody?: string;
+	/**
+	 * The answered question(s) + answers the decision rests on, carried into the
+	 * built body's Context/Decision when no explicit `adrBody` is supplied (so the
+	 * minted ADR is self-contained even without an agent-drafted body).
+	 */
+	answers?: {question: string; answer: string}[];
+	/** Name of the arbiter remote (`--arbiter`). Defaults to `origin`. */
+	arbiter?: string;
+	/** Advisory committer id for the commit subject. Defaults to git user.name. */
+	by?: string;
+	/** Environment for child git processes. */
+	env?: NodeJS.ProcessEnv;
+	/** Show the intended CAS push without mutating the arbiter (`--dry-run`). */
+	dryRun?: boolean;
+	/**
+	 * The CAS CONTENTION-RETRY BUDGET (jittered inter-retry delay + widened
+	 * attempt / wall-clock envelope). Threaded through to
+	 * {@link createItemThroughCas}. The lifecycle driver passes
+	 * `LIFECYCLE_CAS_CONTENTION` here so a propose-tick FAN-OUT of parallel
+	 * `mint-adr` legs desynchronises and DRAINS instead of thrashing to `contended`.
+	 * Absent ⇒ the interactive default (3 retries, no delay).
+	 */
+	contention?: CasContentionBudget;
+	/** Sink for human-readable progress notes. */
+	note?: (message: string) => void;
+}
+
+export interface MintAdrResult {
+	/**
+	 * `minted` (the ADR landed via the CAS + the observation+sidecar were deleted
+	 * in the SAME commit), `lost` (the same-slug ADR race was lost — the loser backs
+	 * off, observation left INTACT), or `contended` (the CAS push kept failing).
+	 * Maps onto the claim-CAS exit codes.
+	 */
+	outcome: 'minted' | 'lost' | 'contended' | 'usage-error';
+	exitCode: 0 | 1 | 2 | 3;
+	/** The new ADR's path (relative to repo root) on a WIN. */
+	adrPath?: string;
+	/** A human-readable summary. */
+	message: string;
+}
+
+/**
+ * Mint a NEW, SELF-CONTAINED ADR FROM an answered observation (the agentic apply
+ * `mint-adr` verdict, US #2): CAS-create `docs/adr/<slug>.md` keyed on the new
+ * ADR's identity (its path), with the source observation + its answered sidecar
+ * `git rm`-ed IN THE SAME atomic commit. The mint is ONE commit (create + delete).
+ *
+ * The minted body is built FROM the source + the answered question(s) (see
+ * {@link buildAdrBody}) so an engineer can read the decision's WHY from the ADR
+ * ALONE — that self-containment is the PRECONDITION for the same-commit deletion
+ * of the source. An agent-drafted `adrBody` (when present) is used verbatim.
+ *
+ * The CAS-create is the new-item-creation helper ({@link createItemThroughCas}):
+ * a same-slug ADR race needs NO special case — exactly one creator lands the
+ * file, the LOSER fails the CAS (exit 2) and backs off WITHOUT deleting the
+ * source (so a retry can re-mint). The source (+ its sidecar) is deleted ONLY on a
+ * WIN, riding the winning creator's commit.
+ */
+export async function mintAdr(options: MintAdrOptions): Promise<MintAdrResult> {
+	const {cwd, item, itemPath, env} = options;
+	const note = options.note ?? (() => {});
+
+	const {slug: obsSlug} = resolveSidecarIdentity(item);
+	const adrSlug = (options.adrSlug ?? obsSlug).trim();
+	if (adrSlug === '') {
+		return {
+			outcome: 'usage-error',
+			exitCode: 1,
+			message: `mint-adr ${item}: empty ADR slug — cannot draft an ADR`,
+		};
+	}
+
+	const adrPath = adrItemRel(adrSlug);
+	const by = options.by || resolveBy(cwd, env);
+	const title = (options.adrTitle ?? adrSlug).trim() || adrSlug;
+	const content =
+		options.adrBody !== undefined && options.adrBody.trim() !== ''
+			? renderAdrFile(adrSlug, title, options.adrBody.trim())
+			: buildAdrBody({
+					slug: adrSlug,
+					title,
+					observation: readItem(cwd, itemPath, env),
+					answers: options.answers ?? [],
+				});
+
+	// The source note + its answered sidecar `git rm` IN THE SAME create commit
+	// (mint = ONE atomic commit). A CAS LOSER never reaches the commit, so it
+	// leaves both INTACT for a retry (the loser-backs-off guarantee, over deletion).
+	const sidecarPath = sidecarPathFor(item);
+
+	const created: CreateItemThroughCasResult = await createItemThroughCas({
+		path: adrPath,
+		content,
+		deletePaths: [itemPath, sidecarPath],
+		cwd,
+		arbiter: options.arbiter,
+		by,
+		dryRun: options.dryRun,
+		env,
+		note,
+		...(options.contention !== undefined
+			? {contention: options.contention}
+			: {}),
+	});
+	if (created.exitCode !== 0) {
+		const message =
+			`mint-adr ${item}: the new ADR ${adrPath} ${created.outcome} the ` +
+			`create CAS (${created.message}) — backing off, the observation is left ` +
+			'intact for a retry.';
+		note(message);
+		return {
+			outcome: created.outcome === 'lost' ? 'lost' : 'contended',
+			exitCode: created.exitCode,
+			message,
+		};
+	}
+
+	const message =
+		`minted ${item} → CREATED ${adrPath} (via the CAS) + DELETED the ` +
+		'observation + its sidecar in the same commit.';
+	note(message);
+	return {outcome: 'minted', exitCode: 0, adrPath, message};
+}
+
+/**
+ * Build a SELF-CONTAINED ADR file FROM an answered observation + its answer(s),
+ * in the repo's existing `docs/adr/` shape (recorded `## Decisions`): a `---`
+ * frontmatter fence (`title` / `status: accepted` / `created`) then a
+ * `# ADR: {title}` heading and the three ADR-FORMAT sections — **Context**
+ * (the source signal that prompted the decision), **Decision** (what was decided,
+ * from the human's answer), and **Why** (the rationale the answer carries). The
+ * decision's WHY is carried IN (the answer prose), so the ADR reads alone — the
+ * precondition for deleting the source in the same commit.
+ *
+ * The mechanism prose of the observation (everything before its first
+ * `## Open questions` heading, frontmatter dropped) seeds Context; the
+ * question(s)+answer(s) seed Decision + Why. When no answers are threaded the
+ * Decision/Why fall back to the observation's prose so the file is never empty.
+ */
+export function buildAdrBody(input: {
+	slug: string;
+	title: string;
+	observation: string;
+	answers: {question: string; answer: string}[];
+}): string {
+	const context = mechanismOf(input.observation).trim();
+	const decisionLines: string[] = [];
+	const whyLines: string[] = [];
+	for (const {question, answer} of input.answers) {
+		const q = question.trim();
+		const a = answer.trim();
+		if (q !== '' || a !== '') {
+			decisionLines.push(`- **${q || '(question)'}** — ${a || '(no answer)'}`);
+			if (a !== '') {
+				whyLines.push(a);
+			}
+		}
+	}
+	const body: string[] = [
+		'## Context',
+		'',
+		context === ''
+			? '(no source context was carried from the observation.)'
+			: context,
+		'',
+		'## Decision',
+		'',
+		decisionLines.length > 0
+			? decisionLines.join('\n')
+			: '(the decision is recorded in the source context above.)',
+		'',
+		'## Why',
+		'',
+		whyLines.length > 0
+			? whyLines.join('\n\n')
+			: 'The decision follows directly from the answered question(s) above; the source signal is preserved in this ADR (the note itself leaves by deletion, git history is the archive).',
+		'',
+	];
+	return renderAdrFile(input.slug, input.title, body.join('\n'));
+}
+
+/**
+ * Wrap an ADR `body` (the markdown AFTER the frontmatter) in the repo's existing
+ * ADR file shape: a `---` frontmatter fence (`title` / `status: accepted` /
+ * `created`) then a `# ADR: {title}` heading, then the body. Mirrors the existing
+ * `docs/adr/*.md` convention (slug-named files with a frontmatter block), NOT the
+ * `NNNN-` numeric prefix the ADR-FORMAT template shows — the repo's LIVE
+ * convention wins (recorded `## Decisions`).
+ */
+function renderAdrFile(slug: string, title: string, body: string): string {
+	const date = new Date().toISOString().slice(0, 10);
+	return [
+		'---',
+		`title: ${title}`,
+		'status: accepted',
+		`created: ${date}`,
+		'---',
+		'',
+		`# ADR: ${title}`,
+		'',
+		body.replace(/\s*$/, ''),
+		'',
+	].join('\n');
+}
+
+/**
+ * The observation's mechanism PROSE: everything before its first
+ * `## Open questions` heading, with the frontmatter fence dropped. An ADR records
+ * a SETTLED decision, so an observation's open-questions scoping is deliberately
+ * NOT carried into the ADR body (unlike a promoted task/prd, which keeps the
+ * open questions live) — the answered question(s) ARE the decision.
+ */
+function mechanismOf(observation: string): string {
+	const body = stripFrontmatter(observation);
+	const lines = body.split('\n');
+	const startIdx = lines.findIndex((l) => /^##\s+Open questions\b/i.test(l));
+	if (startIdx === -1) {
+		return body;
+	}
+	return lines.slice(0, startIdx).join('\n');
+}
+
+/** Strip a leading `---\n…\n---` frontmatter fence, returning the body. */
+function stripFrontmatter(content: string): string {
+	const normalized = content.replace(/\r\n/g, '\n').replace(/^\uFEFF/, '');
+	if (!normalized.startsWith('---\n')) {
+		return normalized;
+	}
+	const lines = normalized.split('\n');
+	const closing = lines.indexOf('---', 1);
+	if (closing === -1) {
+		return normalized;
+	}
+	return lines
+		.slice(closing + 1)
+		.join('\n')
+		.replace(/^\n+/, '');
+}

package/src/mirror-pool-scan.ts

@@ -0,0 +1,240 @@
+import type {Config} from './config.js';
+import {ledgerRead, type LedgerReadStrategy} from './ledger-read.js';
+import {resolveRepoConfigFromMirror} from './repo-mirror.js';
+import {
+	scoreItems,
+	scoreSpecs,
+	toScannedLifecycle,
+	type ScannedItem,
+	type ScanReport,
+	type RepoReport,
+} from './scan.js';
+import {
+	taskableSpecs,
+	type SpecCandidate,
+	type SelectedLifecyclePools,
+} from './select-priority.js';
+import {gatherLifecycleMirror} from './lifecycle-gather.js';
+import type {LifecyclePoolGates} from './lifecycle-pools.js';
+import {heldTaskSlugs} from './item-lock.js';
+
+/**
+ * The MIRROR-SIDE eligible-pool scan — the isolated counterpart to
+ * `do-autopick`'s in-place pool scan ({@link performDoAuto}). It enumerates the
+ * SAME two pools (eligible TASKS + taskable PRDS) but reads a BARE hub mirror's
+ * committed `main` ref (`git ls-tree`/`git show`), NOT a working checkout.
+ *
+ * This is the ONE reusable enumeration unit the prd's FOLD-IN note demands: BOTH
+ * the `run` loop driver's isolated+parallel auto-pick AND the one-shot/CI
+ * `advance --remote -n` / the CI matrix consume it, so the `-n`/auto-pick rungs
+ * (both `do` and `advance`, both `run`-loop and one-shot) all call the SAME scan.
+ * A standalone `do --remote -n` then falls out as a thin caller — the scan is NOT
+ * invented twice (the existing inline `-n`×`--remote` REFUSAL in `cli.ts` is the
+ * placeholder this scan replaces; removing the refusal is the driver/caller's job).
+ *
+ * It only ENUMERATES the pool — it never claims, builds, or runs anything. `-n`
+ * stays ALWAYS SEQUENTIAL (US #25): the selection layer ({@link selectPrioritised})
+ * orders + counts; parallelism comes only from `run`'s concurrent loop or the CI
+ * matrix, never from this scan or from `-n`.
+ *
+ * It is the MIRROR-ref counterpart of `do-autopick`'s in-place scan, reusing the
+ * exact predicates rather than re-deriving them:
+ *
+ *   - **tasks** — {@link scoreItems} (the SAME eligibility scoring the in-place
+ *     `scanRepoPaths`/registry `scan` use) over the mirror's `work/backlog` +
+ *     `work/done` read via {@link LedgerReadStrategy.resolveMirrorState}.
+ *   - **taskable prds** — {@link taskableSpecs} (`autoslice-gate`'s predicate)
+ *     over the mirror's `work/prds/ready` + `work/prds/tasked` read via the mirror-ref
+ *     {@link LedgerReadStrategy.resolveMirrorSpecPool}.
+ *
+ * Per-repo policy parity: a bare mirror has no checked-out `.dorfl.json`,
+ * but the COMMITTED one is reachable on `main` (the `do --remote` per-repo seam).
+ * We layer it via {@link resolveRepoConfigFromMirror} so the same logical `work/`
+ * state yields the SAME `autoBuild`/`autoTask` decision an in-place checkout
+ * would — that is what makes the mirror scan PARITY-equal to the in-place one.
+ */
+
+/** What {@link scanMirrorPool} needs: which bare mirror + the global config. */
+export interface ScanMirrorPoolOptions {
+	/** The bare hub mirror directory (`<workspacesDir>/repos/<key>.git`). */
+	mirrorPath: string;
+	/**
+	 * The global + default config layer. The repo's COMMITTED `.dorfl.json`
+	 * (read from the mirror's `main`) is layered on top, so `autoBuild`/`autoTask`
+	 * resolve per-repo exactly as the in-place scan resolves them from the checkout.
+	 */
+	config: Config;
+	/**
+	 * The mirror-LOCAL ref whose `work/` tree to read (default `main`). A bare hub
+	 * mirror's `main` is a LOCAL branch — never `origin/main`.
+	 */
+	ref?: string;
+	/**
+	 * Override the read seam (tests inject a stub). Defaults to the active
+	 * {@link ledgerRead} — the SAME seam the in-place scan reads through.
+	 */
+	read?: LedgerReadStrategy;
+	/**
+	 * Sink for a non-fatal per-repo-config read warning. The scan must never error
+	 * out on a config-read fault — it falls back to global + default (the
+	 * no-per-repo behaviour) and warns. (Fetch-first freshness is the CALLER's job,
+	 * exactly as it is for the registry `scan`; this reads the already-fetched ref.)
+	 */
+	warn?: (message: string) => void;
+	env?: NodeJS.ProcessEnv;
+	/**
+	 * The LIFECYCLE-POOL create-gates (task `advance-autopick-lifecycle-pools`),
+	 * the internal hook the gate tasks will wire to `observationTriage` /
+	 * `surfaceBlockers`. INTERIM, born OFF: omitted ⇒ BOTH create-gates OFF, so the
+	 * mirror-side triage + surface sub-pools contribute NOTHING (the apply sub-pool
+	 * is always-on). The mirror enumeration mirrors the in-place one exactly.
+	 */
+	lifecycleGates?: LifecyclePoolGates;
+	/**
+	 * The per-machine config-override map (ADR
+	 * `per-machine-config-override-layer`), threaded into the mirror-side per-repo
+	 * resolution so the override applies to the autopick pool scan. Default: empty.
+	 */
+	override?: import('./config-override.js').ConfigOverrideMap;
+}
+
+/**
+ * The enumerated mirror-side pool — the isolated counterpart of `do-autopick`'s
+ * two pools. Both drivers feed `report` + `prds` into the SAME
+ * {@link selectPrioritised} (the loop driver takes all; the one-shot/CI driver
+ * bounds by a SEQUENTIAL `count`).
+ */
+export interface MirrorPoolScanResult {
+	/**
+	 * The task pool as a one-repo {@link ScanReport} (the mirror is the single
+	 * repo), scored through {@link scoreItems} — the SAME shape
+	 * {@link selectPrioritised} consumes for the in-place scan, so the task
+	 * selection is byte-identical to `run`'s.
+	 */
+	report: ScanReport;
+	/** Every scanned task (eligible or not), in scan order. */
+	tasks: ScannedItem[];
+	/** Just the eligible subset of {@link tasks} (convenience for assertions/callers). */
+	eligibleTasks: ScannedItem[];
+	/**
+	 * The TASKABLE SPEC pool — already filtered through `taskableSpecs`
+	 * (`autoslice-gate`'s predicate). In declaration order; the selection layer
+	 * does not re-gate it.
+	 */
+	specs: SpecCandidate[];
+	/**
+	 * The LIFECYCLE pools (task `advance-autopick-lifecycle-pools`): untriaged
+	 * observations (triage), `needsAnswers`-blocked items with no all-answered
+	 * sidecar (surface), and answered-sidecar items (apply). Built through the SAME
+	 * shared {@link buildLifecyclePools} unit the in-place caller uses (NOT a second
+	 * enumeration), so the in-place + mirror-side selections AGREE. The create-gates
+	 * default OFF (interim); apply is always present. The drivers feed this straight
+	 * into {@link selectPrioritised}'s `lifecycle` slot.
+	 */
+	lifecycle: SelectedLifecyclePools;
+}
+
+/**
+ * Run the mirror-side eligible-pool scan over a single bare hub mirror. Reads
+ * both pools from its committed `main`, scores/filters them through the EXACT
+ * in-place predicates, and returns the shape both drivers consume.
+ */
+export async function scanMirrorPool(
+	options: ScanMirrorPoolOptions,
+): Promise<MirrorPoolScanResult> {
+	const {mirrorPath, config, ref = 'main', env} = options;
+	const read = options.read ?? ledgerRead;
+	const warn = options.warn;
+
+	// Per-repo policy parity: layer the COMMITTED `.dorfl.json` from the
+	// mirror's `main` (the `do --remote` per-repo seam) onto global. Never fatal —
+	// a config-less repo or a read fault falls back to global + default.
+	let repoConfig: Config;
+	try {
+		repoConfig = resolveRepoConfigFromMirror({
+			mirrorPath,
+			global: config,
+			env,
+			override: options.override,
+		});
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		warn?.(
+			`could not read the target repo's config from ${mirrorPath}/main; ` +
+				`resolving from global + default. ${reason}`,
+		);
+		repoConfig = config;
+	}
+
+	// Pool 1 — eligible TASKS from the bare mirror's `work/backlog`+`work/done`,
+	// scored through the EXACT same `scoreItems` the in-place/registry scans use.
+	const state = await read.resolveMirrorState({mirrorPath, ref, env});
+	const counts = {totalItems: 0, totalEligible: 0};
+	// HELD-SLUG SUBTRACTION (prd `ledger-status-per-item-lock-refs` US #15): a bare
+	// hub mirror's arbiter is its `origin`; read the held lock refs from there and
+	// exclude those slugs from the enumerated `backlog/` pool. Non-fatal (empty set
+	// on any fault) and redundant-but-harmless while the body still moves — wired now
+	// so task #9 needs no reader change. Freshness (fetch-first) is the CALLER's job
+	// for the pool ref, exactly as it is for the config read; `heldTaskSlugs` does
+	// its own lock-ref fetch.
+	const heldSlugs = await heldTaskSlugs(mirrorPath, 'origin', env);
+	const items = scoreItems(state, repoConfig.autoBuild, counts, heldSlugs);
+	// Pool 2 — TASKABLE PRDS from the bare mirror's `work/prds/ready`+`work/prds/tasked`,
+	// filtered through `autoslice-gate`'s predicate (NOT reinvented). Read FIRST so
+	// we can populate the `specs[]` companion of `items[]` on the RepoReport below.
+	const pool = await read.resolveMirrorSpecPool({mirrorPath, ref, env});
+	const specs = taskableSpecs({
+		candidates: pool.specs.map((p) => ({
+			repoPath: mirrorPath,
+			slug: p.slug,
+			humanOnly: p.humanOnly,
+			needsAnswers: p.needsAnswers,
+			taskedAfter: p.taskedAfter,
+		})),
+		taskedSlugs: pool.taskedSlugs,
+		autoTask: repoConfig.autoTask,
+	});
+	// The one-slug-one-folder LINT is a HUMAN-FACING surface (`scan`/`status`); this
+	// mirror-side pool scan exists only to SCORE the task/prd candidate pools for
+	// autonomous selection, never to render a dashboard, so it carries an empty lint
+	// (the duplicate surface is the user-facing `scan`/`status`, per the task). The
+	// `specs[]` companion of `items[]` is filled via the SAME `scoreSpecs` helper
+	// `scan`/`scanRepoPaths` call — so the propose-matrix `jq` (`repos[].specs[] |
+	// select(.eligibility.eligible)`) sees the same shape on every surface.
+	// Pools 3 + 4 — the LIFECYCLE pools, gathered from the SAME mirror `main` (the
+	// `needsAnswers` backlog/prds + their sidecars + `work/notes/observations/`) and built
+	// through the SHARED enumeration unit the in-place caller uses — so the in-place
+	// + mirror-side selections AGREE. Create-gates default OFF (interim); apply
+	// (consume) is always present.
+	const lifecycle = await gatherLifecycleMirror({
+		mirrorPath,
+		ref,
+		read,
+		gates: options.lifecycleGates,
+		env,
+	});
+
+	const repo: RepoReport = {
+		path: mirrorPath,
+		items,
+		specs: scoreSpecs(mirrorPath, pool, repoConfig.autoTask),
+		// The propose-matrix lifecycle pool on this mirror's `RepoReport` — the SAME
+		// `gatherLifecycleMirror` result projected onto the `scan --json` shape, so
+		// the dashboard/matrix surface agrees with the selection scoring below.
+		lifecycle: toScannedLifecycle(lifecycle),
+		ledgerDuplicates: [],
+	};
+	const report: ScanReport = {
+		repos: [repo],
+		totalItems: counts.totalItems,
+		totalEligible: counts.totalEligible,
+	};
+
+	return {
+		report,
+		tasks: items,
+		eligibleTasks: items.filter((i) => i.eligibility.eligible),
+		specs,
+		lifecycle,
+	};
+}