dorfl 0.1.2 → 0.2.0

package/src/start.ts

@@ -122,7 +122,8 @@ class StartUsageError extends Error {}
 /**
  * Raised for a deliberate REFUSAL (exit 1, outcome 'refused') — distinct from a
  * usage/environment error. Used when the item exists but start declines to act
- * (an in-progress item without --resume). The decision is folder-based.
+ * (an in-progress item without --resume). The decision is LOCK-based (a held
+ * `active` per-item lock), not a `work/in-progress/` folder read.
  */
 class StartRefusal extends Error {}
 
@@ -262,11 +263,11 @@ async function dispatchFolder(
 	if (!inPool) {
 		return folder;
 	}
-	// In the pool/staging: claimed-ness + stuck-ness are the per-item lock, not the folder.
+	// In the pool/staging: claimed-ness is the per-item lock (not the folder).
+	// Post-`retire-stuck-lock-state` there is no `stuck` state — a parked item is
+	// a `needsAnswers:true` pool item on `main` (rendered by status/scan and
+	// drained by the apply rung), NEVER a lock re-key.
 	const lock = await readItemLock({item: `task:${slug}`, cwd, arbiter, env});
-	if (lock && lock.state === 'stuck') {
-		return 'needs-attention';
-	}
 	if (lock && lock.state === 'active') {
 		return 'in-progress';
 	}
@@ -404,7 +405,7 @@ async function continueConflictResult(params: {
 	}
 	const message =
 		`Could not continue '${params.slug}': the kept work branch did not rebase ` +
-		`cleanly onto ${params.arbiter}/main; routed to work/needs-attention/ ` +
+		`cleanly onto ${params.arbiter}/main; marked stuck on its per-item lock ` +
 		'(surfaced by status). Resolve against the latest main, or `requeue --reset` ' +
 		'to discard and start fresh.';
 	return {
@@ -438,8 +439,8 @@ async function continuePushFailureResult(params: {
 	}
 	const message =
 		`Could not continue '${params.slug}': publishing the rebased work branch to ` +
-		`${params.arbiter} failed terminally (${params.pushFailure}); routed to ` +
-		'work/needs-attention/ (surfaced by status), the kept branch left intact on ' +
+		`${params.arbiter} failed terminally (${params.pushFailure}); marked stuck ` +
+		'on its per-item lock (surfaced by status), the kept branch left intact on ' +
 		'the arbiter (recoverable). `requeue` to retry once the churn settles.';
 	return {
 		exitCode: 1,
@@ -465,42 +466,17 @@ async function startFromNeedsAttention(params: {
 }): Promise<StartResult> {
 	const {slug, arbiter, cwd, env, note} = params;
 
-	// Surface the recorded reason for the human, read from the STUCK LOCK ENTRY
-	// (task `cutover-needs-attention-becomes-lock-stuck-recovery-surface`: the lock
-	// is the sole stuck record — no `needs-attention/` folder file). The full reason
-	// prose + any surfaced questions ride on the lock entry body.
-	const stuck = await readItemLock({item: `task:${slug}`, cwd, arbiter, env});
-	if (stuck?.reason) {
-		note(`'${slug}' is stuck (needs-attention): ${stuck.reason}`);
-	} else {
-		note(`'${slug}' is stuck (needs-attention) — picking it up.`);
-	}
-	if (stuck?.questions && stuck.questions.length > 0) {
-		note('Surfaced questions:');
-		for (const q of stuck.questions) {
-			note(`  - ${q}`);
-		}
-	}
-
-	// Resume the lock `stuck → active` THROUGH the write seam (a pure lock amend, NO
-	// `main` write, NO temp checkout — the body already rests in `backlog/` and the
-	// work stays on the kept `work/<slug>` branch), then onboard onto work/<slug>.
-	const resolved = await ledgerWrite.applyResolveNeedsAttentionTransition({
-		cwd,
-		slug,
-		arbiter,
-		env,
-		note,
-	});
-	if (!resolved.moved) {
-		throw new StartUsageError(
-			resolved.reasonNotMoved ??
-				`could not resolve '${slug}' from needs-attention.`,
-		);
-	}
+	// Post-`retire-stuck-lock-state`: the `stuck` lock state is gone; a parked
+	// item is a `needsAnswers:true` pool item on `main` drained by the apply
+	// rung (answer the sidecar). This branch fires only when a LEGACY
+	// `needs-attention/` folder body still exists on `<arbiter>/main` (no
+	// live path lands one). Onboard the human onto the kept work branch — no
+	// lock amend, no reason/questions read from the lock (those live on the
+	// surfaced sidecar now).
+	note(
+		`'${slug}' is in the legacy needs-attention/ folder — onboarding onto its work branch; answer any question sidecar on main to drain it.`,
+	);
 
-	// The lock is back to active (the human owns it). Onboard onto the work branch:
-	// CONTINUE from a kept arbiter work/<slug> when present, else fresh off main.
 	const switched = await switchToWorkBranch({slug, arbiter, cwd, env, note});
 	if (switched.rebaseConflict) {
 		return continueConflictResult({slug, arbiter, cwd, env, note});
@@ -522,10 +498,14 @@ async function startFromNeedsAttention(params: {
 }
 
 /**
- * In-progress → already claimed (it is no longer in backlog, so the CAS cannot
- * apply). Refuse by default. With --resume the human explicitly asserts
+ * In-progress → already claimed (the per-item LOCK is held `active`, so the CAS
+ * cannot apply). Refuse by default. With --resume the human explicitly asserts
  * ownership, so we switch to the work branch WITHOUT claiming. The decision is
- * folder-based; we never read the advisory `claimed_by` to guess ownership.
+ * LOCK-based: `dispatchFolder` reaches here only when the lock is held `active`
+ * (the body rests in the pool/staging, NOT a `work/in-progress/` folder file —
+ * the folder cutover retired that path,
+ * `finish-in-progress-folder-cutover-remove-legacy-recovery-readers`). We never
+ * read the advisory `claimed_by` to guess ownership.
  */
 async function startFromInProgress(params: {
 	slug: string;
@@ -538,10 +518,11 @@ async function startFromInProgress(params: {
 	const {slug, arbiter, cwd, env, resume, note} = params;
 
 	if (!resume) {
-		// The folder drove the decision (WORK-CONTRACT rule 6: the folder + git
-		// history are the source of truth). We do NOT name the claimer in the
-		// message; whoever holds it is read from git history
-		// (`git log work/in-progress/<slug>.md`).
+		// The held LOCK drove the decision (the per-item lock is the source of truth
+		// for liveness now — the body stays in the pool, no `work/in-progress/` file).
+		// We do NOT name the claimer in the message; whoever holds it is read from git
+		// history (`git log` over the item's `work/tasks/ready/<slug>.md` + the lock
+		// ref history).
 		throw new StartRefusal(
 			`'${slug}' is already in-progress; see \`git log\` for who claimed it; ` +
 				'if this is your own work, re-run with --resume.',
@@ -816,8 +797,9 @@ function surfaceUnmovedStartResult(params: {
  * TREE-LESS (`#89` mechanism), the SAME-PROFILE sibling of
  * {@link routeContinuePushFailure}: the rebase was ABORTED, so the REAL continued
  * `work/<slug>` is already on the arbiter from the prior requeue, untouched
- * (after-commit, durable, recoverable). The surface is PURELY the one-file
- * `in-progress/ → needs-attention/` ledger `.md` move + reason — we publish it via
+ * (after-commit, durable, recoverable). The surface is PURELY the lock amend to
+ * `state: stuck` with the reason (post lock-cutover — no `in-progress/ →
+ * needs-attention/` folder move) — we publish it via
  * the tree-less surface CAS (the SAME no-checkout primitive `requeue` uses for the
  * reverse direction), NO temp-branch switch/restore, NO `pushBranch`, NO worktree.
  */
@@ -831,8 +813,10 @@ async function routeContinueConflict(params: {
 	const {slug, arbiter, cwd, env, note} = params;
 	const reason =
 		`continuing the kept ${arbiter}/${workBranchRef('task', slug)}: rebase onto ` +
-		`${arbiter}/main conflicted (aborted, never auto-resolved) — resolve ` +
-		'against the latest main, or `requeue --reset` to discard and start fresh';
+		`${arbiter}/main conflicted (aborted, never auto-resolved) — run ` +
+		'`requeue --reconcile` to non-destructively re-sync the mirror and retry ' +
+		'the rebase (keeps the work). Last resort: `requeue --reset` ' +
+		'DESTRUCTIVELY discards the branch and starts fresh.';
 	note(reason);
 	// PROPAGATE the {moved, reasonNotMoved} result to the caller so a `moved:false`
 	// (the surface did NOT reach main — lost the CAS race) is surfaced honestly
@@ -857,8 +841,9 @@ async function routeContinueConflict(params: {
  * TREE-LESS (`#89` mechanism): the recoverable artifact — the kept `work/<slug>`
  * — is ALREADY on the arbiter from the prior requeue (our local rebased tip is
  * what FAILED to push, so it is not the cross-machine truth), and the work is
- * already committed. So the surface is PURELY the one-file `in-progress/ →
- * needs-attention/` ledger `.md` move + reason: we publish it via the tree-less
+ * already committed. So the surface is PURELY the lock amend to `state: stuck`
+ * with the reason (post lock-cutover — no `in-progress/ → needs-attention/`
+ * folder move): we publish it via the tree-less
  * surface CAS (the SAME no-checkout primitive `requeue` uses for the reverse
  * direction) — NO temp-branch switch/restore, NO `pushBranch`, NO worktree. A
  * `requeue` then continues from the kept arbiter tip.
@@ -875,8 +860,10 @@ async function routeContinuePushFailure(params: {
 	const reason =
 		`continuing the kept ${arbiter}/${workBranchRef('task', slug)}: publishing ` +
 		`the rebased work branch to ${arbiter} failed terminally (${pushFailure}) — ` +
-		'the kept branch is left intact on the arbiter (recoverable); `requeue` to ' +
-		'retry once the churn settles, or `requeue --reset` to discard and start fresh';
+		'the kept branch is left intact on the arbiter (recoverable); `requeue ' +
+		'--reconcile` to non-destructively re-sync the mirror and retry once the ' +
+		'churn settles (keeps the work). Last resort: `requeue --reset` ' +
+		'DESTRUCTIVELY discards the branch and starts fresh.';
 	note(reason);
 	// PROPAGATE the {moved, reasonNotMoved} result to the caller so a `moved:false`
 	// (the surface did NOT reach main — lost the CAS race) is surfaced honestly
@@ -936,7 +923,14 @@ async function folderOnArbiterMain(
 	)[] = [
 		'tasks-ready',
 		...(allowBacklog ? (['tasks-backlog'] as const) : []),
-		'in-progress',
+		// NOTE: `work/in-progress/` is NOT probed (task
+		// `finish-in-progress-folder-cutover-remove-legacy-recovery-readers`): the
+		// per-item-lock cutover moved claim OFF writing that folder, so nothing lands a
+		// body there. A claimed-and-in-flight item RESTS in the pool/staging on `main`
+		// with the held lock as its liveness — `dispatchFolder` re-keys THAT to the
+		// `in-progress` dispatch off the LOCK (`state: active`), never a folder read.
+		// (`needs-attention/` is likewise the lock `state: stuck`; its retained probe is
+		// a separate cutover's concern, left untouched here.)
 		'needs-attention',
 		'done',
 	];

package/src/surface-gate.ts

@@ -252,9 +252,16 @@ export function buildSurfacePrompt(item: string): string {
 		` "note": "… (optional; your reasoning / findings prose lives HERE, not outside the object)"}`,
 		'```',
 		``,
-		`An EMPTY \`questions\` array is a VALID, honest result (no open judgement) —`,
-		`emit the object with \`"questions": []\` (put WHY in \`note\`); do NOT replace`,
-		`it with a prose explanation. Absence of the field is NOT valid.`,
+		`RULE — empty is VALID, absence is NOT. When there is nothing to ask (no open`,
+		`judgement to surface), you MUST STILL emit the JSON object, with`,
+		`\`"questions": []\` (an empty array); put any explanation of WHY in the`,
+		`\`note\` field INSIDE the object. Do NOT replace the object with a prose`,
+		`sentence like "no open questions", do NOT skip the emit, and do NOT drop the`,
+		`\`questions\` field. The parser (\`parseSurfaceEmit\`) enforces this: an empty`,
+		`\`questions\` array is a valid, honest "no open judgement" result; ABSENCE of`,
+		`the \`questions\` field is rejected as an unparseable emit — that failure is`,
+		`what strands the surface rung. Emitting \`{"questions": [], "note": "…"}\` is`,
+		`ALWAYS the safe, honest close for a nothing-to-ask item.`,
 		``,
 		// The SHARED defensive-JSON contract (the same hardening Gate-2's verdict
 		// prompt carries) — the surface rung hit the IDENTICAL unparseable-emit

package/src/surface-persist.ts

@@ -192,7 +192,7 @@ export function persistSurfacedQuestions(
 
 	// Write the appended/created sidecar.
 	mkdirSync(dirname(sidecarAbs), {recursive: true});
-	writeFileSync(sidecarAbs, serialiseSidecar(model));
+	writeFileSync(sidecarAbs, serialiseSidecar(model, {repoRoot: cwd}));
 
 	// Stage exactly the two paths and commit them TOGETHER (one atomic commit) —
 	// the sidecar write + the `needsAnswers:true` flip land in the SAME commit, so

package/src/tasker-review-loop.ts

@@ -52,7 +52,7 @@ export {parseReviewVerdict as parseTaskReviewVerdict} from './review-verdict.js'
  *     applyEdits(…to disk…) }` — ONE agent LAUNCH per pass, the runner writing the
  *     agent's edits to the candidate task FILES (`work/tasks/backlog/`) between passes, the
  *     next pass's agent re-reading the edited files. Accumulation is via DISK +
- *     re-launch, NOT one agent retaining context. `prd/review.md` §Shape 2 is internally
+ *     re-launch, NOT one agent retaining context. `spec/review.md` §Shape 2 is internally
  *     contradictory on this (single-context headline vs "edit the files" operative spec);
  *     this code implements the operative reading. See
  *     `work/findings/review-edit-loop-single-context-is-unbuilt-aspiration-vs-per-pass-disk-impl.md`.
@@ -75,8 +75,9 @@ export {parseReviewVerdict as parseTaskReviewVerdict} from './review-verdict.js'
  *   - **a specific uncertain task** → emit it `needsAnswers: true` with the
  *     questions in its body (created, not agent-buildable until a human answers).
  *   - **the whole decomposition unclear / `taskerLoopMax` exhausted with blockers** →
- *     route the spec to `work/needs-attention/<slug>.md` with the questions as the
- *     reason, emitting NO guessed tasks.
+ *     mark the spec stuck on its per-item lock (post lock-cutover — `state: stuck`
+ *     with the questions as the reason, no `work/needs-attention/` folder write),
+ *     emitting NO guessed tasks.
  *
  * The verdict sink itself (the git transitions for those three outcomes) is the
  * caller's (`tasking.ts`): this module decides WHICH outcome and prepares the

package/src/tasking-lock.ts

@@ -1,9 +1,6 @@
 import {runAsync, type RunResult} from './git.js';
-import {
-	acquireItemLock,
-	releaseItemLock,
-	markStuckItemLock,
-} from './item-lock.js';
+import {acquireItemLock, releaseItemLock, readItemLock} from './item-lock.js';
+import {surfaceStuckToNeedsAttention} from './needs-attention.js';
 import {workItemRel} from './work-layout.js';
 
 /**
@@ -35,9 +32,10 @@ import {workItemRel} from './work-layout.js';
  *   read-stability backstop). A dry-run takes no lock (it mutates nothing).
  *
  * - **Release** ({@link releaseTaskingLock}) DELETES the unified lock ref. It
- *   moves NO lifecycle file: the durable `prd → prd-tasked` success move is owned
- *   by the integrate band (`tasking.ts`/`integration-core.ts`), and there is no
- *   `tasking/ → prd/` abort bounce anymore (the body never left `prd/`). When
+ *   moves NO lifecycle file: the durable `specs/ready → specs/tasked` success move
+ *   is owned by the integrate band (`tasking.ts`/`integration-core.ts`), and there
+ *   is no `tasking/ → specs/ready/` abort bounce anymore (the body never left
+ *   `specs/ready/`). When
  *   `routeToNeedsAttention` is set (the tasker review/edit loop's
  *   decomposition-unclear verdict, or the task-SET acceptance gate's `block`),
  *   release amends the lock `active → stuck` with the reason on the entry INSTEAD
@@ -57,7 +55,7 @@ import {workItemRel} from './work-layout.js';
  *
  * This module provides the lock PRIMITIVES only. The orchestrating `do spec:<slug>`
  * tasking command (`tasking.ts`) acquires, drives the agent's tasking, integrates
- * the emitted tasks + the durable `prd → prd-tasked` move, and releases. The
+ * the emitted tasks + the durable `specs/ready → specs/tasked` move, and releases. The
  * human path (no contention) may task on `main` directly without the lock.
  */
 
@@ -188,9 +186,9 @@ async function runAcquire(
 	// a lock is dead via `release-lock` + `gc --ledger`).
 	// Spec `prd-to-spec-vocabulary-cutover-and-migration-command`: the parent-spec
 	// item identity is `spec:<slug>`, so the unified per-item lock ref is
-	// `refs/dorfl/lock/spec-<slug>`. HARD CUTOVER: the legacy `prd:<slug>` identity
-	// is GONE — the resolver no longer treats `prd:` as the spec namespace (a
-	// `prd:<slug>` arg is a bare literal task slug now).
+	// `refs/dorfl/lock/spec-<slug>`. HARD CUTOVER: the legacy ''prd:<slug>'' identity
+	// is GONE — the resolver no longer treats ''prd:'' as the spec namespace (a
+	// ''prd:<slug>'' arg is a bare literal task slug now).
 	const lock = await acquireItemLock({
 		item: `spec:${slug}`,
 		action: 'task',
@@ -273,9 +271,9 @@ export interface ReleaseTaskingLockResult {
 /**
  * Release the tasking lock for `slug`: DELETE the unified `action: task` lock ref
  * (idempotent — an already-absent ref is a clean `released`). It moves NO lifecycle
- * file: the durable `prd → prd-tasked` success move is owned by the integrate band,
+ * file: the durable `specs/ready → specs/tasked` success move is owned by the integrate band,
  * and the spec body never left `work/specs/ready/` under the lock, so there is no
- * `tasking/ → prd/` restore.
+ * `tasking/ → specs/ready/` restore.
  *
  * When `routeToNeedsAttention` is set (the tasker decomposition-unclear verdict /
  * the task-SET acceptance gate `block`), the lock is AMENDED `active → stuck`
@@ -325,33 +323,51 @@ async function runRelease(
 		);
 	}
 
-	// DECOMPOSITION-UNCLEAR / TASK-GATE BLOCK: amend the lock `active → stuck` with
-	// the reason on the entry (the tasking needs-attention surface), NOT delete it.
-	// The spec body stays in `work/specs/ready/`; the stuck lock keeps it out of the
-	// taskable pool until a human resolves it (`release-lock`/`resume`).
+	// DECOMPOSITION-UNCLEAR / TASK-GATE BLOCK: surface the spec as a `stuck`-kind
+	// sidecar + `needsAnswers:true` on the spec body in ONE commit on
+	// `<arbiter>/main`, THEN release the tasking lock (PR-2b, spec
+	// `surface-stuck-as-questions-and-retire-stuck-lock-state`, decision #1). The
+	// spec body stays in `work/specs/ready/` (or `work/specs/proposed/` — the D1
+	// probe finds it); the surfaced question keeps the spec out of the taskable
+	// pool via `needsAnswers:true` (eligibility `false`) until a human answers.
 	if (options.routeToNeedsAttention !== undefined) {
-		// MIGRATE: EMIT `spec:<slug>` (keyed to the `spec-<slug>` lock entry).
-		const stuck = await markStuckItemLock({
-			item: `spec:${slug}`,
-			reason: options.routeToNeedsAttention.reason,
-			cwd,
-			arbiter,
-			env,
-		});
-		if (stuck.outcome === 'transitioned' || stuck.outcome === 'wrong-state') {
-			// `wrong-state` (already stuck) is a tolerated idempotent re-surface.
-			const message = `Routed the tasking of '${slug}' to needs-attention (per-item lock marked stuck).`;
+		const item = `spec:${slug}`;
+		// Detect a genuinely NOT-HELD lock BEFORE the surface (so a bounce of an
+		// unlocked spec still returns the exit-2 `lost` contract). The surface itself
+		// is idempotent, but without this pre-check a not-held spec would surface
+		// silently on main with no lock to release — losing the caller-visible
+		// "nothing to route" signal.
+		const held = await readItemLock({item, cwd, arbiter, env});
+		if (held === undefined) {
+			const message = `'${slug}' is not locked for tasking — nothing to route to needs-attention.`;
 			note(message);
-			return {exitCode: 0, outcome: 'released', message};
+			return {exitCode: 2, outcome: 'lost', message};
 		}
-		if (stuck.outcome === 'not-held') {
-			const message = `'${slug}' is not locked for tasking — nothing to mark stuck.`;
+		try {
+			const surfaced = await surfaceStuckToNeedsAttention({
+				cwd,
+				slug,
+				item,
+				reason: options.routeToNeedsAttention.reason,
+				arbiter,
+				env,
+				note,
+			});
+			if (surfaced.surfaced || surfaced.bodyAbsent) {
+				const message = surfaced.surfaced
+					? `Routed the tasking of '${slug}' to needs-attention (surfaced on ${arbiter}/main; tasking lock released).`
+					: `Routed the tasking of '${slug}' to needs-attention (no spec body on ${arbiter}/main — clean no-op surface; tasking lock released).`;
+				note(message);
+				return {exitCode: 0, outcome: 'released', message};
+			}
+			const message = `could not surface '${item}' on ${arbiter}/main (${surfaced.reasonNotSurfaced ?? 'unknown'}).`;
 			note(message);
-			return {exitCode: 2, outcome: 'lost', message};
+			return {exitCode: 1, outcome: 'usage-error', message};
+		} catch (err) {
+			const message = `could not surface '${item}' on ${arbiter}/main (${err instanceof Error ? err.message : String(err)}).`;
+			note(message);
+			return {exitCode: 1, outcome: 'usage-error', message};
 		}
-		const message = `could not mark the per-item lock for '${slug}' stuck (${stuck.outcome}: ${stuck.message}).`;
-		note(message);
-		return {exitCode: 1, outcome: 'usage-error', message};
 	}
 
 	// NORMAL release: delete the lock ref (idempotent).