dorfl 0.1.1 → 0.2.0

package/src/start.ts

@@ -78,7 +78,7 @@ export interface StartOptions {
 	 */
 	override?: boolean;
 	/**
-	 * `--allow-backlog` (prd
+	 * `--allow-backlog` (spec
 	 * `do-allow-backlog-drive-staged-tasks-without-promotion`): recognise a
 	 * `tasks/backlog/`-resident body (staging) as a valid start/onboard residence,
 	 * so the no-checkout `do --remote/--isolated … --allow-backlog` flow (which
@@ -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 {}
 
@@ -236,7 +237,7 @@ async function runStart(
  *     resume the lock `stuck → active`, onboard).
  * Everything else dispatches by folder unchanged.
  *
- * Under `--allow-backlog` (prd
+ * Under `--allow-backlog` (spec
  * `do-allow-backlog-drive-staged-tasks-without-promotion`) a body resting in
  * `tasks/backlog/` (staging) is treated EXACTLY like the pool for this re-key
  * (held active ⇒ in-progress; held stuck ⇒ needs-attention; else the backlog
@@ -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.',
@@ -620,7 +601,7 @@ async function switchToWorkBranch(params: {
 }): Promise<SwitchResult> {
 	const {slug, arbiter, cwd, env, note} = params;
 	// `start` is a TASK-only command: the branch is the task-namespaced
-	// `work/task-<slug>` (distinct from a same-slug prd-tasking branch).
+	// `work/task-<slug>` (distinct from a same-slug spec-tasking branch).
 	const branch = workBranchRef('task', slug);
 
 	await gitHard(['fetch', '--quiet', arbiter], cwd, env);
@@ -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
@@ -909,7 +896,7 @@ async function inferSlugFromBranch(
 
 /**
  * Which work/ folder the slug currently lives in on `<arbiter>/main`. Under
- * `--allow-backlog` (prd `do-allow-backlog-drive-staged-tasks-without-promotion`)
+ * `--allow-backlog` (spec `do-allow-backlog-drive-staged-tasks-without-promotion`)
  * it ALSO recognises `tasks/backlog/` (staging) at LOWEST priority — after the
  * pool — so a same-slug pool copy still wins; otherwise staging is invisible.
  */
@@ -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/status.ts

@@ -81,7 +81,7 @@ export interface JobStatus {
 }
 
 /**
- * One repo's PER-ITEM LOCK refs, surfaced for the dashboard (prd
+ * One repo's PER-ITEM LOCK refs, surfaced for the dashboard (spec
  * `ledger-status-per-item-lock-refs` US #8; task
  * `needs-attention-as-stuck-lock-state`). The in-flight view read from the lock
  * refs — held (`active` = in-progress) and stuck (`needs-attention`) entries +
@@ -111,7 +111,7 @@ export interface StatusReport {
 	/** Stuck (needs-attention), crashed (running-but-dead), or un-reaped (done) jobs. */
 	attention: JobStatus[];
 	/**
-	 * The PER-ITEM LOCK in-flight view (prd `ledger-status-per-item-lock-refs` US
+	 * The PER-ITEM LOCK in-flight view (spec `ledger-status-per-item-lock-refs` US
 	 * #8; task `needs-attention-as-stuck-lock-state`): per registered hub mirror,
 	 * the held lock entries read from the mirror's `refs/dorfl/lock/*` refs —
 	 * `active` holds (in-progress) and `stuck` holds (needs-attention) + reasons.
@@ -124,7 +124,7 @@ export interface StatusReport {
 	 */
 	lockHeld?: RepoLockEntries[];
 	/**
-	 * The one-slug-one-folder LINT (prd `ledger-integrity` story 3): per registered
+	 * The one-slug-one-folder LINT (spec `ledger-integrity` story 3): per registered
 	 * hub mirror, any slug present in MORE THAN ONE `work/` status folder (a corrupt
 	 * ledger). Read from the mirror's bare `main` ref (the SAME `ls-tree` source the
 	 * needs-attention surface uses). Only repos WITH a duplicate appear. `status`
@@ -235,7 +235,7 @@ export async function status(options: StatusOptions): Promise<StatusReport> {
 		// reflects the remote truth. Never fatal — a failed fetch WARNS and falls back
 		// to the mirror's last-known `main`.
 		fetchMirrorMainOrWarn({mirrorPath, warn: options.warn, env: options.env});
-		// The PER-ITEM LOCK in-flight view (prd US #8): read the mirror's lock refs to
+		// The PER-ITEM LOCK in-flight view (spec US #8): read the mirror's lock refs to
 		// surface held (`active` = in-progress) and stuck (`needs-attention`) entries +
 		// reasons/questions. A bare hub mirror's arbiter is its `origin` (the SAME
 		// handle the `scan` held-slug subtraction reads). Best-effort: a fetch/read
@@ -249,7 +249,7 @@ export async function status(options: StatusOptions): Promise<StatusReport> {
 		if (entries.length > 0) {
 			lockHeld.push({repoPath: mirrorPath, entries});
 		}
-		// The one-slug-one-folder LINT (prd story 3): derive any slug residing in >1
+		// The one-slug-one-folder LINT (spec story 3): derive any slug residing in >1
 		// status folder from the SAME freshly-fetched `main` ref, surfaced LOUDLY.
 		const dups = lintRefLedger('main', mirrorPath, options.env);
 		if (dups.length > 0) {
@@ -359,7 +359,7 @@ export function formatStatus(report: StatusReport): string {
 		}
 	}
 
-	// The PER-ITEM LOCK in-flight view (prd US #8; task
+	// The PER-ITEM LOCK in-flight view (spec US #8; task
 	// `cutover-needs-attention-becomes-lock-stuck-recovery-surface`): the held lock
 	// refs read from each mirror — `active` holds (in-progress) and `stuck` holds
 	// (needs-attention) + their reasons/questions. This is the SOLE stuck-state
@@ -377,7 +377,7 @@ export function formatStatus(report: StatusReport): string {
 		}
 	}
 
-	// The one-slug-one-folder LINT (prd `ledger-integrity` story 3): WARN LOUDLY
+	// The one-slug-one-folder LINT (spec `ledger-integrity` story 3): WARN LOUDLY
 	// about every slug residing in >1 status folder of a registered mirror's ledger
 	// (a corrupt ledger — never a silent pass). A human must resolve each.
 	if (dupCount > 0) {

package/src/surface-gate.ts

@@ -6,7 +6,7 @@ import {parseableJsonContractPrompt} from './review-verdict.js';
 import type {NewQuestion} from './sidecar.js';
 
 /**
- * The **SURFACE gate** (prd `advance-loop`, task `advance-rung-surface`,
+ * The **SURFACE gate** (spec `advance-loop`, task `advance-rung-surface`,
  * US #32/33) — the surface-question rung's fresh-context spawn, the DIRECT mirror
  * of the PR/code review gate ({@link import('./review-gate.js')}). On
  * `classify=surface`, the advance engine spawns a FRESH-CONTEXT agent with the
@@ -70,7 +70,7 @@ export interface SurfaceEmit {
 
 /** What the surface gate needs to launch a fresh-context surface of one item. */
 export interface SurfaceGateInput {
-	/** The namespaced identity the surface is for (`task:foo` / `prd:bar` / `observation:baz`). */
+	/** The namespaced identity the surface is for (`task:foo` / `spec:bar` / `observation:baz`). */
 	item: string;
 	/** The working clone/checkout the gate runs in. */
 	cwd: string;
@@ -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

@@ -13,7 +13,7 @@ import {
 } from './sidecar.js';
 
 /**
- * The engine-owned SURFACE PERSIST (prd `advance-loop`, task
+ * The engine-owned SURFACE PERSIST (spec `advance-loop`, task
  * `advance-rung-surface`, US #15/33) — the half of the surface rung the ENGINE
  * owns (the skill JUDGES, the engine PERSISTS). Given the questions the
  * `surface-questions` skill EMITTED (gathered by `surface-gate.ts`'s spawn), the
@@ -53,7 +53,7 @@ import {
 export interface SurfacePersistOptions {
 	/** Working clone/worktree the persist commits in. */
 	cwd: string;
-	/** The namespaced item identity (`task:foo` / `prd:bar` / `observation:baz`). */
+	/** The namespaced item identity (`task:foo` / `spec:bar` / `observation:baz`). */
 	item: string;
 	/**
 	 * The item file path RELATIVE to `cwd` (e.g. `work/backlog/foo.md`). The
@@ -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

@@ -29,9 +29,9 @@ export {parseReviewVerdict as parseTaskReviewVerdict} from './review-verdict.js'
 
 /**
  * **The tasker review→edit→re-review→converge LOOP** (`slicer-review-edit-loop`,
- * GATES prd `work/prds/ready/review.md` RESOLVED DESIGN — Shape 2 / insertion point A).
+ * GATES spec `work/specs/ready/review.md` RESOLVED DESIGN — Shape 2 / insertion point A).
  *
- * On the `do prd:<slug>` tasking path (`tasking.ts`/`performTask`), AFTER the
+ * On the `do spec:<slug>` tasking path (`tasking.ts`/`performTask`), AFTER the
  * agent produces a candidate set of `work/tasks/backlog/<slug>.md` tasks and BEFORE the
  * runner finalises/lands them, this loop RUNS the `review` SKILL
  * (`skills/review/SKILL.md`), APPLIES its findings as EDITS to the candidate task
@@ -47,12 +47,12 @@ export {parseReviewVerdict as parseTaskReviewVerdict} from './review-verdict.js'
  *     N so the loop can never run forever.
  *
  *     ⚠️ ASPIRATION-VS-BUILT (2026-06-10): the "single context" wording above is the
- *     prd's ASPIRATION, NOT what this module does at runtime. The ACTUAL N loop is
+ *     spec's ASPIRATION, NOT what this module does at runtime. The ACTUAL N loop is
  *     RUNNER-DRIVEN and PER-PASS: `runOneExecution` does `for (pass …) { gate(…);
  *     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 prd 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
@@ -101,7 +102,7 @@ export type TaskReviewVerdict = ReviewVerdict;
 
 /** What the review gate needs to launch a fresh-context review+edit pass. */
 export interface TaskReviewGateInput {
-	/** The prd slug whose candidate tasks are under review. */
+	/** The spec slug whose candidate tasks are under review. */
 	slug: string;
 	/** The working clone/checkout the loop runs in (candidate tasks live here). */
 	cwd: string;
@@ -141,7 +142,7 @@ export type LoopOutcome =
 	| 'converged'
 	/** `taskerLoopMax` hit with blockers → specific uncertain task(s) → needsAnswers. */
 	| 'uncertain-tasks'
-	/** `taskerLoopMax` hit / decomposition unclear → route the prd to needs-attention. */
+	/** `taskerLoopMax` hit / decomposition unclear → route the spec to needs-attention. */
 	| 'decomposition-unclear';
 
 /** The result of running the loop — the disposition the caller's sink routes. */
@@ -174,7 +175,7 @@ export interface RunTaskReviewLoopResult {
 }
 
 export interface RunTaskReviewLoopOptions {
-	/** The prd slug whose candidate tasks are being improved. */
+	/** The spec slug whose candidate tasks are being improved. */
 	slug: string;
 	/** The working clone/checkout the loop runs in. */
 	cwd: string;
@@ -226,7 +227,7 @@ export interface RunTaskReviewLoopOptions {
  * to the candidate task files, then re-review — until `verdict === 'approve'` (no
  * NEW blocking issue → converged) or the pass count reaches `taskerLoopMax`. On the cap
  * with a still-`block` verdict, ROUTE per the verdict's channels:
- *   - `decompositionUnclear` set ⇒ `decomposition-unclear` (prd → needs-attention,
+ *   - `decompositionUnclear` set ⇒ `decomposition-unclear` (spec → needs-attention,
  *     no guessed tasks);
  *   - else `uncertainTasks` (or, as a floor, every candidate task) ⇒
  *     `uncertain-tasks` (those tasks emitted `needsAnswers: true` + questions).
@@ -296,7 +297,7 @@ export async function runTaskReviewLoop(
 		note(
 			`Tasker review loop did not converge within taskerLoopMax=${taskerLoopMax} ` +
 				`across ${executions} fresh context(s); the whole decomposition is ` +
-				'unclear — routing the prd to needs-attention (no guessed tasks).',
+				'unclear — routing the spec to needs-attention (no guessed tasks).',
 		);
 		return {
 			outcome: 'decomposition-unclear',
@@ -308,7 +309,7 @@ export async function runTaskReviewLoop(
 			message:
 				`The decomposition of '${options.slug}' is still unclear after ` +
 				`taskerLoopMax=${taskerLoopMax} review pass(es) across ${executions} fresh ` +
-				'context(s); routing the prd to needs-attention with the open ' +
+				'context(s); routing the spec to needs-attention with the open ' +
 				'questions, emitting no guessed tasks.',
 		};
 	}
@@ -617,18 +618,18 @@ export function buildTaskReviewPrompt(input: TaskReviewGateInput): string {
 	const list = input.candidateTasks.map((p) => `  - ${p}`).join('\n');
 	return [
 		`You are a FRESH-CONTEXT reviewer in the TASKER review→edit→converge LOOP`,
-		`(insertion point A). Review the CANDIDATE TASKS just produced for the prd`,
+		`(insertion point A). Review the CANDIDATE TASKS just produced for the spec`,
 		`"${input.slug}":`,
 		list || '  (no candidate tasks found)',
 		``,
 		reviewDisciplinePrompt(),
 		``,
-		`Read the source prd (work/prds/ready/${input.slug}.md) and review the candidate`,
+		`Read the source spec (${workItemRel('specs-ready', `${input.slug}.md`)}) and review the candidate`,
 		`decomposition ADVERSARIALLY. Review the WHOLE SET — graph coherence / gaps /`,
 		`overlap / goal-composition (dependency-graph coherence, set-level gaps,`,
-		`overlapping/duplicated tasks, and "does the set compose into the prd goal")`,
+		`overlapping/duplicated tasks, and "does the set compose into the spec goal")`,
 		`— not just per-task well-formedness. The DESTINATION CHECK ("if every task`,
-		`is built exactly as written, do we end up with the system the prd describes?")`,
+		`is built exactly as written, do we end up with the system the spec describes?")`,
 		`is PART OF this pass and may ITSELF trigger edits — that is why this is a`,
 		`loop, not a one-shot gate.`,
 		``,
@@ -645,7 +646,7 @@ export function buildTaskReviewPrompt(input: TaskReviewGateInput): string {
 		`    can FIX a finding by editing (the natural improver step).`,
 		`  - "uncertainTasks" — specific tasks you cannot make buildable (each gets`,
 		`    \`needsAnswers: true\` with the questions in its body).`,
-		`  - "decompositionUnclear" — the WHOLE decomposition is unsound (the prd is`,
+		`  - "decompositionUnclear" — the WHOLE decomposition is unsound (the spec is`,
 		`    routed to needs-attention; emit no guessed tasks).`,
 		`Do NOT fill "review" / "edit" / "questions" — those are other callers'`,
 		`channels. Flag, do not guess: a flagged question costs one human glance; a`,

package/src/tasking-eligibility.ts

@@ -1,46 +1,46 @@
 /**
  * Pure tasking-eligibility resolution — the auto-task decision layer, one level
- * UP from the build gate (`eligibility.ts`). No I/O: callers pass in the prd's
+ * UP from the build gate (`eligibility.ts`). No I/O: callers pass in the spec's
  * two autonomy axes (`humanOnly`, `needsAnswers`), the repo's `autoTask` policy,
- * the prd's `taskedAfter` slugs, and the set of slugs whose prds are already
- * TASKED (resolved against `work/prds/tasked/` residence, NOT `work/done/`).
+ * the spec's `taskedAfter` slugs, and the set of slugs whose prds are already
+ * TASKED (resolved against `work/specs/tasked/` residence, NOT `work/done/`).
  *
  * This mirrors the build-gate shape deliberately (CONTEXT.md / the `auto-slice`
- * prd): the same `needsAnswers !== true && humanOnly !== true && <repo policy>`
- * predicate, applied to a prd's two axes + the repo's `autoTask` toggle — and a
- * cross-prd ordering check that resolves against tasked-ness rather than done-ness.
+ * spec): the same `needsAnswers !== true && humanOnly !== true && <repo policy>`
+ * predicate, applied to a spec's two axes + the repo's `autoTask` toggle — and a
+ * cross-spec ordering check that resolves against tasked-ness rather than done-ness.
  */
 
 import type {HumanOnlyGate} from './eligibility.js';
 
 export type {HumanOnlyGate};
 
-/** Resolution of a prd's `taskedAfter` against the set of already-tasked prds. */
+/** Resolution of a spec's `taskedAfter` against the set of already-tasked prds. */
 export interface TaskedAfterResult {
-	/** True when every listed prd is already tasked. */
+	/** True when every listed spec is already tasked. */
 	satisfied: boolean;
-	/** Listed prd slugs not yet tasked, in declaration order. */
+	/** Listed spec slugs not yet tasked, in declaration order. */
 	missing: string[];
 }
 
 export interface TaskingEligibilityInput {
-	/** Autonomy axis 1 (DECIDED): a human must drive THIS prd's tasking. */
+	/** Autonomy axis 1 (DECIDED): a human must drive THIS spec's tasking. */
 	humanOnly: HumanOnlyGate;
-	/** Autonomy axis 2 (DISCOVERED): the prd has unresolved questions. */
+	/** Autonomy axis 2 (DISCOVERED): the spec has unresolved questions. */
 	needsAnswers: HumanOnlyGate;
-	/** Cross-prd order: prd slugs that must already be tasked before this one. */
+	/** Cross-spec order: spec slugs that must already be tasked before this one. */
 	taskedAfter: string[];
-	/** Slugs of prds that are already TASKED (residence in `work/prds/tasked/`). */
+	/** Slugs of prds that are already TASKED (residence in `work/specs/tasked/`). */
 	taskedSlugs: Set<string>;
 	/** Per-repo policy: may an agent auto-task *undeclared* prds in this repo? */
 	autoTask: boolean;
 	/**
-	 * The target was named EXPLICITLY by the operator (`do prd:<slug>`), so the
-	 * `autoTask` POLICY is already satisfied — naming the prd IS the authorization,
+	 * The target was named EXPLICITLY by the operator (`do spec:<slug>`), so the
+	 * `autoTask` POLICY is already satisfied — naming the spec IS the authorization,
 	 * exactly as `do <task>` builds a named task regardless of `autoBuild` (the
 	 * `autoBuild` precedent: the pool/scan gates the policy, the explicit claim path
 	 * never re-checks it). When `true`, the policy term drops from the gate and ONLY
-	 * the prd's own readiness axes (`humanOnly`/`needsAnswers`) + `taskedAfter` bind.
+	 * the spec's own readiness axes (`humanOnly`/`needsAnswers`) + `taskedAfter` bind.
 	 * Defaults `false` (the AUTO-PICK pool path, where the `autoTask` policy DOES
 	 * gate). The pool is the single policy-enforcement point; the per-invocation gate
 	 * applies the policy only when NOT explicit.
@@ -49,7 +49,7 @@ export interface TaskingEligibilityInput {
 }
 
 export interface TaskingEligibilityResult {
-	/** Taskable now = gate passes AND every `taskedAfter` prd is already tasked. */
+	/** Taskable now = gate passes AND every `taskedAfter` spec is already tasked. */
 	taskable: boolean;
 	/** Whether the autonomy gate alone passes (agent-taskable on its own axes). */
 	gatePass: boolean;
@@ -61,7 +61,7 @@ export interface TaskingEligibilityResult {
  * `true` AND `humanOnly` is not `true` AND the repo's `autoTask` POLICY is
  * satisfied — where the policy is satisfied either by the repo's `autoTask`
  * toggle being on (the AUTO-PICK pool path) OR by the target being named
- * EXPLICITLY (`explicit: true` — `do prd:<slug>`, where naming IS the
+ * EXPLICITLY (`explicit: true` — `do spec:<slug>`, where naming IS the
  * authorization, mirroring `do <task>` vs `autoBuild`). Both readiness axes
  * block orthogonally and are never agent-taskable regardless of policy; a human
  * is never bound by either. The exact mirror of `resolveGate` (the build gate),
@@ -82,9 +82,9 @@ export function resolveTaskGate(
 }
 
 /**
- * Resolve a prd's `taskedAfter` against the slugs of prds already TASKED (NOT
- * `done/`): satisfied iff every listed prd is present in `taskedSlugs`. An
- * untasked blocker ⇒ not yet taskable (so this prd's emitted tasks can
+ * Resolve a spec's `taskedAfter` against the slugs of prds already TASKED (NOT
+ * `done/`): satisfied iff every listed spec is present in `taskedSlugs`. An
+ * untasked blocker ⇒ not yet taskable (so this spec's emitted tasks can
  * reference the real slugs of those prds' tasks).
  */
 export function resolveTaskedAfter(