dorfl 0.1.1 → 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/prompt.ts

@@ -1,6 +1,6 @@
 /**
  * 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.
  *
@@ -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
@@ -459,10 +459,7 @@ export interface ResolvedTask {
 	path: string;
 	/** The folder the task was resolved from (in-progress wins over tasks-ready). */
 	folder: TaskFolder;
-	/**
-	 * The task's source SPEC slug (frontmatter `spec:`, or the legacy `prd:` key
-	 * as read-only back-compat), if any.
-	 */
+	/** The task's source SPEC slug (frontmatter `spec:`), if any. */
 	spec: string | undefined;
 	/** The extracted `## Prompt` body. */
 	taskPrompt: string;
@@ -493,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
@@ -533,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
@@ -574,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.
  *
@@ -588,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(
@@ -627,9 +624,8 @@ export function resolveTask(
 			);
 		}
 		const fm = parseFrontmatter(content);
-		// Read the parent-spec pointer off `fm.spec` (populated from EITHER the
-		// canonical `spec:` key or the legacy `prd:` back-compat alias) into the
-		// `spec`-only `ResolvedTask` (spec
+		// 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};
 	}
@@ -665,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.
  */
@@ -688,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(
@@ -714,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.
  */
@@ -725,8 +721,7 @@ export function resolvePromptGuidanceForItem(options: {
 }): PromptGuidance {
 	const taskFm = parseFrontmatter(options.taskContent);
 	let specFm: Frontmatter | undefined;
-	// Read the parent-spec pointer off `fm.spec` (populated from the `spec:` key or
-	// the legacy `prd:` back-compat alias).
+	// 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) {
@@ -745,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

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

package/src/repo-config.ts

@@ -61,16 +61,16 @@ export const REPO_CONFIG_FILENAME = brand.repoConfigFilename;
  */
 export const REPO_ALLOWED_KEYS = [
 	'integration',
-	// `taskingIntegration` (the per-TRANSITION override for the prd→tasks TASKING
+	// `taskingIntegration` (the per-TRANSITION override for the spec→tasks TASKING
 	// transition ONLY) is a genuine repo property exactly like `integration`: whether
-	// THIS repo tasks a prd straight onto `main` (task FILES land, no PR) while it
+	// THIS repo tasks a spec straight onto `main` (task FILES land, no PR) while it
 	// still BUILDS each task as a reviewable PR is agreed by all collaborators +
 	// travels with the repo. Resolved per-repo through the SAME chain as
 	// `integration`, then falls back to `integration` when unset. DISTINCT from
 	// intake's per-EMITTED-TYPE `{task, prd}` resolver (front door, author-trust):
 	// this is a per-lifecycle-transition knob, inside the boundary, config-resolved.
 	'taskingIntegration',
-	// `tasksLandIn` (the per-repo TASK-PLACEMENT default — staging vs pool, prd
+	// `tasksLandIn` (the per-repo TASK-PLACEMENT default — staging vs pool, spec
 	// `staging-pool-position-gate-and-trust-model` US #5) is a genuine repo property
 	// exactly like `taskingIntegration`/`integration`: whether THIS repo's tasker
 	// output lands STAGED (`pre-backlog/`, review-without-PR human-promote path) or
@@ -91,7 +91,7 @@ export const REPO_ALLOWED_KEYS = [
 	// through the SAME chain as `tasksLandIn` (flag `--specs-land-in` > env
 	// `DORFL_SPECS_LAND_IN` > per-repo > global > built-in). Fed into the shared
 	// placement resolver as the configured-default rung for the spec lifecycle
-	// (`src/placement.ts`). The sole spec-placement key after the prd → spec HARD
+	// (`src/placement.ts`). The sole spec-placement key after the `prd` → `spec` HARD
 	// CUTOVER (the legacy `prdsLandIn` key is GONE — clean break, no accepted alias).
 	'specsLandIn',
 	// `noPR` (the PR-INTENT axis — push the branch but deliberately skip the PR) is
@@ -116,7 +116,7 @@ export const REPO_ALLOWED_KEYS = [
 	'autoBuild',
 	// `autoTask` (may an agent auto-task undeclared prds in this repo?) is a
 	// genuine repo property — the tasking-autonomy mirror of `autoBuild`
-	// (`work/prds/auto-task.md`), resolved per-repo through the same chain.
+	// (`work/specs/auto-task.md`), resolved per-repo through the same chain.
 	'autoTask',
 	// `observationTriage` (the 3-state `off|ask|auto` gate over the observation
 	// INBOX) is a genuine repo property — the observation-side question-surfacing
@@ -125,7 +125,7 @@ export const REPO_ALLOWED_KEYS = [
 	// boolean (no alias; no external users owed a migration window, 2026-06-12).
 	'observationTriage',
 	// `mergeQuestions` (the 3-state `off|ask|auto` gate over the MERGE-QUESTION
-	// SURFACER — prd `land-time-reverify-and-parallel-merge-ceiling` Story 17 /
+	// SURFACER — spec `land-time-reverify-and-parallel-merge-ceiling` Story 17 /
 	// task `merge-questions-gate-axis`) is a genuine repo property exactly like
 	// `observationTriage`: whether THIS repo's unmerged `work/*` branches surface
 	// as merge-questions (and whether they auto-land) is agreed by all
@@ -136,13 +136,13 @@ export const REPO_ALLOWED_KEYS = [
 	// (flag > env > per-repo > global > default `ask`).
 	'mergeQuestions',
 	// `surfaceBlockers` (the BOOLEAN gate over DECLARED blocked work — whether a
-	// task/prd carrying `needsAnswers:true` is rendered into a question sidecar) is a
+	// task/spec carrying `needsAnswers:true` is rendered into a question sidecar) is a
 	// genuine repo property — the blocked-work side of the question-surfacing gate
 	// family (ADR `ci-config-policy-and-gate-family`), the orthogonal peer of
 	// `observationTriage`, resolved per-repo through the same chain as `autoBuild`.
 	'surfaceBlockers',
 	// `surfaceStaging` (the BOOLEAN gate-family member that widens SURFACE into
-	// STAGING — prd `staging-surface-and-apply-promote-safety` F2) is a genuine
+	// STAGING — spec `staging-surface-and-apply-promote-safety` F2) is a genuine
 	// repo property exactly like its siblings (`surfaceBlockers`/`autoBuild`):
 	// whether THIS repo inspects staging for questions is agreed by all
 	// collaborators + travels with the repo. Default `true`; resolved per-repo
@@ -161,8 +161,8 @@ export const REPO_ALLOWED_KEYS = [
 	// (machine paths/commands), so they are rejected below.
 	'model',
 	'harness',
-	// Gate 2 (PR/code review) policy is a genuine repo property (GATES prd
-	// `work/prds/tasked/review.md`), resolved per-repo like `integration`/`autoBuild`:
+	// Gate 2 (PR/code review) policy is a genuine repo property (GATES spec
+	// `work/specs/tasked/review.md`), resolved per-repo like `integration`/`autoBuild`:
 	// whether this repo runs Gate 2 (`review`), which model the review agent runs
 	// on (`reviewModel`), and the revise↔review loop bound (`reviewMaxRounds`).
 	// `reviewModel` is routing intent (not auth), so — like `model` — it is
@@ -185,7 +185,7 @@ export const REPO_ALLOWED_KEYS = [
 	// artifact (and pays the per-gate install cost) is agreed by all collaborators
 	// + travels with the repo. Resolved per-repo through the SAME chain.
 	'freshWorktreeGate',
-	// `mergeRetries` (the cross-job merge serialiser's CAS-retry cap — prd
+	// `mergeRetries` (the cross-job merge serialiser's CAS-retry cap — spec
 	// `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1 (a))
 	// is a genuine repo property exactly like `freshWorktreeGate`: "how many
 	// re-rebase-and-retry attempts before a contender bounces to needs-attention"
@@ -195,7 +195,7 @@ export const REPO_ALLOWED_KEYS = [
 	// CAS still costs only a re-rebase + re-gate retry, never a `--force`.
 	'mergeRetries',
 	// `strictMergeApproval` (the OPT-IN strictness layered on the OQ6
-	// stale-approval default — prd `land-time-reverify-and-parallel-merge-ceiling`
+	// stale-approval default — spec `land-time-reverify-and-parallel-merge-ceiling`
 	// sidecar OQ6 / task `strict-merge-approval-gate`) is a genuine repo property
 	// exactly like `mergeQuestions`/`mergeRetries`: whether THIS repo re-surfaces
 	// the merge-question on a merge-base change (the host-agnostic analogue of

package/src/review-gate.ts

@@ -1,6 +1,7 @@
 import {NullHarness, substituteModel, type Harness} from './harness.js';
 import {launchWithOptionalWatch} from './agent-launch.js';
 import {boundaryLine} from './watch-session.js';
+import {workItemRel} from './work-layout.js';
 import {
 	parseReviewVerdict,
 	ReviewParseError,
@@ -18,7 +19,7 @@ export {
 } from './review-verdict.js';
 
 /**
- * **Gate 2 — the PR/code review gate** (GATES prd `work/prds/tasked/review.md`), the
+ * **Gate 2 — the PR/code review gate** (GATES spec `work/specs/tasked/review.md`), the
  * JUDGEMENT layer that rides ON TOP of the deterministic `verify` floor (ADR §8).
  *
  * After the green `verify` and BEFORE the done-move, `complete`/`do` invoke the
@@ -110,7 +111,7 @@ export function buildReviewPrompt(slug: string): string {
 	return [
 		`You are a FRESH-CONTEXT reviewer (Gate 2 — PR/code review). Review the`,
 		`code changes on this work branch AGAINST the task that specified them`,
-		`(work/in-progress/${slug}.md or work/done/${slug}.md) and its source prd.`,
+		`(work/in-progress/${slug}.md or work/done/${slug}.md) and its source spec.`,
 		``,
 		reviewDisciplinePrompt(),
 		``,
@@ -150,7 +151,7 @@ export function buildReviewPrompt(slug: string): string {
 		`comment on the PR — write it FOR a human landing there, NOT as scratch`,
 		`thinking. LEAD with the verdict ("Approved" or "Blocked") and then give the`,
 		`lenses' reasoning and the destination check ("merged as written, do we reach`,
-		`the task/prd goal?"). Write it deliberately; do NOT narrate your process`,
+		`the task/spec goal?"). Write it deliberately; do NOT narrate your process`,
 		`("Let me check…"). Keep it TIGHT: aim for a few short sentences and DO NOT`,
 		`exceed ~1500 characters — a long, multi-paragraph field is exactly what`,
 		`corrupts the JSON on large diffs; say less, not more. It is plain text inside`,
@@ -247,10 +248,10 @@ export function harnessReviewGate(
  * Render the TASK-SET acceptance-gate PROMPT — the task-path mirror of
  * {@link buildReviewPrompt} (task `slice-acceptance-gate`). Instead of
  * reviewing a code diff against ONE task, this instructs a FRESH-CONTEXT
- * agent to review the WHOLE candidate SET of tasks produced for prd `slug`,
+ * agent to review the WHOLE candidate SET of tasks produced for spec `slug`,
  * using the **review discipline**'s SET-OF-TASKS lens (coherence / dependency
  * graph / gaps + overlap / "if every task is built exactly as written, do we
- * reach the system the prd describes, and is each task
+ * reach the system the spec describes, and is each task
  * correct-if-implemented?"). It emits the SAME unified `ReviewVerdict` shape
  * so {@link parseReviewVerdict} reads it identically.
  *
@@ -265,24 +266,24 @@ export function harnessReviewGate(
 export function buildTaskAcceptancePrompt(slug: string): string {
 	return [
 		`You are a FRESH-CONTEXT reviewer (the task-SET ACCEPTANCE GATE). Review`,
-		`the candidate tasks this tasking run produced for the prd "${slug}" — the`,
+		`the candidate tasks this tasking run produced for the spec "${slug}" — the`,
 		`new/changed candidate task files on this work branch — AGAINST their source`,
-		`prd (work/prds/ready/${slug}.md — the held prd stays in prds/ready/ while it is being`,
+		`spec (${workItemRel('specs-ready', `${slug}.md`)} — the held spec stays in specs/ready/ while it is being`,
 		`tasked).`,
 		``,
 		reviewDisciplinePrompt(),
 		``,
 		`Review the WHOLE SET as a SET, not each task in isolation. The set-level`,
 		`framings the review discipline names:`,
-		`  - COHERENCE — do the tasks speak the prd's (and the system's) language`,
-		`    consistently; no task re-means or forks a concept another task/the prd`,
+		`  - COHERENCE — do the tasks speak the spec's (and the system's) language`,
+		`    consistently; no task re-means or forks a concept another task/the spec`,
 		`    already owns?`,
 		`  - DEPENDENCY GRAPH — is the \`blockedBy\`/ordering graph sound (acyclic, the`,
 		`    keystone first, each task's stated blockers really land its premise)?`,
-		`  - GAPS + OVERLAP — does the set COVER the prd with no missing piece, and`,
+		`  - GAPS + OVERLAP — does the set COVER the spec with no missing piece, and`,
 		`    without two tasks doing the same work or fighting over the same seam?`,
 		`  - CORRECT-IF-IMPLEMENTED — if EVERY task is built EXACTLY as written, do we`,
-		`    reach the system the prd describes, and is each task individually`,
+		`    reach the system the spec describes, and is each task individually`,
 		`    correct-if-implemented (no task that compiles but builds the wrong thing)?`,
 		``,
 		`This is a TERMINAL one-shot accept/reject gate: do NOT edit any task, do NOT`,

package/src/review-verdict.ts

@@ -4,7 +4,7 @@
  * (`work/protocol/REVIEW-PROTOCOL.md`, source-of-truth
  * `skills/setup/protocol/REVIEW-PROTOCOL.md`).
  *
- * This is the keystone of the `runner-invoked-disciplines-into-protocol` prd
+ * This is the keystone of the `runner-invoked-disciplines-into-protocol` spec
  * (task 1, D4): every runner-invoked review prompt builder
  * ({@link buildReviewPrompt}, {@link buildTaskAcceptancePrompt} in
  * `review-gate.ts`; {@link buildLoneTaskReviewPrompt} in `intake.ts`;
@@ -84,7 +84,7 @@ export interface ReviewVerdict {
 	questions?: string[];
 	/** For the tasker improver loop: specific tasks to emit `needsAnswers: true`. */
 	uncertainTasks?: UncertainTask[];
-	/** For the tasker improver loop: route the WHOLE prd to needs-attention. */
+	/** For the tasker improver loop: route the WHOLE spec to needs-attention. */
 	decompositionUnclear?: {questions: string[]};
 }
 

package/src/run.ts

@@ -765,7 +765,7 @@ async function runOneItem(
 		}
 
 		// 3. Build the prompt — the SAME dual-use assembly `dorfl prompt`
-		//    emits: the canonical wrapper (+ source prd) + the task's ## Prompt.
+		//    emits: the canonical wrapper (+ source spec) + the task's ## Prompt.
 		let prompt: string;
 		try {
 			// CONTINUE-aware resolution: only on a continue (the job continued a kept
@@ -801,7 +801,7 @@ async function runOneItem(
 					})
 				: undefined;
 			// Thread the resolved per-repo nudge through the per-item override layer
-			// (a task or prd may pin `promptGuidance.testFirst` in its frontmatter,
+			// (a task or spec may pin `promptGuidance.testFirst` in its frontmatter,
 			// superseding the repo policy for THIS item) before the wrapper is built.
 			const itemGuidance = resolvePromptGuidanceForItem({
 				cwd: tree.dir,
@@ -879,7 +879,7 @@ async function runOneItem(
 		// 5–7 (CONVERGED). The whole gate → review → done-move → commit → rebase →
 		// integrate band — plus the needs-attention routing on any failure — now runs
 		// through the SHARED `performIntegration` core (`integration-core.ts`, the
-		// run/do convergence prd). `run` no longer forks its own gate / done-move /
+		// run/do convergence spec). `run` no longer forks its own gate / done-move /
 		// completion commit / `Integrator`+`integrateWithRebase`: that closed all
 		// three drift instances at once (the fleet now gets the review gate, the PR
 		// title/body, AND the per-repo language-agnostic `verify` gate instead of the
@@ -954,7 +954,7 @@ async function runOneItem(
 				// (`do`/`--isolated`/`--remote`/`complete`) already pass it unconditionally.
 				freshWorktreeGate: config.freshWorktreeGate,
 				// The cross-job merge-serialiser CAS-retry cap (config `mergeRetries`) —
-				// the git-alone FLOOR of the cross-job land queue (prd `land-time-reverify-
+				// the git-alone FLOOR of the cross-job land queue (spec `land-time-reverify-
 				// and-parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)). Threaded
 				// from the per-repo resolved config so a wide-matrix CI's raised cap actually
 				// reaches the merge loop — across separate `run` fleet jobs the CAS loop IS
@@ -1262,7 +1262,7 @@ export function defaultRunWorkspace(): string {
  * One supervised TICK over the registry, as a swappable unit. Today the tick IS
  * `runOnce` (claim+build+integrate a concurrent batch of eligible TASKS). The
  * loop ({@link runLoop}) is deliberately written against this signature — NOT
- * against `runOnce` directly — so the advance-loop prd can later swap the tick
+ * against `runOnce` directly — so the advance-loop spec can later swap the tick
  * (build / task / triage / surface / apply) WITHOUT re-architecting the loop
  * (the forward-pointer: the loop owns concurrency/scheduling, the tick owns one
  * item's work). The loop never reaches inside a tick.