dorfl 0.1.1 → 0.2.0

package/src/apply-stuck-action.ts

@@ -0,0 +1,260 @@
+import {existsSync, readFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {
+	isEntryAnswered,
+	parseSidecar,
+	sidecarPathFor,
+	type SidecarEntry,
+	type SidecarModel,
+} from './sidecar.js';
+import {deleteRemoteWorkBranchIfPresent} from './needs-attention.js';
+
+/**
+ * The **answered STUCK-QUESTION ACTION DISPATCH** (spec
+ * `surface-stuck-as-questions-and-retire-stuck-lock-state`, task
+ * `apply-resolve-reset-flag-discards-work-branch`; user story 2, resolved
+ * decision #6) — the deterministic, answer-driven RUNNER-ACTION layer that
+ * turns an answered `kind: 'stuck'` sidecar entry (the shape the bounce-surface
+ * path stamps when a task's build bounces) into one of three verbs:
+ *
+ *   - `keep`   -> today's continue-from-WIP: leave the `work/<slug>` branch
+ *                alone; the apply rung falls through to the normal
+ *                `applyAnsweredQuestions` resolve so the next claim continues
+ *                from the branch tip.
+ *   - `reset`  -> discard the WIP branch, rebuild clean: DELETE the remote
+ *                `work/<slug>` branch on the arbiter (via the SHARED
+ *                {@link deleteRemoteWorkBranchIfPresent} primitive the
+ *                `requeue --reset` recovery verb also uses) BEFORE the apply
+ *                rung clears `needsAnswers`, so the next claim starts fresh.
+ *                Safely IDEMPOTENT when no branch exists (an observation, or a
+ *                task never built) — a `remote ref does not exist` push error
+ *                is tolerated as an already-gone no-op.
+ *   - `cancel` -> the existing `dispose` terminal: `git mv` the task to
+ *                `tasks/cancelled/` via `applyAnsweredQuestions`' `dispose`
+ *                option (the answer text is recorded as the human's reason).
+ *
+ * A direct SIBLING of the `apply-merge-action.ts` machinery: the apply rung
+ * KIND-CHECKS the sidecar BEFORE the fall-through persist, so an answered
+ * `kind: 'stuck'` entry dispatches HERE deterministically (mirroring how a
+ * `kind: 'merge'` entry dispatches through `apply-merge-action.ts`). There is
+ * NO agentic decider on the TASK apply-persist path (the `runAgenticDecision`
+ * gate at `advance.ts` fires only for `namespace === 'observation'`), so this
+ * MUST be a deterministic parse+dispatch — the flag SOURCE on the task path
+ * (see the task's `## Re-scope 2026-07-14`).
+ *
+ * # Ordering (delete-before-clear) and partial-failure decision
+ *
+ * The `reset` verb DELETES the remote work branch BEFORE the apply rung
+ * clears `needsAnswers`. On a partial failure (arbiter delete FAILS after the
+ * local tracking ref was cleared), we REFUSE the apply and leave the sidecar
+ * in place (`needsAnswers` stays `true`), so the human sees the failure and
+ * can re-answer. The alternative (clear-then-delete, or clear-anyway on a
+ * failed delete) would leave the item `needsAnswers:false` and CLAIMABLE while
+ * still carrying the WIP branch we meant to discard — exactly the stale-
+ * continue trap the `requeue --reset` code path spends a page of comment
+ * defending against. The two callers (this verb + `requeue --reset`) MUST
+ * stay behaviourally identical; both fail the whole recovery on a genuine
+ * push-delete failure. This is the `## Decisions` entry the done record
+ * links.
+ */
+
+/** The three deterministic verbs a stuck-question answer encodes. */
+export type StuckActionVerb = 'keep' | 'reset' | 'cancel';
+
+/** A detected, answer-driven stuck-action keyed off ONE answered `kind: 'stuck'` entry. */
+export interface DetectedStuckAction {
+	/** The deterministic verb parsed from the entry's answer text. */
+	verb: StuckActionVerb;
+	/** The answered `kind: 'stuck'` entry the verb came from. */
+	entry: SidecarEntry;
+}
+
+/**
+ * Parse the human's plain free-text answer into a {@link StuckActionVerb}.
+ * MIRRORS `parseMergeAnswer` EXACTLY: first whole ASCII word, case-insensitive,
+ * trailing commentary tolerated; `undefined` on anything else (empty / typo /
+ * narrative). NEVER default-guesses a destructive `reset` — an ambiguous
+ * answer falls through to today's plain persist (the safe "keep the branch,
+ * clear the flag" behaviour), never invents a branch discard.
+ */
+export function parseStuckAnswer(text: string): StuckActionVerb | undefined {
+	const trimmed = text.trim().toLowerCase();
+	if (trimmed === '') return undefined;
+	const match = /^([a-z]+)/.exec(trimmed);
+	if (match === null) return undefined;
+	const word = match[1];
+	if (word === 'keep' || word === 'reset' || word === 'cancel') {
+		return word;
+	}
+	return undefined;
+}
+
+/**
+ * Detect the `kind: 'stuck'` action verb that should drive the next apply run.
+ *
+ * ORDERING (mirrors `detectAnsweredMergeAction`'s re-stale re-surface rule):
+ *
+ *   1. If ANY `kind: 'stuck'` entry is UNANSWERED, return `undefined` —
+ *      that is the re-paused state (a freshly-appended follow-up awaiting an
+ *      answer), and the apply MUST NOT fire against a stale prior sibling.
+ *   2. Otherwise return the LATEST answered `kind: 'stuck'` entry — a fresh
+ *      follow-up answer wins over the stale one.
+ *
+ * Returns `undefined` on a missing/unparseable sidecar or when no
+ * `kind: 'stuck'` entry parses to one of the three verbs (the apply rung then
+ * falls through to today's plain persist, which is the `keep` semantic — a
+ * malformed answer NEVER discards a branch).
+ */
+export function detectAnsweredStuckAction(
+	cwd: string,
+	item: string,
+): DetectedStuckAction | undefined {
+	const abs = join(cwd, sidecarPathFor(item));
+	if (!existsSync(abs)) return undefined;
+	let model: SidecarModel;
+	try {
+		model = parseSidecar(readFileSync(abs, 'utf8'));
+	} catch {
+		return undefined;
+	}
+	for (const entry of model.entries) {
+		if (entry.kind === 'stuck' && !isEntryAnswered(entry)) return undefined;
+	}
+	for (let i = model.entries.length - 1; i >= 0; i--) {
+		const entry = model.entries[i];
+		if (entry.kind !== 'stuck') continue;
+		if (!isEntryAnswered(entry)) continue;
+		const verb = parseStuckAnswer(entry.answer);
+		if (verb !== undefined) {
+			return {verb, entry};
+		}
+	}
+	return undefined;
+}
+
+/** Input the production stuck-action handler consumes. */
+export interface StuckActionInput {
+	/** The detected action (verb + source entry). */
+	action: DetectedStuckAction;
+	/** The namespaced item identity (`task:<slug>`). */
+	item: string;
+	/** The bare slug (the work branch is `work/task-<slug>`). */
+	slug: string;
+	/** The apply rung's working clone. */
+	cwd: string;
+	/** The arbiter remote NAME in `cwd` (defaults to `origin`). */
+	arbiter: string;
+	/** Environment for child git processes. */
+	env?: NodeJS.ProcessEnv;
+	/** Sink for human-readable progress notes. */
+	note?: (message: string) => void;
+}
+
+/** The terminal verbs the dispatcher reports to the apply rung. */
+export type StuckActionOutcome =
+	/** `answer=keep` -> no action; fall through to the normal apply persist. */
+	| 'keep'
+	/**
+	 * `answer=reset` -> the remote `work/<slug>` branch was DELETED (or was
+	 * already gone); fall through to the normal apply persist so
+	 * `needsAnswers` clears. The `already-gone` sub-case is the safe idempotent
+	 * no-op for an item with no work branch.
+	 */
+	| 'reset'
+	/**
+	 * `answer=cancel` -> the apply rung dispatches through
+	 * `applyAnsweredQuestions`' `dispose` option (task -> `tasks/cancelled/`).
+	 * The answer text is the human's reason.
+	 */
+	| 'cancel'
+	/**
+	 * `answer=reset` -> the branch delete FAILED (a real push-delete error, not
+	 * `already-gone`). The apply rung SHORT-CIRCUITS: the sidecar stays,
+	 * `needsAnswers` stays `true`, no clear — the human sees the failure and
+	 * re-answers. Matches the `requeue --reset` "abort the requeue on a failed
+	 * arbiter delete" behaviour (delete-before-clear ordering, see the module
+	 * docs' partial-failure decision).
+	 */
+	| 'refused';
+
+/** What the production handler returns to the apply rung. */
+export interface StuckActionResult {
+	outcome: StuckActionOutcome;
+	/** Human-readable summary for the rung's message. */
+	message: string;
+}
+
+/**
+ * The injectable dispatch SEAM. Production wires {@link performStuckAction};
+ * tests inject a stub to assert on the apply-rung's routing WITHOUT touching a
+ * real arbiter.
+ */
+export type StuckActionHandler = (
+	input: StuckActionInput,
+) => Promise<StuckActionResult>;
+
+/**
+ * The PRODUCTION dispatcher: an answered `kind: 'stuck'` entry's verb drives
+ * one of the four terminals (`keep` / `reset` / `refused` / `cancel`). For
+ * `answer=reset` it dispatches through the SHARED
+ * {@link deleteRemoteWorkBranchIfPresent} primitive the `requeue --reset` verb
+ * also uses — delete-before-clear ordering, local-first write-through,
+ * already-gone tolerance (safe no-op when no branch exists). For `keep` and
+ * `cancel` there is nothing to do on the git side; the apply rung's normal
+ * fall-through handles the persist (`cancel` via the `dispose` option).
+ */
+export async function performStuckAction(
+	input: StuckActionInput,
+): Promise<StuckActionResult> {
+	const note = input.note ?? (() => {});
+	const {verb} = input.action;
+
+	if (verb === 'keep') {
+		return {
+			outcome: 'keep',
+			message:
+				`stuck-question for ${input.item} answered KEEP — leaving ` +
+				`\`work/task-${input.slug}\` untouched (continue-from-WIP; the answer ` +
+				`is recorded in the item body via the normal apply path).`,
+		};
+	}
+
+	if (verb === 'cancel') {
+		return {
+			outcome: 'cancel',
+			message:
+				`stuck-question for ${input.item} answered CANCEL — dispatching ` +
+				`through the \`dispose\` terminal (\`git mv -> tasks/cancelled/\`).`,
+		};
+	}
+
+	// verb === 'reset'
+	const dropped = await deleteRemoteWorkBranchIfPresent({
+		cwd: input.cwd,
+		arbiter: input.arbiter,
+		slug: input.slug,
+		env: input.env,
+	});
+	if (dropped.status === 'failed') {
+		const stderr = dropped.stderr;
+		const message =
+			`stuck-question for ${input.item} answered RESET — but the arbiter ` +
+			`delete of ${dropped.branch} on ${input.arbiter} failed ` +
+			`(${stderr || 'unknown error'}). NOT clearing needsAnswers; the sidecar ` +
+			`stays surfaced for a re-answer. The local tracking ref was already ` +
+			`cleared (write-through ordering); a subsequent fetch will restore it ` +
+			`from the arbiter — the local store is BEHIND the arbiter ` +
+			`(self-healing), never AHEAD (which would drive a stale continue).`;
+		note(message);
+		return {outcome: 'refused', message};
+	}
+	const droppedLabel =
+		dropped.status === 'deleted'
+			? `Deleted the remote branch ${dropped.branch} on ${input.arbiter}`
+			: `Remote branch ${dropped.branch} on ${input.arbiter} was already gone`;
+	const message =
+		`stuck-question for ${input.item} answered RESET — ${droppedLabel} ` +
+		`(next claim starts fresh).`;
+	note(message);
+	return {outcome: 'reset', message};
+}

package/src/brand.ts

@@ -77,8 +77,19 @@ export interface Brand {
 	readonly base: string;
 	/** The shared env-var prefix: `constantCase(base) + '_'` ⇒ `DORFL_`. */
 	readonly envPrefix: string;
-	/** The per-repo config filename: `.{paramCase(base)}.json` ⇒ `.dorfl.json`. */
+	/**
+	 * The per-repo config filename PREFERRED + written by default:
+	 * `{paramCase(base)}.json` ⇒ `dorfl.json` (a plain, non-dotfile name, so it is
+	 * visible in a normal `ls` and reads like other tool configs).
+	 */
 	readonly repoConfigFilename: string;
+	/**
+	 * The LEGACY per-repo config filename still honoured on READ for backward
+	 * compatibility: `.{paramCase(base)}.json` ⇒ `.dorfl.json` (the original
+	 * dotfile form). Reads prefer {@link repoConfigFilename} and fall back to this;
+	 * writes/`setup` use {@link repoConfigFilename}.
+	 */
+	readonly repoConfigFilenameLegacy: string;
 	/** The workspaces-dir name (a dotfile dir): `.{paramCase(base)}` ⇒ `.dorfl`. */
 	readonly workdirName: string;
 	/** The per-job record filename: `.{paramCase(base)}-job.json` ⇒ `.dorfl-job.json`. */
@@ -95,7 +106,8 @@ export function deriveBrand(base: string): Brand {
 	return {
 		base,
 		envPrefix: constantCase(base) + '_',
-		repoConfigFilename: `.${param}.json`,
+		repoConfigFilename: `${param}.json`,
+		repoConfigFilenameLegacy: `.${param}.json`,
 		workdirName: `.${param}`,
 		jobRecordFilename: `.${param}-job.json`,
 		configDirName: param,

package/src/buildable-body.ts

@@ -1,7 +1,7 @@
 /**
- * The SINGLE owner of the buildable-task (and PRD-body) markdown SECTION SCHEMA
- * (prd `centralize-buildable-task-renderer-shared-by-intake-and-promotion`, US
- * #1/#4/#7). dorfl has TWO independent producers of a buildable task/PRD body —
+ * The SINGLE owner of the buildable-task (and SPEC-body) markdown SECTION SCHEMA
+ * (spec `centralize-buildable-task-renderer-shared-by-intake-and-promotion`, US
+ * #1/#4/#7). dorfl has TWO independent producers of a buildable task/SPEC body —
  * `intake.ts` (`renderBacklogTask`/`renderSpec`, a wrapper+fallback) and
  * `triage-persist.ts` (`buildPromotedBody`, a structured renderer) — and until
  * this module they each HAND-ROLLED the `## What to build` / `## Acceptance
@@ -28,14 +28,14 @@
  *     mechanism prose, and NO `## Acceptance criteria`. Reproduced by omitting
  *     `acceptanceCriteria` and passing the open-questions block + the seed prose.
  *
- * Symmetrically, {@link renderSpecBody} owns the FULL PRD section schema both PRD
- * producers need: intake's default PRD scaffold is `## Problem Statement` +
+ * Symmetrically, {@link renderSpecBody} owns the FULL SPEC section schema both SPEC
+ * producers need: intake's default SPEC scaffold is `## Problem Statement` +
  * `## Solution` + `## User Stories` (reproduced by passing all three), while
- * promotion's structured PRD body is `## Problem Statement` + optional
+ * promotion's structured SPEC body is `## Problem Statement` + optional
  * `## Open questions` (reproduced by omitting `solution`/`userStories`). Each
  * optional section is emitted only when its input is non-empty.
  *
- * `## Prompt` is TASK-ONLY: a PRD is not dispatched by `do`/`run`, so a PRD body
+ * `## Prompt` is TASK-ONLY: a SPEC is not dispatched by `do`/`run`, so a SPEC body
  * carries none (the symmetric reason the task body MUST carry one — the consumer
  * `extractPromptSection`/`resolveTask` in `prompt.ts` throws "has no '## Prompt'
  * section" at dispatch time without it). {@link renderTaskBody} always emits a
@@ -136,28 +136,28 @@ export interface RenderSpecBodyInput {
 	problemStatement: string;
 	/**
 	 * The `## Solution` prose (markdown). OMIT it (or pass empty) to drop the
-	 * section — promotion's structured PRD body carries no Solution section, intake's
-	 * default PRD scaffold does.
+	 * section — promotion's structured SPEC body carries no Solution section, intake's
+	 * default SPEC scaffold does.
 	 */
 	solution?: string;
 	/**
 	 * The `## User Stories` block (markdown, e.g. a numbered list). OMIT it (or pass
-	 * empty) to drop the section — promotion's structured PRD body carries no User
-	 * Stories section, intake's default PRD scaffold does.
+	 * empty) to drop the section — promotion's structured SPEC body carries no User
+	 * Stories section, intake's default SPEC scaffold does.
 	 */
 	userStories?: string;
 	/**
 	 * The `## Open questions` block (markdown). OMIT it (or pass empty) to drop the
-	 * section. A PRD carries NO `## Prompt` (it is not dispatched).
+	 * section. A SPEC carries NO `## Prompt` (it is not dispatched).
 	 */
 	openQuestions?: string;
 }
 
 /**
- * Render a PRD body (the markdown AFTER the frontmatter fence). Emits, in the
+ * Render a SPEC body (the markdown AFTER the frontmatter fence). Emits, in the
  * canonical order, `## Problem Statement`, then `## Solution`, `## User Stories`,
  * and `## Open questions` (each only when its input is given), and NEVER a
- * `## Prompt` — a PRD is a north-star doc, not a dispatchable task. The symmetric twin of
+ * `## Prompt` — a SPEC is a north-star doc, not a dispatchable task. The symmetric twin of
  * {@link renderTaskBody}, owning the FULL SPEC section schema both producers need
  * (intake's default scaffold supplies Problem Statement + Solution + User Stories;
  * promotion's structured body supplies Problem Statement + optional Open

package/src/claim-cas.ts

@@ -10,7 +10,7 @@ import {workItemRel} from './work-layout.js';
  * `scripts/CLAIM-PROTOCOL.md`. This is the first-class `dorfl claim`
  * command (ADR §9: dorfl is the PRIMARY implementation of the claim
  * protocol; `scripts/claim.sh` is retained as the portable, zero-dependency
- * bootstrap / reference). The lock-substrate cut-over (prd
+ * bootstrap / reference). The lock-substrate cut-over (spec
  * `ledger-status-per-item-lock-refs`) has since diverged it from `claim.sh`'s
  * body-move semantics — see the lock note below — but the exit codes are the same.
  *
@@ -26,7 +26,7 @@ import {workItemRel} from './work-layout.js';
  *   3  (legacy) push contention — no longer reachable: the per-item lock never
  *      falsely contends, so there is no retry budget to exhaust
  *
- * UNIFIED PER-ITEM LOCK (prd `ledger-status-per-item-lock-refs` US #1/#15/#16,
+ * UNIFIED PER-ITEM LOCK (spec `ledger-status-per-item-lock-refs` US #1/#15/#16,
  * ADR `ledger-status-on-per-item-lock-refs`): a claim ACQUIRES the item's
  * per-item lock (`action: implement`) via the lock module and writes NOTHING to
  * `main` — the body STAYS at `work/backlog/<slug>.md`. The claimable predicate is
@@ -86,7 +86,7 @@ export interface ClaimCasOptions {
 	 */
 	override?: boolean;
 	/**
-	 * `--allow-backlog` (prd
+	 * `--allow-backlog` (spec
 	 * `do-allow-backlog-drive-staged-tasks-without-promotion`): WIDEN the claimable
 	 * predicate to ALSO accept a `tasks/backlog/`-resident body (staging), so a
 	 * human can drive a staged task in place WITHOUT promoting it to the pool. The
@@ -336,7 +336,7 @@ async function runClaim(
 		}
 	}
 
-	// UNIFIED PER-ITEM LOCK — the WHOLE of the claim now (prd
+	// UNIFIED PER-ITEM LOCK — the WHOLE of the claim now (spec
 	// `ledger-status-per-item-lock-refs` US #1/#15/#16; ADR
 	// `ledger-status-on-per-item-lock-refs`). The interim dual-write is GONE: claim
 	// acquires the item's per-item lock (`action: implement`) and writes NOTHING to

package/src/cli-spinner.ts

@@ -1,6 +1,6 @@
 /**
  * A small, isolated terminal-spinner helper for the standalone
- * `dorfl claim <slug>` CLI command (prd/task `claim-cas-spinner`).
+ * `dorfl claim <slug>` CLI command (spec/task `claim-cas-spinner`).
  *
  * The push the claim CAS performs can take a few seconds (network +
  * arbiter round-trip), so the terminal looked frozen. This helper wraps