dorfl 0.1.1 → 0.2.0

package/src/tasking-lock.ts

@@ -1,25 +1,22 @@
 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';
 
 /**
- * The **tasking concurrency lock** (prd `auto-slice`, task `autoslice-lock`).
+ * The **tasking concurrency lock** (spec `auto-slice`, task `autoslice-lock`).
  *
- * Serialises *concurrent* taskers (two CI runs, or human + CI) so a prd is never
+ * Serialises *concurrent* taskers (two CI runs, or human + CI) so a spec is never
  * double-tasked. As of the capstone cut-over (task
- * `cutover-retire-slicing-advancing-markers-and-trim-folder-sets`, prd
+ * `cutover-retire-slicing-advancing-markers-and-trim-folder-sets`, spec
  * `ledger-status-per-item-lock-refs`; ADR `ledger-status-on-per-item-lock-refs`)
- * the legacy `git mv work/prds/ready/<slug>.md → work/tasking/<slug>.md` MARKER on `main`
+ * the legacy `git mv work/specs/ready/<slug>.md → work/tasking/<slug>.md` MARKER on `main`
  * is GONE: the body NEVER relocates until the durable promotion, exactly as claim
  * no longer moves the task body (task
  * `cutover-claim-body-stays-and-complete-sources-from-backlog`). The tasking lock
  * is now ONLY the UNIFIED per-item lock (`refs/dorfl/lock/<entry>`,
- * `action: task`, keyed `prd:<slug>`) — the SAME ref claim and advance use for
- * the same item, so tasking a prd is mutually exclusive with claiming/advancing
+ * `action: task`, keyed `spec:<slug>`) — the SAME ref claim and advance use for
+ * the same item, so tasking a spec is mutually exclusive with claiming/advancing
  * the SAME item BY CONSTRUCTION (the second acquirer loses the SAME create-only
  * ref CAS, with NO retry budget and NO false contention). There is no transient
  * status in `main`'s tree anymore, so a work branch cut from `main` inherits no
@@ -29,15 +26,16 @@ import {workItemRel} from './work-layout.js';
  *   A `lost` (the item is already held for implement/task/advance) makes the
  *   tasking acquire lose DEFINITIVELY (exit 2, no retry). On a successful acquire
  *   it returns {@link AcquireTaskingLockResult.lockedBlob}: the git blob sha of the
- *   prd body the lock TOOK, read from `work/prds/ready/<slug>.md` on the arbiter — the
+ *   spec body the lock TOOK, read from `work/specs/ready/<slug>.md` on the arbiter — the
  *   snapshot the tasker reads + tasks from, handed back so the integrate
- *   transition can fail loud if the held prd was edited concurrently (the
+ *   transition can fail loud if the held spec was edited concurrently (the
  *   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
@@ -51,13 +49,13 @@ import {workItemRel} from './work-layout.js';
  * The READ-STABILITY backstop (the content-identity stale check that used to live
  * in the release, comparing the held `work/tasking/<slug>.md` blob against the
  * acquire-time snapshot) now lives at the integrate seam (`tasking.ts`
- * `heldSpecIsStale`, comparing `work/prds/ready/<slug>.md`) — relocated because the
+ * `heldSpecIsStale`, comparing `work/specs/ready/<slug>.md`) — relocated because the
  * completing transition, not the release, owns the commit. See
  * `work/notes/observations/tasking-lock-does-not-stabilise-prd-content.md`.
  *
- * This module provides the lock PRIMITIVES only. The orchestrating `do prd:<slug>`
+ * 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.
  */
 
@@ -74,7 +72,7 @@ export type AcquireTaskingLockOutcome =
 export type AcquireTaskingLockExitCode = 0 | 1 | 2 | 3;
 
 export interface AcquireTaskingLockOptions {
-	/** The prd slug to lock (`work/prds/ready/<slug>.md`). */
+	/** The spec slug to lock (`work/specs/ready/<slug>.md`). */
 	slug: string;
 	/** Working clone/worktree the lock acquire runs in. */
 	cwd: string;
@@ -98,10 +96,10 @@ export interface AcquireTaskingLockResult {
 	/** Human-readable summary of the terminal condition. */
 	message: string;
 	/**
-	 * On a successful acquire (`acquired`), the git BLOB sha of the prd body that
-	 * the lock TOOK (`work/prds/ready/<slug>.md` on the arbiter). This IS the snapshot the
+	 * On a successful acquire (`acquired`), the git BLOB sha of the spec body that
+	 * the lock TOOK (`work/specs/ready/<slug>.md` on the arbiter). This IS the snapshot the
 	 * tasker reads + tasks from; the integrate transition compares the current
-	 * `work/prds/ready/<slug>.md` blob against it to fail loud on a concurrent edit (the
+	 * `work/specs/ready/<slug>.md` blob against it to fail loud on a concurrent edit (the
 	 * read-stability backstop). `undefined` unless `outcome === 'acquired'` (and on
 	 * dry-run, where nothing was published).
 	 */
@@ -157,7 +155,7 @@ async function runAcquire(
 	}
 	const by = options.by || (await resolveBy(cwd, env));
 
-	// Is the prd still lockable (present in work/prds/ready/ on the arbiter's main)?
+	// Is the spec still lockable (present in work/specs/ready/ on the arbiter's main)?
 	await gitHard(['fetch', '--quiet', arbiter], cwd, env);
 	const spec = workItemRel('specs-ready', `${slug}.md`);
 	const specBlob = await gitSoft(
@@ -166,7 +164,7 @@ async function runAcquire(
 		env,
 	);
 	if (specBlob.status !== 0) {
-		const message = `'${spec}' not found on ${arbiter}/main (no such prd, or it was already moved/tasked).`;
+		const message = `'${spec}' not found on ${arbiter}/main (no such spec, or it was already moved/tasked).`;
 		note(message);
 		return {exitCode: 2, outcome: 'lost', message};
 	}
@@ -180,18 +178,17 @@ async function runAcquire(
 		return {exitCode: 0, outcome: 'acquired', message, lockedBlob};
 	}
 
-	// Acquire the UNIFIED per-item lock (`action: task`, keyed `prd:<slug>` so it
+	// Acquire the UNIFIED per-item lock (`action: task`, keyed `spec:<slug>` so it
 	// shares the ONE ref with claim/advance of the SAME item). A create-only ref
 	// CAS: the winner holds it, the loser is DEFINITIVELY `lost` (exit 2, no retry
 	// budget). No auto-steal of an orphaned lock, consistent with claim/advance and
 	// the ADR's recovery model (no liveness heartbeat / auto-sweep; a human asserts
 	// a lock is dead via `release-lock` + `gc --ledger`).
-	// MIGRATE step (prd `prd-to-spec-vocabulary-cutover-and-migration-command`):
-	// EMIT the parent-spec item identity as `spec:<slug>` so the unified per-item
-	// lock ref is `refs/dorfl/lock/spec-<slug>` (the expand-lock task made
-	// `spec:<slug>` resolve to a `spec-<slug>` entry). The resolver still ACCEPTS
-	// `prd:<slug>`, so any lock taken under the old identity stays readable; the
-	// contract task removes the legacy form.
+	// 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).
 	const lock = await acquireItemLock({
 		item: `spec:${slug}`,
 		action: 'task',
@@ -228,7 +225,7 @@ export type ReleaseTaskingLockOutcome =
 export type ReleaseTaskingLockExitCode = 0 | 1 | 2 | 3 | 4;
 
 export interface ReleaseTaskingLockOptions {
-	/** The prd slug whose lock to release. */
+	/** The spec slug whose lock to release. */
 	slug: string;
 	/** Working clone/worktree the release runs in. */
 	cwd: string;
@@ -249,9 +246,9 @@ export interface ReleaseTaskingLockOptions {
 	/**
 	 * The tasker review→edit LOOP's **decomposition-unclear** verdict
 	 * (`slicer-review-edit-loop`), or the task-SET acceptance gate's `block`:
-	 * instead of DELETING the lock (returning the prd to the claimable/taskable
+	 * instead of DELETING the lock (returning the spec to the claimable/taskable
 	 * pool), amend it `active → stuck` with this reason recorded on the entry,
-	 * emitting NO guessed tasks. The prd body stays in `work/prds/ready/` (it never moved
+	 * emitting NO guessed tasks. The spec body stays in `work/specs/ready/` (it never moved
 	 * under the lock); the stuck lock IS the tasking needs-attention surface (no
 	 * `work/needs-attention/` folder write), so it is NOT re-taskable until a human
 	 * resolves it via `release-lock`/`resume`. Omitted ⇒ the normal release DELETES
@@ -274,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,
- * and the prd body never left `work/prds/ready/` under the lock, so there is no
- * `tasking/ → prd/` restore.
+ * 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/ → specs/ready/` restore.
  *
  * When `routeToNeedsAttention` is set (the tasker decomposition-unclear verdict /
  * the task-SET acceptance gate `block`), the lock is AMENDED `active → stuck`
@@ -326,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 prd body stays in `work/prds/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).