dorfl 0.5.1 → 0.7.0

package/src/integration-core.ts

@@ -36,6 +36,47 @@ import {git, run, runAsync, type RunResult} from './git.js';
 import {realSleep, type Sleep} from './retry-backoff.js';
 import {workBranchRef} from './slug-namespace.js';
 import {isAncestor} from './gc.js';
+import {
+	detectColocatedSidecars,
+	formatSidecarGuardReason,
+} from './sidecar-guard.js';
+
+/**
+ * Build the human-facing CONTEXT tail appended to an `acceptance gate failed`
+ * reason — the load-bearing fix for the opaque `acceptance gate failed (exit N)`
+ * bounce message (a maintainer could not tell WHICH command failed or WHY without
+ * re-running the whole gate). Given the failed command + its output tail (both
+ * from {@link RunVerifyResult}), it produces a compact, deterministic block:
+ *
+ *   - names the FAILED command (`the failing step was: \`<cmd>\``), so a
+ *     multi-command gate (`build && test && format:check`) points at the culprit;
+ *   - quotes the last lines of that command's output (the ACTUAL error, e.g.
+ *     "no changesets were found"), so the answer surface carries real signal;
+ *   - when neither is known (an older result / a prepare failure) it returns the
+ *     empty string — the caller's base reason is unchanged (graceful degrade).
+ *
+ * PURE + seam-free (string in, string out) so it is unit-testable and reused by
+ * every gate-failure site (front gate, rebased-tip fresh gate, committed
+ * recovery). The output is bounded by {@link RunVerifyResult.outputTail}'s own
+ * cap, so it can never bloat the surfaced sidecar.
+ */
+export function formatGateFailureContext(params: {
+	failedCommand?: string;
+	outputTail?: string;
+}): string {
+	const {failedCommand, outputTail} = params;
+	const parts: string[] = [];
+	if (failedCommand !== undefined && failedCommand.trim() !== '') {
+		parts.push(`the failing step was: \`${failedCommand.trim()}\``);
+	}
+	if (outputTail !== undefined && outputTail.trim() !== '') {
+		parts.push(`its last output was:\n\n${outputTail.trimEnd()}`);
+	}
+	if (parts.length === 0) {
+		return '';
+	}
+	return ` — ${parts.join('; ')}`;
+}
 
 /**
  * **The shared gate→integrate BACK-HALF** of the per-item pipeline, extracted out
@@ -92,6 +133,7 @@ export type IntegrationCoreOutcome =
 	| 'review-blocked' // Gate 2 (PR/code review) returned `block` (or exhausted rounds)
 	| 'review-unparseable' // Gate 2 ran but its verdict JSON could not be parsed (malformed output) — work-preserving route, transient-infra cause (NOT a reviewer block)
 	| 'rebase-conflict' // rebase onto arbiter/main conflicted (aborted; human resolves)
+	| 'sidecar-violation' // a co-located <slug>/ sidecar sits beside a flowing task/spec item (WORK-CONTRACT rule 8) — HARD BLOCK before the durable move
 	| 'invariant-violation' // one-slug-one-folder would break (slug in two folders on the arbiter)
 	| 'already-integrated'; // committed-recovery: the kept tip is already on <arbiter>/main (clean no-op)
 
@@ -854,7 +896,15 @@ export async function performIntegration(
 			// reason on the lock entry, no `in-progress/ → needs-attention/` folder
 			// move) plus saving the agent's uncommitted work as a wip commit. No
 			// partial state.
-			const reason = `acceptance gate failed (exit ${gate.exitCode})`;
+			// Enrich the surfaced reason with WHICH gate command failed + the tail of
+			// its output (the actual error), so the needs-attention question is
+			// actionable instead of a bare exit code.
+			const reason =
+				`acceptance gate failed (exit ${gate.exitCode})` +
+				formatGateFailureContext({
+					failedCommand: gate.failedCommand,
+					outputTail: gate.outputTail,
+				});
 			const routed = await ledgerWrite.applyNeedsAttentionTransition({
 				cwd,
 				slug,
@@ -933,6 +983,61 @@ export async function performIntegration(
 		});
 	}
 
+	// 1c. CO-LOCATED SIDECAR GUARD (WORK-CONTRACT.md rule 8). A `<slug>/` asset
+	//     sidecar co-located with a FLOWING task/spec item strands on the
+	//     `ready → done` / `ready → tasked` `git mv` (the `<slug>.md` moves, the
+	//     `<slug>/` folder is left behind — one item split across two status folders,
+	//     the SAME one-slug-one-folder invariant `ledger-lint`/the integration core
+	//     enforce). So this is a HARD BLOCK at LAND, BEFORE the durable move: a
+	//     detected sidecar routes the item to needs-attention via the SAME
+	//     `applyNeedsAttentionTransition` seam the red gate / review block use, with
+	//     an ACTIONABLE relocate-to-`docs/spikes/<slug>/` reason. A `notes/*` sidecar
+	//     is NOT scanned (notes do not flow), and the `work/questions/*`
+	//     status-mechanism file is not an item sidecar — so neither false-positives.
+	//     Runs for BOTH the build and the tasking (`lifecycle`) transitions: either
+	//     way a flowing item is about to be `git mv`'d and would strand a sidecar.
+	//     ROUTING: the BUILD path routes here (the task lock the `applyNeedsAttention
+	//     Transition` seam keys on — `task:<slug>` — is the one `claim` holds); the
+	//     TASKING (`lifecycle`) path does its OWN spec-lock routing in `tasking.ts`
+	//     from `reviewBlockReason` (exactly as the review-blocked tasking path does),
+	//     so here it only RETURNS the reason without touching a `task:` lock that a
+	//     tasking run never held.
+	const colocatedSidecars = detectColocatedSidecars(cwd, slug);
+	if (colocatedSidecars.length > 0) {
+		const reason = formatSidecarGuardReason(colocatedSidecars);
+		if (lifecycle) {
+			return {
+				outcome: 'sidecar-violation',
+				routedToNeedsAttention: false,
+				branch,
+				reason:
+					`Co-located sidecar detected for '${slug}'; not completing the ` +
+					`transition. ${reason}`,
+				reviewBlockReason: reason,
+			};
+		}
+		const routed = await ledgerWrite.applyNeedsAttentionTransition({
+			cwd,
+			slug,
+			reason,
+			arbiter: input.surfaceArbiter,
+			env,
+			note,
+		});
+		return {
+			outcome: 'sidecar-violation',
+			routedToNeedsAttention: routed.moved,
+			branch,
+			reason: routed.moved
+				? `Co-located task/spec sidecar detected for '${slug}'; marked it stuck ` +
+					`on its per-item lock (a flowing item's <slug>/ sidecar strands on ` +
+					`the durable move). ${reason}`
+				: `Co-located task/spec sidecar detected for '${slug}'; not completing ` +
+					`it. ${reason}`,
+			reviewBlockReason: reason,
+		};
+	}
+
 	// Read the title now, BEFORE the move, for the default commit summary AND the
 	// synthesised propose-mode PR TITLE (the source file is about to be git-mv'd
 	// away). The PR title is a SINGLE, capped line built runner-side from the
@@ -1314,10 +1419,21 @@ export async function performIntegration(
 					gated.kind === 'prepare'
 						? `Env-prep (prepare) failed (exit ${gated.exitCode})`
 						: `Acceptance gate failed (exit ${gated.exitCode})`;
+				// The gate-failure CONTEXT (which command failed + its output tail) is
+				// meaningful only for a `verify` failure; a prepare failure names its
+				// single command already. Enrich the surfaced reason so the question is
+				// actionable rather than an opaque exit code.
+				const context =
+					gated.kind === 'prepare'
+						? ''
+						: formatGateFailureContext({
+								failedCommand: gated.failedCommand,
+								outputTail: gated.outputTail,
+							});
 				const reason =
 					gated.kind === 'prepare'
 						? `prepare (env-prep) failed (exit ${gated.exitCode}) on the rebased tip`
-						: `acceptance gate failed (exit ${gated.exitCode}) on the rebased tip`;
+						: `acceptance gate failed (exit ${gated.exitCode}) on the rebased tip${context}`;
 				const routed = await ledgerWrite.applyNeedsAttentionTransition({
 					cwd,
 					slug,
@@ -1898,10 +2014,17 @@ async function recoverAlreadyCommitted(params: {
 				gated.kind === 'prepare'
 					? `Env-prep (prepare) failed (exit ${gated.exitCode})`
 					: `Acceptance gate failed (exit ${gated.exitCode})`;
+			const context =
+				gated.kind === 'prepare'
+					? ''
+					: formatGateFailureContext({
+							failedCommand: gated.failedCommand,
+							outputTail: gated.outputTail,
+						});
 			const reason =
 				gated.kind === 'prepare'
 					? `prepare (env-prep) failed (exit ${gated.exitCode}) on the rebased tip`
-					: `acceptance gate failed (exit ${gated.exitCode}) on the rebased tip`;
+					: `acceptance gate failed (exit ${gated.exitCode}) on the rebased tip${context}`;
 			const routed = await ledgerWrite.applyNeedsAttentionTransition({
 				cwd,
 				slug,
@@ -3055,6 +3178,19 @@ interface FreshGateResult {
 	kind?: 'prepare' | 'verify';
 	/** The non-zero exit code of the failing step (when `!passed`). */
 	exitCode?: number;
+	/**
+	 * The EXACT gate command that failed (`verify` kind only) — threaded from
+	 * {@link RunVerifyResult.failedCommand} so the surfaced reason names WHICH step
+	 * of a multi-command gate failed. Absent for a `prepare` failure (the prepare
+	 * command is single + already named).
+	 */
+	failedCommand?: string;
+	/**
+	 * The TAIL of the failed gate command's output (`verify` kind only) — threaded
+	 * from {@link RunVerifyResult.outputTail} so the surfaced question carries the
+	 * actual error text.
+	 */
+	outputTail?: string;
 	/**
 	 * The Gate-2 REVIEW outcome, present ONLY when a review gate was supplied to the
 	 * fresh gate AND `verify` passed (so the review ran AFTER it on the rebased tip).
@@ -3144,7 +3280,13 @@ async function runFreshWorktreeGate(params: {
 			env,
 		});
 		if (!gate.passed) {
-			return {passed: false, kind: 'verify', exitCode: gate.exitCode};
+			return {
+				passed: false,
+				kind: 'verify',
+				exitCode: gate.exitCode,
+				failedCommand: gate.failedCommand,
+				outputTail: gate.outputTail,
+			};
 		}
 		// GATE-2 REVIEW on the rebased tip, AFTER the green verify (verify-then-review
 		// on the SAME merged tree). Runs while the worktree is still live (the review

package/src/run.ts

@@ -1059,8 +1059,14 @@ async function runOneItem(
 			core.outcome === 'prepare-failed' ||
 			core.outcome === 'review-blocked' ||
 			core.outcome === 'rebase-conflict' ||
+			core.outcome === 'sidecar-violation' ||
 			core.outcome === 'invariant-violation'
 		) {
+			// `sidecar-violation`: a co-located `<slug>/` sidecar sits beside a FLOWING
+			// task/spec item (WORK-CONTRACT rule 8) — a HARD BLOCK before the durable
+			// move (it would strand on `ready → done`). The core routed it to
+			// needs-attention with an actionable relocate-to-`docs/spikes/<slug>/`
+			// reason; the least-supervised caller MUST NOT fall through to success.
 			// `prepare-failed`: the env-prep (install) step was red, so the env could
 			// not be made ready and `verify` was NOT run — distinct from a `tests-failed`
 			// red gate. Route it to needs-attention like the others (a human fixes the

package/src/sidecar-guard.ts

@@ -0,0 +1,142 @@
+import {existsSync, statSync} from 'node:fs';
+import {join} from 'node:path';
+import {
+	workFolderName,
+	workFolderPath,
+	type WorkFolderKey,
+} from './work-layout.js';
+
+/**
+ * The **co-located task/spec sidecar GUARD** (WORK-CONTRACT.md rule 8, the
+ * `notes/*`-only scoping).
+ *
+ * WHAT IT ENFORCES. A `<slug>/` asset sidecar folder co-located with a work item
+ * is ALLOWED for `notes/*` ONLY (`ideas`/`observations`/`findings` — they do NOT
+ * flow; a note leaves by deletion, so its sidecar never moves). It is FORBIDDEN
+ * for a `tasks/*` or `specs/*` item, because those regimes FLOW through status
+ * folders (`tasks/ready → tasks/done`, `specs/ready → specs/tasked`, …): a
+ * co-located sidecar shares the item's lifecycle and must be `git mv`'d in
+ * lockstep on every transition, and in practice gets STRANDED — the `<slug>.md`
+ * moves to the new status folder while the `<slug>/` sidecar is left behind in
+ * the old one, splitting ONE item across TWO status folders (a
+ * one-slug-one-folder violation, the SAME invariant `ledger-lint.ts` reads and
+ * the integration core enforces). A task's/spec's durable companion artifacts
+ * belong in the STABLE, non-flowing `docs/spikes/<slug>/` home (referenced by
+ * path from the `<slug>.md`), NOT a co-located sidecar.
+ *
+ * WHERE IT RUNS. This is the DETECTOR half; the integration core (`integration-core.ts`)
+ * wires it as a HARD BLOCK at LAND, BEFORE the durable `git mv` — a detected
+ * sidecar routes the item to needs-attention with {@link formatSidecarGuardReason},
+ * consistent with the status=folder / one-item-one-location contract the stranding
+ * violates. Fix = `git mv` the sidecar contents to `docs/spikes/<slug>/` + a
+ * reference edit in the `<slug>.md`.
+ *
+ * NO FALSE POSITIVES on: (a) the `work/questions/<type>-<slug>.md` needs-attention
+ * file — it is a tooling-owned STATUS-MECHANISM file, NOT scanned here (only
+ * `tasks/*` + `specs/*` FLOWING folders are); (b) a legitimate `notes/*` sidecar —
+ * the note buckets are deliberately EXCLUDED from the scan set; (c) a
+ * `docs/spikes/<slug>/` outside `work/` — this only ever looks INSIDE the FLOWING
+ * `work/` status folders.
+ */
+
+/**
+ * The FLOWING status folders a `tasks/*` / `specs/*` item moves through — the ONLY
+ * folders scanned for an illegal co-located sidecar. Deliberately EXCLUDES the
+ * `notes/*` capture buckets (`ideas`/`observations`/`findings`, which legitimately
+ * MAY carry a sidecar) and the top-level `questions`/`protocol` surfaces (neither
+ * holds a flowing work item). A sidecar under any of THESE is a rule-8 violation
+ * because the item it sits beside will be `git mv`'d to another status folder and
+ * strand it.
+ */
+export const SIDECAR_GUARD_FLOWING_FOLDERS = [
+	'tasks-backlog',
+	'tasks-ready',
+	'done',
+	'cancelled',
+	'specs-proposed',
+	'specs-ready',
+	'specs-tasked',
+	'specs-dropped',
+] as const satisfies readonly WorkFolderKey[];
+
+/** One illegal co-located `<slug>/` sidecar found beside a flowing task/spec item. */
+export interface ColocatedSidecar {
+	/** The flowing status folder the sidecar was found in. */
+	folder: WorkFolderKey;
+	/** The slug of the offending `<slug>/` sidecar directory. */
+	slug: string;
+	/** The repo-relative path of the sidecar directory (`work/<folder>/<slug>/`). */
+	dirRel: string;
+}
+
+/** Does `<dir>/<name>` exist AND is it a directory? (a sidecar is a folder). */
+function isDir(dir: string, name: string): boolean {
+	try {
+		return statSync(join(dir, name)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Detect a co-located `<slug>/` asset sidecar directory sitting beside the
+ * `<slug>.md` of a FLOWING task/spec item, in the given `cwd`'s working tree.
+ * Scans ONLY {@link SIDECAR_GUARD_FLOWING_FOLDERS} for a `<slug>/` DIRECTORY whose
+ * sibling `<slug>.md` FILE is present (both must be there: a lone `<slug>/`
+ * directory with no item file is not this item's sidecar). Returns every offender
+ * found (typically at most one, for the item being landed), or `[]` when clean.
+ *
+ * PURE-ish: reads the filesystem, no writes, no throws. The integration core
+ * passes the specific `slug` being landed so the block is scoped to THAT item.
+ */
+export function detectColocatedSidecars(
+	cwd: string,
+	slug: string,
+): ColocatedSidecar[] {
+	const found: ColocatedSidecar[] = [];
+	for (const folder of SIDECAR_GUARD_FLOWING_FOLDERS) {
+		const dir = workFolderPath(cwd, folder);
+		// The item file `<slug>.md` AND the sidecar dir `<slug>/` must BOTH be
+		// present for this to be the item's stranded-able sidecar. A stray `<slug>/`
+		// with no `<slug>.md` in the same folder is not an item's sidecar.
+		if (!existsSync(join(dir, `${slug}.md`))) {
+			continue;
+		}
+		if (isDir(dir, slug)) {
+			found.push({
+				folder,
+				slug,
+				dirRel: `work/${workFolderName(folder)}/${slug}/`,
+			});
+		}
+	}
+	return found;
+}
+
+/**
+ * Format the ACTIONABLE needs-attention reason for a detected co-located sidecar
+ * (the message the LAND-time hard block surfaces VERBATIM). Names the offending
+ * path, the correct destination, and the exact fix — a `git mv` to
+ * `docs/spikes/<slug>/` plus a reference edit.
+ */
+export function formatSidecarGuardReason(
+	sidecars: readonly ColocatedSidecar[],
+): string {
+	if (sidecars.length === 0) {
+		return '';
+	}
+	const lines = [
+		'task/spec artifacts belong in docs/spikes/<slug>/, not a co-located ' +
+			'work/tasks|specs/<slug>/ sidecar; only notes/* may carry a sidecar ' +
+			'(WORK-CONTRACT rule 8) — relocate + reference by path:',
+	];
+	for (const s of sidecars) {
+		lines.push(
+			`  - ${s.dirRel}: git mv its contents to docs/spikes/${s.slug}/ ` +
+				`(a STABLE, non-flowing home), then reference them by that path from ` +
+				`work/${workFolderName(s.folder)}/${s.slug}.md (a flowing item's ` +
+				`co-located sidecar strands on the ready→done move).`,
+		);
+	}
+	return lines.join('\n');
+}

package/src/tasking.ts

@@ -758,6 +758,39 @@ export async function performTask(
 					`marked the per-item lock stuck (needs attention; no tasks landed).`,
 			};
 		}
+		if (core.outcome === 'sidecar-violation') {
+			// A co-located `<slug>/` asset sidecar sits beside the FLOWING spec item
+			// (WORK-CONTRACT.md rule 8): the tasking transition would `git mv`
+			// `specs/ready → specs/tasked` and STRAND the sidecar. The core HARD-BLOCKED
+			// before the stage/integrate; route the held spec to needs-attention through
+			// the SAME `spec:<slug>` lock-release seam the block path uses (no tasks land),
+			// carrying the actionable relocate-to-`docs/spikes/<slug>/` reason.
+			const reason =
+				`The spec '${slug}' carries a co-located asset sidecar: ` +
+				`${core.reviewBlockReason ?? core.reason ?? ''}`;
+			const routed = await lock.release({
+				slug,
+				cwd,
+				arbiter,
+				lockedBlob,
+				routeToNeedsAttention: {reason},
+				env,
+				note,
+			});
+			if (routed.outcome !== 'released') {
+				return releaseFailureToResult(routed, slug);
+			}
+			note(reason);
+			return {
+				exitCode: 1,
+				outcome: 'needs-attention',
+				slug,
+				message:
+					`The spec '${slug}' carries a co-located asset sidecar (WORK-CONTRACT ` +
+					`rule 8); marked the per-item lock stuck (needs attention; no tasks ` +
+					`landed; relocate it to docs/spikes/${slug}/ and reference by path).`,
+			};
+		}
 		if (core.outcome === 'review-unparseable') {
 			// The task-set acceptance gate RAN but its verdict was UNPARSEABLE (malformed
 			// JSON). Route the held spec to needs-attention through the SAME lock-release

package/src/verify.ts

@@ -99,6 +99,22 @@ export interface RunVerifyResult {
 	commands: string[];
 	/** Whether the gate passed (exitCode === 0). */
 	passed: boolean;
+	/**
+	 * The EXACT command that failed (the first non-zero exit — `&&`-short-circuit
+	 * semantics), verbatim from the resolved gate list. Present ONLY on a failing
+	 * result with a configured gate. This is the load-bearing context a bare `exit
+	 * N` throws away: in a multi-command gate (`build && test && format:check`) it
+	 * tells the human WHICH step failed without re-running the whole gate.
+	 */
+	failedCommand?: string;
+	/**
+	 * The TAIL of the failed command's combined stdout+stderr (last
+	 * {@link VERIFY_OUTPUT_TAIL_LINES} non-empty lines), so the surfaced
+	 * needs-attention question carries the ACTUAL error text (e.g. "no changesets
+	 * were found") rather than an opaque exit code. Bounded so a noisy gate cannot
+	 * bloat the sidecar. Present ONLY on a failing result with a configured gate.
+	 */
+	outputTail?: string;
 	/**
 	 * True iff the gate could not run because NO `verify` is declared (unset /
 	 * empty / all-blank). A distinct, always-failing outcome (`passed: false`)
@@ -108,6 +124,15 @@ export interface RunVerifyResult {
 	notConfigured?: boolean;
 }
 
+/**
+ * How many trailing non-empty output lines of the FAILED gate command are kept
+ * in {@link RunVerifyResult.outputTail}. Small enough to keep the surfaced
+ * question readable, large enough to carry the actual error (most tool errors
+ * are 1–3 lines). The tail is captured per-command and reset on each command so
+ * only the failing command's output is retained.
+ */
+export const VERIFY_OUTPUT_TAIL_LINES = 20;
+
 /**
  * Run the resolved gate command(s) in `cwd`, streaming output, and resolve with
  * the gate's status: exit 0 iff every command passed. Commands run in sequence;
@@ -142,17 +167,62 @@ export async function runVerify(
 		options.onStderr ?? ((chunk: string) => process.stderr.write(chunk));
 
 	for (const command of commands) {
+		// Capture a bounded ring of this command's combined output so a FAILURE can
+		// carry the actual error text (not just an exit code). Reset per command so
+		// only the failing command's tail is retained. The captured chunks still
+		// stream through the sinks unchanged (the console/log is unaffected).
+		const tail: string[] = [];
+		const capture = (chunk: string) => {
+			for (const line of chunk.split('\n')) {
+				tail.push(line);
+			}
+			// Keep a little slack over the reported budget; trimmed to the exact budget
+			// (non-empty lines only) when a failure surfaces.
+			const maxRing = VERIFY_OUTPUT_TAIL_LINES * 4;
+			if (tail.length > maxRing) {
+				tail.splice(0, tail.length - maxRing);
+			}
+		};
 		const exitCode = await runOne(command, options.cwd, options.env, {
-			onStdout,
-			onStderr,
+			onStdout: (chunk) => {
+				capture(chunk);
+				onStdout(chunk);
+			},
+			onStderr: (chunk) => {
+				capture(chunk);
+				onStderr(chunk);
+			},
 		});
 		if (exitCode !== 0) {
-			return {exitCode, commands, passed: false};
+			return {
+				exitCode,
+				commands,
+				passed: false,
+				failedCommand: command,
+				outputTail: lastNonEmptyLines(tail, VERIFY_OUTPUT_TAIL_LINES),
+			};
 		}
 	}
 	return {exitCode: 0, commands, passed: true};
 }
 
+/**
+ * Join the last `n` NON-EMPTY lines of a captured output ring into a single
+ * string (newline-separated), preserving order. Blank lines are dropped so the
+ * tail is dense signal (tool errors, not the trailing whitespace many gates
+ * emit). Returns `undefined` when nothing was captured, so callers can omit the
+ * context cleanly rather than surfacing an empty block.
+ */
+function lastNonEmptyLines(lines: string[], n: number): string | undefined {
+	const dense = lines
+		.map((line) => line.trimEnd())
+		.filter((line) => line !== '');
+	if (dense.length === 0) {
+		return undefined;
+	}
+	return dense.slice(-n).join('\n');
+}
+
 /** Spawn one command via `bash -c`, streaming its output, resolving its code. */
 function runOne(
 	command: string,