dorfl 0.5.0 → 0.6.0

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,