dorfl 0.14.2 → 0.15.0

package/src/land-question-residue.ts

@@ -0,0 +1,122 @@
+import {existsSync, readFileSync, rmSync, writeFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {parseFrontmatter, setNeedsAnswersMarker} from './frontmatter.js';
+import {isEntryAnswered, parseSidecar, sidecarPathFor} from './sidecar.js';
+import {workItemPath, workItemRel} from './work-layout.js';
+
+/** What {@link clearOwnQuestionResidueOnLand} did to the working tree. */
+export interface LandQuestionResidueResult {
+	/**
+	 * Repo-relative paths this pass CHANGED in the working tree (the done record
+	 * whose `needsAnswers` it cleared, the sidecar it deleted). Empty ⇒ the tree is
+	 * byte-for-byte untouched (the normal land).
+	 */
+	changed: string[];
+	/** True when the done record's `needsAnswers: true` was rewritten to `false`. */
+	unflagged: boolean;
+	/** True when the item's own unanswered question sidecar was deleted. */
+	drainedSidecar: boolean;
+	/**
+	 * True when the item's sidecar carries a human ANSWER (or could not be parsed)
+	 * and was therefore left alone, together with the flag.
+	 */
+	held: boolean;
+}
+
+/**
+ * CLEAR a landing task's OWN stale question state in the WORKING TREE, so it
+ * rides the land's completion commit instead of surviving onto `main` (task
+ * `a-recovered-task-lands-without-stale-question-state`).
+ *
+ * THE DEFECT. A task surfaced to needs-attention (`surfaceStuckToNeedsAttention`
+ * writes `needsAnswers: true` on the body AND `work/questions/task-<slug>.md` in
+ * one commit on `main`) and then RECOVERED (a re-dispatch, a requeue continue, a
+ * stranded-branch finish) carried both halves straight through its done-move:
+ * the `git mv ... → tasks/done/` kept the flag, and nothing deleted the sidecar.
+ * The claim-time reconcile (`reconcileTerminalQuestionResidue`) drained them only
+ * on the NEXT claim, so the ledger was wrong in between, and stayed wrong when no
+ * claim followed.
+ *
+ * WHY THE LAND and not a later sweep: the done-move is the moment the residue
+ * becomes residue, and the land already owns a commit that touches exactly this
+ * item. Folding the clean-up into it leaves no window at all.
+ *
+ * SAME SEMANTICS as the claim-time drain for a `completed` terminal, so the two
+ * never disagree about what "stale" means:
+ *   - the flag is set to `needsAnswers: false` via the SAME
+ *     {@link setNeedsAnswersMarker} writer, and only when it parses back as
+ *     `false` (a body the writer cannot annotate is left alone rather than
+ *     written as something we cannot vouch for);
+ *   - a sidecar carrying ANY answered entry is never deleted, and the item's flag
+ *     is then left alone too (a human's unapplied answer is data the tool did not
+ *     author; the answered-merge apply rung owns that sidecar). An unparseable
+ *     sidecar is held the same way (every uncertainty resolves to leaving state
+ *     alone).
+ *
+ * Only ever touches the landing task's own two paths, and only when its done
+ * record exists in the tree. A normal land (no flag, no sidecar) changes nothing.
+ * Best-effort: never throws; a fault leaves the tree as it was.
+ */
+export function clearOwnQuestionResidueOnLand(params: {
+	cwd: string;
+	slug: string;
+	note?: (message: string) => void;
+}): LandQuestionResidueResult {
+	const {cwd, slug} = params;
+	const note = params.note ?? (() => {});
+	const result: LandQuestionResidueResult = {
+		changed: [],
+		unflagged: false,
+		drainedSidecar: false,
+		held: false,
+	};
+	const donePath = workItemPath(cwd, 'done', slug);
+	if (!existsSync(donePath)) {
+		return result; // not a task done-move (a lifecycle / degenerate shape).
+	}
+	const sidecarRel = sidecarPathFor(`task:${slug}`);
+	const sidecarAbs = join(cwd, sidecarRel);
+	try {
+		if (existsSync(sidecarAbs)) {
+			let answered: boolean;
+			try {
+				answered = parseSidecar(readFileSync(sidecarAbs, 'utf8')).entries.some(
+					(e) => isEntryAnswered(e),
+				);
+			} catch {
+				answered = true; // unparseable: hold, never delete what we cannot read.
+			}
+			if (answered) {
+				result.held = true;
+				note(
+					`Left ${sidecarRel} and the needsAnswers flag of '${slug}' in place: ` +
+						'the sidecar carries an answer (or could not be read), which the ' +
+						'land never discards.',
+				);
+				return result;
+			}
+			rmSync(sidecarAbs, {force: true});
+			result.drainedSidecar = true;
+			result.changed.push(sidecarRel);
+		}
+		const body = readFileSync(donePath, 'utf8');
+		if (parseFrontmatter(body).needsAnswers === true) {
+			const cleared = setNeedsAnswersMarker(body, false);
+			if (parseFrontmatter(cleared).needsAnswers === false) {
+				writeFileSync(donePath, cleared);
+				result.unflagged = true;
+				result.changed.push(workItemRel('done', `${slug}.md`));
+			}
+		}
+	} catch {
+		// Best-effort: never fail a green land over question-state hygiene.
+	}
+	if (result.changed.length > 0) {
+		note(
+			`Cleared the stale question state of '${slug}' in its land ` +
+				`(${result.changed.join(', ')}): the task is done, so its ` +
+				'needs-attention question is moot.',
+		);
+	}
+	return result;
+}

package/src/lifecycle-gather.ts

@@ -7,6 +7,7 @@ import {
 	type SidecarModel,
 } from './sidecar.js';
 import {runAsync} from './git.js';
+import {answeredMergeActionIn} from './merge-answer.js';
 import {
 	buildLifecyclePools,
 	type LifecyclePoolGates,
@@ -153,10 +154,20 @@ export function gatherLifecycleInPlace(input: {
 	 * behaviour) so callers who cannot resolve a lock read still work.
 	 */
 	heldSlugs?: Set<string>;
+	/**
+	 * The held TASK slugs whose lock a finished propose build keeps (the
+	 * `propose-pr` marker, `proposeKeptTaskSlugs`). Such a slug is NOT subtracted
+	 * when its sidecar carries an answered `merge` (task
+	 * `wire-merge-questions-into-the-advance-tick`, decision 6): the answered-merge
+	 * apply takes that lock over. Every other held slug is still subtracted.
+	 * Defaults empty.
+	 */
+	proposeKeptSlugs?: Set<string>;
 }): SelectedLifecyclePools {
 	const read = input.read ?? ledgerRead;
 	const repoPath = input.repoPath;
 	const heldSlugs = input.heldSlugs ?? new Set<string>();
+	const proposeKept = input.proposeKeptSlugs ?? new Set<string>();
 
 	const rawObservations = read.resolveLocalState({repoPath}).observations;
 	const observations: ObservationCandidate[] = rawObservations.map((obs) => ({
@@ -165,21 +176,40 @@ export function gatherLifecycleInPlace(input: {
 		sidecar: readSidecarInPlace(repoPath, 'observation', obs.slug),
 	}));
 	const surfaceStaging = input.gates?.surfaceStaging === true;
-	const needsAnswers: NeedsAnswersCandidate[] = blockedItemsInPlace(
-		read,
-		repoPath,
-		surfaceStaging,
-	)
-		// Held-slug subtraction (task-scoped): a `needsAnswers` TASK whose per-item
-		// lock is currently held is EXCLUDED from surface/apply enumeration. Spec /
-		// observation entries are untouched — the lock ref set here is task-only.
-		.filter((item) => !(item.namespace === 'task' && heldSlugs.has(item.slug)))
+	const blocked = blockedItemsInPlace(read, repoPath, surfaceStaging);
+	if (!surfaceStaging) {
+		// A merge question on a STAGED body (`tasks/backlog/`) is applied even with
+		// `surfaceStaging` off (task `wire-merge-questions-into-the-advance-tick`,
+		// decision 6): the surfacer asked it, the staging gate did not.
+		for (const item of read.resolveLocalTaskStaging({repoPath})) {
+			if (
+				item.needsAnswers === true &&
+				hasMergeQuestion(readSidecarInPlace(repoPath, 'task', item.slug))
+			) {
+				blocked.push({namespace: 'task', slug: item.slug});
+			}
+		}
+	}
+	const needsAnswers: NeedsAnswersCandidate[] = blocked
 		.map((item) => ({
 			repoPath,
 			namespace: item.namespace,
 			slug: item.slug,
 			sidecar: readSidecarInPlace(repoPath, item.namespace, item.slug),
-		}));
+		}))
+		// Held-slug subtraction (task-scoped): a `needsAnswers` TASK whose per-item
+		// lock is currently held is EXCLUDED from surface/apply enumeration, unless
+		// the lock is kept for a propose PR and the item's merge question is
+		// answered `merge` (the answered-merge apply takes that lock over). Spec /
+		// observation entries are untouched: the lock ref set here is task-only.
+		.filter(
+			(item) =>
+				!(
+					item.namespace === 'task' &&
+					heldSlugs.has(item.slug) &&
+					!mayTakeOverProposeKept(proposeKept, item.slug, item.sidecar)
+				),
+		);
 
 	return buildLifecyclePools({
 		repoPath,
@@ -189,6 +219,28 @@ export function gatherLifecycleInPlace(input: {
 	});
 }
 
+/** Does the sidecar carry a merge question (answered or not)? */
+function hasMergeQuestion(sidecar: SidecarModel | undefined): boolean {
+	return sidecar?.entries.some((e) => e.kind === 'merge') === true;
+}
+
+/**
+ * May a HELD task still be selected? Only when its lock is kept for a propose PR
+ * (`proposeKept`) and its merge question is answered `merge`: that apply takes
+ * the lock over (task `wire-merge-questions-into-the-advance-tick`, decision 6).
+ */
+export function mayTakeOverProposeKept(
+	proposeKept: Set<string>,
+	slug: string,
+	sidecar: SidecarModel | undefined,
+): boolean {
+	return (
+		proposeKept.has(slug) &&
+		sidecar !== undefined &&
+		answeredMergeActionIn(sidecar)?.verb === 'merge'
+	);
+}
+
 /**
  * Read the ACTIVE sidecar for `<namespace>:<slug>` from a BARE hub mirror's
  * committed `<ref>:work/questions/<type>-<slug>.md` via `git show` (the SAME
@@ -243,6 +295,25 @@ export async function gatherLifecycleMirror(input: {
 				read.resolveMirrorSpecStaging({mirrorPath, ref, env}),
 			])
 		: [[], []];
+	// A merge question on a STAGED body is applied even with `surfaceStaging`
+	// off (decision 6), as in {@link gatherLifecycleInPlace}.
+	const stagedMergeQuestions: BlockedItem[] = [];
+	if (!surfaceStaging) {
+		for (const item of await read.resolveMirrorTaskStaging({
+			mirrorPath,
+			ref,
+			env,
+		})) {
+			if (
+				item.needsAnswers === true &&
+				hasMergeQuestion(
+					await readSidecarMirror(mirrorPath, ref, 'task', item.slug, env),
+				)
+			) {
+				stagedMergeQuestions.push({namespace: 'task', slug: item.slug});
+			}
+		}
+	}
 
 	const blocked: BlockedItem[] = [];
 	for (const item of state.ready) {
@@ -282,6 +353,7 @@ export async function gatherLifecycleMirror(input: {
 			blocked.push({namespace: 'spec', slug: spec.slug});
 		}
 	}
+	blocked.push(...stagedMergeQuestions);
 
 	const needsAnswers: NeedsAnswersCandidate[] = await Promise.all(
 		blocked.map(async (item) => ({

package/src/merge-answer.ts

@@ -0,0 +1,82 @@
+import {
+	isEntryAnswered,
+	type SidecarEntry,
+	type SidecarModel,
+} from './sidecar.js';
+
+/**
+ * The PARSE half of the answered merge-question (task
+ * `apply-rung-merge-disposition`): the human's plain `merge | hold | drop`
+ * answer to a `kind: merge` sidecar entry, read deterministically. Kept apart
+ * from the dispatcher (`apply-merge-action.ts`, which re-exports it) so the
+ * selection path can read an answered merge without importing the land
+ * machinery.
+ */
+
+/** The three deterministic actions a merge-question answer encodes. */
+export type MergeActionVerb = 'merge' | 'hold' | 'drop';
+
+/** A detected, answer-driven merge-action keyed off ONE answered `kind: merge` entry. */
+export interface DetectedMergeAction {
+	/** The deterministic verb parsed from the entry's answer text. */
+	verb: MergeActionVerb;
+	/** The answered `kind: merge` entry the verb came from. */
+	entry: SidecarEntry;
+}
+
+/**
+ * Parse the human's plain free-text answer into the deterministic
+ * {@link MergeActionVerb}. The merge-question surfacer renders
+ * `merge | hold | drop` in the entry's `default` as a human-readable hint, so
+ * the human typically types one of those words verbatim. We accept any text
+ * whose first whole word (case-insensitive) is one of `merge` / `hold` / `drop`
+ * — this is the same machine-parseable choice shape the surfacer's applied
+ * answer q1 documents ("a DETERMINISTIC CHOICE shape … the human picks and the
+ * system parses unambiguously").
+ *
+ * Returns `undefined` on ANYTHING else (an empty answer, a typo, a long
+ * narrative without one of the three words at the start) so the caller can
+ * route the ambiguity HONESTLY — never default-to-merge on a malformed answer,
+ * which would invent a land the human did not authorise.
+ */
+export function parseMergeAnswer(text: string): MergeActionVerb | undefined {
+	const trimmed = text.trim().toLowerCase();
+	if (trimmed === '') return undefined;
+	// The first whole alphabetic word; trailing punctuation (a comma, em-dash,
+	// period) and any following commentary are tolerated. We deliberately do
+	// NOT consume hyphens / apostrophes — the three verbs are plain ASCII
+	// words, and over-tolerating typo-shapes would silently invent a verb the
+	// human did not pick.
+	const match = /^([a-z]+)/.exec(trimmed);
+	if (match === null) return undefined;
+	const word = match[1];
+	if (word === 'merge' || word === 'hold' || word === 'drop') {
+		return word;
+	}
+	return undefined;
+}
+
+/**
+ * `detectAnsweredMergeAction` (`apply-merge-action.ts`) over an already-parsed sidecar model (the
+ * selection path reads sidecars itself, in place and from a mirror ref). The
+ * same ordering rules apply.
+ */
+export function answeredMergeActionIn(
+	model: SidecarModel,
+): DetectedMergeAction | undefined {
+	// (1) Unanswered `kind: merge` follow-up ⇒ re-paused; the apply must NOT fire.
+	for (const entry of model.entries) {
+		if (entry.kind === 'merge' && !isEntryAnswered(entry)) return undefined;
+	}
+	// (2) LATEST answered `kind: merge` entry — a fresh follow-up beats a stale one.
+	for (let i = model.entries.length - 1; i >= 0; i--) {
+		const entry = model.entries[i];
+		if (entry.kind !== 'merge') continue;
+		if (!isEntryAnswered(entry)) continue;
+		const verb = parseMergeAnswer(entry.answer);
+		if (verb !== undefined) {
+			return {verb, entry};
+		}
+	}
+	return undefined;
+}