dorfl 0.1.0 → 0.1.2

package/src/needs-attention.ts

@@ -30,7 +30,7 @@ import {
 
 /**
  * The **needs-attention mechanism** (ADR `ledger-status-on-per-item-lock-refs`;
- * prd `ledger-status-per-item-lock-refs`; ADR §12 for the original folder model).
+ * spec `ledger-status-per-item-lock-refs`; ADR §12 for the original folder model).
  * Every "couldn't finish, a human must look" outcome (a failed acceptance gate
  * (red `verify`), a rebase/merge conflict (ADR §10), a task the agent reported
  * too ambiguous to build, a timeout, or a rejected review) resolves to ONE
@@ -81,7 +81,7 @@ export interface RouteToNeedsAttentionOptions {
 	/**
 	 * The work branch to push to the arbiter (the RECOVERABLE half — see the seam
 	 * docstring). DEFAULT `work/<slug>`: the build-bounce branch the wip/move
-	 * commits landed on. A tasking bounce passes its own branch (`work/prds/
+	 * commits landed on. A tasking bounce passes its own branch (`work/specs/
 	 * ready-<slug>`). The supplied branch MUST be the one HEAD is on (the branch the
 	 * wip/move commits landed on) — NEVER a default that differs from HEAD; a
 	 * caller NOT checked out on the work branch (e.g. a temp branch off main) must
@@ -259,7 +259,7 @@ export interface SurfaceToNeedsAttentionResult {
  *      (an unreachable arbiter leaves the local branch standing — recovery
  *      degrades, never crashes the bounce; retried with bounded backoff on an
  *      outage), BRANCH-PARAMETERISED (default `work/<slug>`; an explicit `branch`
- *      overrides — the tasking bounce passes `work/prds/ready-<slug>`; `pushBranch: false`
+ *      overrides — the tasking bounce passes `work/specs/ready-<slug>`; `pushBranch: false`
  *      ⇒ push NOTHING), and EMPTINESS-GUARDED (a branch with no commits beyond
  *      main, or an absent branch, is skipped). The branch MUST be the one HEAD is
  *      on. The work-branch push is NOT a `main` write.
@@ -316,7 +316,7 @@ export async function routeToNeedsAttention(
 	let pushError: string | undefined;
 	if (options.arbiter && options.pushBranch !== false) {
 		// DEFAULT to the task-namespaced build-bounce branch; a non-task caller
-		// (the tasking bounce) passes its own `work/prds/ready-<slug>` via `branch`.
+		// (the tasking bounce) passes its own `work/specs/ready-<slug>` via `branch`.
 		const branch = options.branch ?? workBranchRef('task', slug);
 		if (branchAheadOf(cwd, branch, 'main', env)) {
 			const arbiter = options.arbiter;
@@ -652,7 +652,7 @@ export async function returnToBacklog(
 }
 
 /**
- * **Promote a STAGED task into the agent-eligible pool** (prd
+ * **Promote a STAGED task into the agent-eligible pool** (spec
  * `staging-pool-position-gate-and-trust-model`, task
  * `pre-backlog-staging-folder-and-promote-step-a`, governing ADR
  * `placement-is-runner-deterministic-humanonly-is-agent-judgement`). Moves
@@ -733,7 +733,7 @@ export async function promoteFromPreBacklog(
 	// arbiter's TRUTH. A fetch, not a checkout — the working tree is untouched.
 	await gitSoftAsync(['fetch', '--quiet', arbiter], cwd, env);
 
-	// UNIFIED PER-ITEM LOCK around the CAS window (prd
+	// UNIFIED PER-ITEM LOCK around the CAS window (spec
 	// `staging-surface-and-apply-promote-safety`, task
 	// `f3b-promote-takes-per-item-advancing-lock`): promote and apply BOTH key onto
 	// the item's `refs/dorfl/lock/<entry>` ref with `action: advance` (the
@@ -850,34 +850,34 @@ export async function promoteFromPreBacklog(
 }
 
 /**
- * **Promote a STAGED prd into the auto-task pool** (prd
+ * **Promote a STAGED spec into the auto-task pool** (spec
  * `staging-pool-position-gate-and-trust-model`, task
  * `pre-prd-staging-pool-split-and-untrusted-prd-placement`, governing ADR
- * `placement-is-runner-deterministic-humanonly-is-agent-judgement`). The prd
+ * `placement-is-runner-deterministic-humanonly-is-agent-judgement`). The spec
  * twin of {@link promoteFromPreBacklog}: moves
- * `work/prds/proposed/<slug>.md → work/prds/ready/<slug>.md` as a durable `main` move
+ * `work/specs/proposed/<slug>.md → work/specs/ready/<slug>.md` as a durable `main` move
  * (tree-less CAS via {@link runTreelessLedgerMove}). After this transition
- * the prd is in the auto-task POOL and eligible to be auto-tasked (subject
+ * the spec is in the auto-task POOL and eligible to be auto-tasked (subject
  * to the existing `autoTask`/`humanOnly`/`needsAnswers`/`taskedAfter` gates,
  * which are UNCHANGED — the staging/pool split changes only WHICH folder is
  * the auto-task pool, not the gates).
  *
  * **RUNNER/human-owned.** There is no agent-facing path that performs this:
- * `intake`'s `prd` dispatch lands the prd STAGED in `work/prds/proposed/` (the
+ * `intake`'s `prd` dispatch lands the spec STAGED in `work/specs/proposed/` (the
  * runner's deterministic placement decision), and only a runner/human
  * invocation moves it into the pool. The agent does no git here, as
  * everywhere; this function is not reachable from any agent surface.
  *
  * Storage-agnostic + tree-less, exactly like {@link promoteFromPreBacklog}:
  * cwd index/HEAD/working tree are never touched, an arbiter remote is
- * REQUIRED, and "not in prds/proposed/" / contention-exhausted cases are returned
+ * REQUIRED, and "not in specs/proposed/" / contention-exhausted cases are returned
  * (NEVER thrown) via `{moved: false, reasonNotMoved}` so callers branch
  * cleanly. Idempotent: re-running after the move LANDED is a no-op success.
  */
 export interface PromoteFromPreSpecOptions {
 	/** The working clone the move is originated from (origin source only; never written). */
 	cwd: string;
-	/** The slug of the staged prd to promote into the pool. */
+	/** The slug of the staged spec to promote into the pool. */
 	slug: string;
 	/** The arbiter remote the promotion is CAS-published to. REQUIRED. */
 	arbiter: string;
@@ -888,11 +888,11 @@ export interface PromoteFromPreSpecOptions {
 }
 
 export interface PromoteFromPreSpecResult {
-	/** True iff the staged prd was moved into the pool + committed. */
+	/** True iff the staged spec was moved into the pool + committed. */
 	moved: boolean;
 	/** When `moved`, the committed transition message. */
 	commitMessage?: string;
-	/** When NOT moved, why (no such prds/proposed item, already in prds/ready/, contention). */
+	/** When NOT moved, why (no such specs/proposed item, already in specs/ready/, contention). */
 	reasonNotMoved?: string;
 }
 
@@ -927,14 +927,14 @@ export async function promoteFromPreSpec(
 	await gitSoftAsync(['fetch', '--quiet', arbiter], cwd, env);
 
 	// UNIFIED PER-ITEM LOCK around the CAS window — symmetric with
-	// {@link promoteFromPreBacklog} (prd `staging-surface-and-apply-promote-safety`,
-	// task `f3b-promote-takes-per-item-advancing-lock`, decisive prd q4 answer:
+	// {@link promoteFromPreBacklog} (spec `staging-surface-and-apply-promote-safety`,
+	// task `f3b-promote-takes-per-item-advancing-lock`, decisive spec q4 answer:
 	// specs share the apply×promote mutual-exclusion fix with tasks). The lock
 	// keys on `spec:${slug}` (a distinct ref from a task with the same slug, via
 	// {@link lockEntryFor}'s `<type>-<slug>` encoding), with `action: advance` —
 	// the SAME action an apply for a spec would take — so spec promote and spec
 	// apply on the same item are mutually exclusive by construction. MIGRATE step
-	// (prd `prd-to-spec-vocabulary-cutover-and-migration-command`): the lock
+	// (spec `prd-to-spec-vocabulary-cutover-and-migration-command`): the lock
 	// identity is `spec:${slug}` to match the `spec-<slug>` entry the tasking/apply
 	// path now acquires (`tasking.ts` releases under `spec:${slug}`); a stale
 	// `prd:${slug}` here would key a DIFFERENT ref and break the mutual exclusion.
@@ -1009,7 +1009,7 @@ export async function promoteFromPreSpec(
 					base,
 					sourceRel,
 					destRel,
-					// The body is carried byte-for-byte from prds/proposed into the pool —
+					// The body is carried byte-for-byte from specs/proposed into the pool —
 					// promotion is a placement decision, not a content transform.
 					transformBody: (body) => body,
 					commitMessage,
@@ -1020,14 +1020,14 @@ export async function promoteFromPreSpec(
 		});
 		if (moved) {
 			note(
-				`Promoted prd '${slug}' from prds/proposed to prds/ready (auto-taskable).`,
+				`Promoted spec '${slug}' from specs/proposed to specs/ready (auto-taskable).`,
 			);
 			return {moved: true, commitMessage};
 		}
 
 		const message =
 			`promote for '${slug}': the arbiter's main kept moving (contended) ` +
-			`after ${TREELESS_CONTENTION_ATTEMPTS} attempts — item left in prds/proposed ` +
+			`after ${TREELESS_CONTENTION_ATTEMPTS} attempts — item left in specs/proposed ` +
 			'(no move). Try again shortly.';
 		note(message);
 		return {moved: false, reasonNotMoved: message};
@@ -1062,7 +1062,7 @@ export interface ListPromotableResult {
 
 /**
  * LIST every staged item awaiting a runner/human promotion — the tasks in
- * `work/pre-backlog/` and the prds in `work/prds/proposed/` on `<arbiter>/main` (the
+ * `work/pre-backlog/` and the prds in `work/specs/proposed/` on `<arbiter>/main` (the
  * discovery half of the `promote` verb, so `promote` with no argument answers
  * "what is staged waiting for me?"). It reads the ARBITER's truth (a fetch + a
  * tree read), NOT the local working tree (which may be stale) — the same source

package/src/orphan-sidecar.ts

@@ -8,12 +8,12 @@ import {workFolderPath, workFolderRel} from './work-layout.js';
 /**
  * The **orphan-sidecar reaper** — the WORKING-TREE counterpart of the job-worktree
  * and remote-branch reapers (`gc.ts` / `reap-branches.ts`), folded into `dorfl gc`
- * (prd `agentic-question-resolution-retire-disposition-vocabulary`, US #10).
+ * (spec `agentic-question-resolution-retire-disposition-vocabulary`, US #10).
  *
  * A question sidecar is a tooling-owned file `work/questions/<type>-<slug>.md`
  * keyed on its source item's `(type, slug)` identity (`sidecarPathFor`). The
  * contract is that notes/sidecars leave by DELETION (git history is the archive),
- * so when a human deletes the source observation (or task/prd) out-of-band, its
+ * so when a human deletes the source observation (or task/spec) out-of-band, its
  * sidecar is ORPHANED.
  *
  * WHY THIS IS A SWEEP, NOT AN APPLY STEP. An orphan's source item is GONE, so it

package/src/placement.ts

@@ -1,5 +1,5 @@
 /**
- * **The shared STAGING/POOL placement resolver** (prd
+ * **The shared STAGING/POOL placement resolver** (spec
  * `staging-pool-position-gate-and-trust-model`, task
  * `runner-deterministic-slice-placement-policy-and-precedence`, governing ADR
  * `placement-is-runner-deterministic-humanonly-is-agent-judgement`).
@@ -32,18 +32,18 @@
  * onto the lifecycle's concrete folder name via {@link PlacementSlots}.
  *
  * - `'staging'` — land in the staging area (tasks: `pre-backlog/`; prds:
- *   `prds/proposed/`). Not in the agent pool; a human/runner promotion is needed to make
+ *   `specs/proposed/`). Not in the agent pool; a human/runner promotion is needed to make
  *   the item eligible. Review-without-PR review surface.
  * - `'pool'` — land directly in the agent-eligible pool (tasks: `tasks/ready/`;
- *   prds: `prds/ready/`). The trusted-fast-path landing.
+ *   prds: `specs/ready/`). The trusted-fast-path landing.
  */
 export type PlacementSide = 'staging' | 'pool';
 
 /**
  * The two folder names a lifecycle uses for its staging/pool split. Supplied by
  * the caller so this resolver stays lifecycle-generic (the TASK caller passes
- * `{staging: 'pre-backlog', pool: 'tasks/ready'}`; the PRD-placement caller passes
- * `{staging: 'prds/proposed', pool: 'prds/ready'}`).
+ * `{staging: 'pre-backlog', pool: 'tasks/ready'}`; the SPEC-placement caller passes
+ * `{staging: 'specs/proposed', pool: 'specs/ready'}`).
  */
 export interface PlacementSlots {
 	staging: string;
@@ -100,7 +100,7 @@ const BUILT_IN_FLOOR: PlacementSide = 'staging';
  *   explicit  >  untrusted-origin ⇒ staging  >  configured default  >  built-in
  *
  * Pure: no I/O, no env reads — the caller resolves config + reads the
- * frontmatter and passes both in. Reused by every lifecycle (task + prd
+ * frontmatter and passes both in. Reused by every lifecycle (task + spec
  * placement + future intake variants) so a precedence change touches ONE place.
  */
 export function resolvePlacement(

package/src/prd-to-spec.ts

@@ -276,6 +276,14 @@ export interface ResyncedDoc {
 	dest: string;
 	/** True when the target already had byte-identical content (a no-op copy). */
 	unchanged: boolean;
+	/**
+	 * True when the doc's SOURCE could not be resolved (the package/dev copy is
+	 * missing), so NOTHING was copied to `dest`. A skipped doc is NEVER counted as
+	 * a change (it must not bump `VERSION` — the latent bug this field guards) and
+	 * is surfaced LOUDLY by the caller. Distinct from `unchanged` (which means the
+	 * source WAS resolved and matched the dest byte-for-byte).
+	 */
+	skipped: boolean;
 }
 
 /** What the protocol re-sync did (or would do). */
@@ -293,40 +301,68 @@ export interface ResyncResult {
  * (`skills/setup/protocol/`) copy — NEVER the target repo's own (old) copy. This
  * is how the migrated repo picks up the new `spec` contract before its data is
  * converted. Idempotent: a doc already byte-identical is reported `unchanged`.
+ * A doc whose SOURCE cannot be resolved is reported `skipped` (NOT copied, NEVER
+ * a VERSION-bump) rather than silently bumping VERSION with nothing copied.
  *
- * `dryRun` reports what WOULD be copied without writing.
+ * `dryRun` reports what WOULD be copied without writing. `resolveDoc` overrides
+ * how a doc's source path is resolved (defaults to {@link resolveProtocolDoc});
+ * it exists so a test can force a non-resolvable source (a path that does not
+ * exist) to exercise the skip path.
  */
 export function resyncProtocol(
 	repoPath: string,
-	options: {dryRun?: boolean} = {},
+	options: {
+		dryRun?: boolean;
+		resolveDoc?: (name: string) => string;
+	} = {},
 ): ResyncResult {
 	const protocolDir = join(repoPath, WORK_ROOT, 'protocol');
+	const resolveDoc = options.resolveDoc ?? ((name) => resolveProtocolDoc(name));
 	const docs: ResyncedDoc[] = [];
 	for (const name of PROTOCOL_DOCS) {
 		// Resolve the SOURCE (package/dev), never the target's adopted copy.
-		const source = resolveProtocolDoc(name, undefined);
+		const source = resolveDoc(name);
 		const destAbs = join(protocolDir, name);
 		const destRel = relative(repoPath, destAbs);
-		let unchanged = false;
-		if (existsSync(source) && existsSync(destAbs)) {
-			unchanged =
-				readFileSync(source, 'utf8') === readFileSync(destAbs, 'utf8');
+		const sourceExists = existsSync(source);
+		if (!sourceExists) {
+			// The source doc could not be resolved: copy NOTHING and record the doc as
+			// SKIPPED (never a change). This is the latent-bug fix: a non-resolvable
+			// source must not count as `changed` and bump `VERSION` while copying no
+			// file. `unchanged: false` here is honest (the dest was not made to match a
+			// source), but `skipped: true` keeps it OUT of the VERSION-bump tally.
+			docs.push({name, dest: destRel, unchanged: false, skipped: true});
+			continue;
 		}
-		if (!options.dryRun && existsSync(source)) {
+		// Source resolved: a doc is CHANGED (VERSION-bump-worthy) only when the dest
+		// is absent OR its content differs from the source. An identical dest is a
+		// no-op copy (`unchanged`), so an already-synced re-run stays a true no-op.
+		const unchanged =
+			existsSync(destAbs) &&
+			readFileSync(source, 'utf8') === readFileSync(destAbs, 'utf8');
+		if (!options.dryRun) {
 			mkdirSync(dirname(destAbs), {recursive: true});
 			copyFileSync(source, destAbs);
 		}
-		docs.push({name, dest: destRel, unchanged});
+		docs.push({name, dest: destRel, unchanged, skipped: false});
 	}
 
 	const versionAbs = join(protocolDir, 'VERSION');
 	const versionRel = relative(repoPath, versionAbs);
-	// Bump VERSION only when a doc actually CHANGED (or VERSION is absent). A
-	// re-run on an already-synced repo must stay a true no-op — otherwise the
-	// (always-fresh) `synced-at` timestamp would dirty the tree on every idempotent
-	// re-run.
-	const anyDocChanged = docs.some((d) => !d.unchanged);
-	if (!options.dryRun && (anyDocChanged || !existsSync(versionAbs))) {
+	// Bump VERSION only when a doc was ACTUALLY COPIED with new content, or when
+	// VERSION is absent AND at least one doc was genuinely synced (copied). A
+	// SKIPPED doc (unresolvable source, nothing copied) is NEVER a change —
+	// counting it would bump VERSION without copying a single doc (the latent bug),
+	// and the write-when-absent fallback must ALSO require a real copy so an
+	// all-skipped resync leaves no VERSION behind. A re-run on an already-synced
+	// repo must stay a true no-op — otherwise the (always-fresh) `synced-at`
+	// timestamp would dirty the tree on every idempotent re-run.
+	const anyDocChanged = docs.some((d) => !d.unchanged && !d.skipped);
+	const anyDocSynced = docs.some((d) => !d.skipped);
+	if (
+		!options.dryRun &&
+		(anyDocChanged || (anyDocSynced && !existsSync(versionAbs)))
+	) {
 		mkdirSync(dirname(versionAbs), {recursive: true});
 		const today = new Date().toISOString().slice(0, 10);
 		writeFileSync(

package/src/prompt.ts

@@ -1,13 +1,13 @@
 /**
  * Builds the prompt the runner hands to `agentCmd`: a small CONSTANT wrapper
- * (only the `<slug>` / source-prd path vary) around the claimed task's own
+ * (only the `<slug>` / source-spec path vary) around the claimed task's own
  * `## Prompt` section. This is dual-use — the SAME assembly the autonomous
  * runner feeds `agentCmd` and the human `dorfl prompt [<slug>]` command.
  *
  * The wrapper is NOT hardcoded here: it is read VERBATIM from the work-contract
  * (`skills/setup/protocol/CLAIM-PROTOCOL.md` → "The prompt handed to the work agent"),
  * so the emitted text can never silently diverge from the canonical contract.
- * We only substitute the per-task placeholders (`<slug>`, `<prd>`).
+ * We only substitute the per-task placeholders (`<slug>`, `<spec>`).
  *
  * The wrapper draws the git boundary IN-BAND — the spawned agent does NO git ops
  * on the repo (no commit/push, no moving `work/` files); the RUNNER owns every
@@ -137,7 +137,7 @@ export function resolveProtocolDoc(
 /**
  * Pull the canonical wrapper TEMPLATE out of CLAIM-PROTOCOL.md: the first fenced
  * code block following the "The prompt handed to the work agent" heading. The
- * returned text still contains the `<slug>` / `<prd>` placeholders verbatim — it
+ * returned text still contains the `<slug>` / `<spec>` placeholders verbatim — it
  * is the single source of truth for the wrapper.
  */
 export function extractCanonicalWrapperTemplate(protocol: string): string {
@@ -208,7 +208,7 @@ export function extractCanonicalWrapperTemplate(protocol: string): string {
  *
  * Pure string transform; runs AFTER `extractCanonicalWrapperTemplate` (a pure
  * verbatim extractor stays a pure verbatim extractor) and BEFORE the
- * `<slug>`/`<prd>` substitution.
+ * `<slug>`/`<spec>` substitution.
  */
 export function applyPromptGuidance(
 	template: string,
@@ -227,17 +227,17 @@ export function applyPromptGuidance(
 }
 
 /**
- * The constant wrapper, parameterised only by the task slug, its source prd
+ * The constant wrapper, parameterised only by the task slug, its source spec
  * slug, and (optionally) the resolved {@link PromptGuidance} nudges. Read
  * verbatim from the work-contract and substituted — never a divergent hardcoded
- * copy. `prd` may be `undefined` when the task has no `prd:` field. When
+ * copy. `spec` may be `undefined` when the task has no `spec:` field. When
  * `promptGuidance` is omitted (or every member resolves false) the output is
  * BYTE-IDENTICAL to today's wrapper (the ELSE-branch of every conditional is
  * the historic text).
  */
 export function wrapper(
 	slug: string,
-	prd: string | undefined,
+	spec: string | undefined,
 	options: {
 		protocolPath?: string;
 		cwd?: string;
@@ -252,7 +252,7 @@ export function wrapper(
 	const protocol = readFileSync(protocolPath, 'utf8');
 	const template = extractCanonicalWrapperTemplate(protocol);
 	const resolved = applyPromptGuidance(template, options.promptGuidance);
-	return resolved.replace(/<slug>/g, slug).replace(/<prd>/g, prd ?? '<prd>');
+	return resolved.replace(/<slug>/g, slug).replace(/<spec>/g, spec ?? '<spec>');
 }
 
 /**
@@ -416,7 +416,7 @@ export function buildContinueBlock(slug: string, ctx: ContinueContext): string {
 }
 
 /**
- * Build the full prompt: the canonical wrapper for `slug` (with its source prd
+ * Build the full prompt: the canonical wrapper for `slug` (with its source spec
  * substituted) followed by the task's own `## Prompt` body, appended verbatim.
  *
  * In CONTINUE-mode (a {@link ContinueContext} is supplied), a CONTINUE block is
@@ -427,7 +427,7 @@ export function buildContinueBlock(slug: string, ctx: ContinueContext): string {
  */
 export function buildAgentPrompt(
 	slug: string,
-	prd: string | undefined,
+	spec: string | undefined,
 	taskPrompt: string,
 	options: {
 		protocolPath?: string;
@@ -436,7 +436,7 @@ export function buildAgentPrompt(
 		promptGuidance?: {testFirst?: boolean};
 	} = {},
 ): string {
-	const head = wrapper(slug, prd, options);
+	const head = wrapper(slug, spec, options);
 	if (options.continueContext) {
 		const block = buildContinueBlock(slug, options.continueContext);
 		return `${head}\n\n${block}\n\n${taskPrompt}\n`;
@@ -459,8 +459,8 @@ export interface ResolvedTask {
 	path: string;
 	/** The folder the task was resolved from (in-progress wins over tasks-ready). */
 	folder: TaskFolder;
-	/** The task's source prd slug (frontmatter `prd:`), if any. */
-	prd: string | undefined;
+	/** The task's source SPEC slug (frontmatter `spec:`), if any. */
+	spec: string | undefined;
 	/** The extracted `## Prompt` body. */
 	taskPrompt: string;
 }
@@ -490,7 +490,7 @@ export class PromptError extends Error {}
 /**
  * The CONTINUE-only gate that lets {@link resolveTask} reach a task that has
  * already been done-moved into `work/done/` — story 5 of the `ledger-integrity`
- * prd (defect 3). A continue/re-claim can legitimately land on a branch whose
+ * spec (defect 3). A continue/re-claim can legitimately land on a branch whose
  * task was ALREADY moved to `done/` (the green-but-unpushed STRAND state), and
  * onboard must find it; but a `done/` task is folder-indistinguishable between
  * two states and re-onboarding a genuinely-finished one would RE-RUN it. So
@@ -530,7 +530,7 @@ export interface ContinueResolutionGate {
 
 /**
  * Extra knobs for {@link resolveTask} beyond the continue gate. Today the only
- * member is `allowBacklog` (prd
+ * member is `allowBacklog` (spec
  * `do-allow-backlog-drive-staged-tasks-without-promotion`): the operator's
  * EXPLICIT `do … --allow-backlog`, which widens resolution to also search
  * `tasks-backlog` (staging) at LOWEST priority. Default off (omitted) \u21d2 the
@@ -571,7 +571,7 @@ function isStrandedDoneTip(gate: ContinueResolutionGate): boolean {
 
 /**
  * Resolve a task's file: prefer `work/in-progress/<slug>.md`, fall back to
- * `work/tasks/ready/<slug>.md` (the pool). Returns the parsed prd + extracted
+ * `work/tasks/ready/<slug>.md` (the pool). Returns the parsed spec + extracted
  * `## Prompt` body. Throws {@link PromptError} when neither file exists or it has
  * no prompt body.
  *
@@ -585,11 +585,11 @@ function isStrandedDoneTip(gate: ContinueResolutionGate): boolean {
  * the only addition, and it is gated. With no gate (a fresh claim) the behaviour
  * is byte-identical to the original `['in-progress','tasks-ready']`-only resolution.
  *
- * `--allow-backlog` (prd `do-allow-backlog-drive-staged-tasks-without-promotion`):
+ * `--allow-backlog` (spec `do-allow-backlog-drive-staged-tasks-without-promotion`):
  * when {@link ResolveTaskOptions.allowBacklog} is set, `tasks-backlog` (the staging
  * folder) is appended at the LOWEST priority — after `tasks-ready`, so a slug
  * present in BOTH the pool and staging resolves to the READY copy (the same-slug
- * precedence the prd's decision 5 fixes). Default off ⇒ byte-identical to today
+ * precedence the spec's decision 5 fixes). Default off ⇒ byte-identical to today
  * (no autonomous path sets it; staging stays unreachable to `run`/auto-pick).
  */
 export function resolveTask(
@@ -624,11 +624,10 @@ export function resolveTask(
 			);
 		}
 		const fm = parseFrontmatter(content);
-		// MIGRATE step (prd `prd-to-spec-vocabulary-cutover-and-migration-command`):
-		// read the parent-spec pointer off the new `fm.spec` field (populated beside
-		// `fm.prd` by the expand task). The `ResolvedTask.prd` field name is left
-		// unchanged (a struct-field rename is out of this batch's scope).
-		return {slug, path, folder, prd: fm.spec, taskPrompt};
+		// Read the parent-spec pointer off `fm.spec` (populated from the canonical
+		// `spec:` key) into the `spec`-only `ResolvedTask` (spec
+		// `prd-to-spec-vocabulary-cutover-and-migration-command`).
+		return {slug, path, folder, spec: fm.spec, taskPrompt};
 	}
 	const searched = order.map((f) => `${workFolderRel(f)}/`).join(', ');
 	throw new PromptError(`no task '${slug}' found in ${searched}`);
@@ -662,13 +661,13 @@ export function inferSlugFromBranch(
  */
 /**
  * Resolve the EFFECTIVE `promptGuidance` for an item by walking the precedence
- * chain (highest → lowest): the per-task frontmatter override, the per-prd
- * frontmatter override (only when the task carries a `prd:`), then the
+ * chain (highest → lowest): the per-task frontmatter override, the per-spec
+ * frontmatter override (only when the task carries a `spec:`), then the
  * already-resolved repo policy. Each nudge member resolves independently — a
  * task's `promptGuidance.testFirst` override never bleeds into a sibling
  * member — mirroring the `humanOnly`/`autoBuild` per-item override shape.
  *
- * A task may carry the override even when it has NO `prd:` (a self-contained
+ * A task may carry the override even when it has NO `spec:` (a self-contained
  * chore), by symmetry with `humanOnly` at the item level; `specFrontmatter`
  * is then simply absent and the chain reads task ⇒ repo.
  */
@@ -685,11 +684,11 @@ export function resolveItemPromptGuidance(
 }
 
 /**
- * Locate a prd's file on disk: prefer `work/prds/ready/<slug>.md` (the
- * auto-slice pool), then fall back to `work/prds/tasked/<slug>.md` (tasked,
+ * Locate a spec's file on disk: prefer `work/specs/ready/<slug>.md` (the
+ * auto-slice pool), then fall back to `work/specs/tasked/<slug>.md` (tasked,
  * resting). Returns `undefined` when neither exists — the caller treats that
- * as "no prd-level override available" and the precedence chain falls
- * through to the repo policy (a missing prd is NOT an error at this seam;
+ * as "no spec-level override available" and the precedence chain falls
+ * through to the repo policy (a missing spec is NOT an error at this seam;
  * the per-item override is OPTIONAL by design).
  */
 export function findSpecPath(
@@ -711,7 +710,7 @@ export function findSpecPath(
 /**
  * The convenience seam every caller of {@link buildAgentPrompt} reuses to
  * resolve the per-item override: load the task frontmatter from its file +
- * (when the task carries `prd:`) the prd frontmatter, then walk
+ * (when the task carries `spec:`) the spec frontmatter, then walk
  * {@link resolveItemPromptGuidance}. Pure-ish (reads at most two files);
  * returns the repo policy verbatim when neither item layer overrides anything.
  */
@@ -722,8 +721,7 @@ export function resolvePromptGuidanceForItem(options: {
 }): PromptGuidance {
 	const taskFm = parseFrontmatter(options.taskContent);
 	let specFm: Frontmatter | undefined;
-	// MIGRATE step (prd `prd-to-spec-vocabulary-cutover-and-migration-command`):
-	// read the parent-spec pointer off `fm.spec` (populated beside `fm.prd`).
+	// Read the parent-spec pointer off `fm.spec` (populated from the `spec:` key).
 	if (taskFm.spec !== undefined) {
 		const specPath = findSpecPath(options.cwd, taskFm.spec);
 		if (specPath !== undefined) {
@@ -742,7 +740,7 @@ export function renderPrompt(options: PromptOptions): string {
 		);
 	}
 	const task = resolveTask(options.cwd, slug);
-	// Per-item override layer: a task or prd may pin `promptGuidance.testFirst`
+	// Per-item override layer: a task or spec may pin `promptGuidance.testFirst`
 	// in its frontmatter, superseding the resolved repo policy for THIS item.
 	// We ALWAYS walk the resolver (even when no repo policy was threaded), so a
 	// task can opt IN to the strengthened nudge even on a repo whose default is
@@ -752,7 +750,7 @@ export function renderPrompt(options: PromptOptions): string {
 		repoResolved: {testFirst: options.promptGuidance?.testFirst === true},
 		taskContent: readFileSync(task.path, 'utf8'),
 	});
-	return buildAgentPrompt(task.slug, task.prd, task.taskPrompt, {
+	return buildAgentPrompt(task.slug, task.spec, task.taskPrompt, {
 		protocolPath: options.protocolPath,
 		cwd: options.cwd,
 		promptGuidance: resolvedGuidance,

package/src/readiness.ts

@@ -16,7 +16,7 @@ import {ledgerRead} from './ledger-read.js';
  * the shared {@link resolveBlockedBy} (no reimplemented dep resolution).
  *
  * The two axes are deliberately treated differently (see WORK-CONTRACT and the
- * task prd):
+ * task spec):
  *
  *   - `blockedBy` unmet is a FACTUAL prerequisite (the dep work does not exist
  *     yet) → REFUSE by default. An override flag is the human escape hatch.

package/src/recover-isolated.ts

@@ -11,7 +11,7 @@ import type {ReviewProvider} from './integrator.js';
 
 /**
  * **`complete --isolated <slug>` — FINISH an already-committed, already-done-moved
- * STRANDED isolated worktree** (prd `ledger-integrity` story 6, the
+ * STRANDED isolated worktree** (spec `ledger-integrity` story 6, the
  * `finish-already-committed-branch` task). The LOCATE-EXISTING inverse of
  * `do --isolated` (which CREATES a worktree): it resolves the slug's RETAINED job
  * worktree via the existing arbiter-URL-keyed naming