dorfl 0.1.0 → 0.1.2

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,14 +801,14 @@ 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,
 				repoResolved: resolvePromptGuidance(config),
 				taskContent: readFileSync(task.path, 'utf8'),
 			});
-			prompt = buildAgentPrompt(task.slug, task.prd, task.taskPrompt, {
+			prompt = buildAgentPrompt(task.slug, task.spec, task.taskPrompt, {
 				cwd: tree.dir,
 				continueContext,
 				promptGuidance: itemGuidance,
@@ -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.

package/src/scan.ts

@@ -53,7 +53,7 @@ export function lifecycleGatesFrom(config: {
 	surfaceBlockers: boolean;
 	/**
 	 * Spec `staging-surface-and-apply-promote-safety` F2 — the gate that widens
-	 * the SURFACE candidate set into STAGING (`tasks/backlog/` + `prds/proposed/`).
+	 * the SURFACE candidate set into STAGING (`tasks/backlog/` + `specs/proposed/`).
 	 * Threaded here so the `scan --json` `lifecycle.surface[]` reflects the
 	 * expanded pool and the CI matrix enumerates staging surface legs. BUILD/claim
 	 * stays pool-only — only this lifecycle path widens.
@@ -78,7 +78,7 @@ export interface ScannedTriageItem {
 }
 /**
  * A surface/apply lifecycle item, with its namespace. SURFACE only ever carries
- * `needsAnswers` task/prd items (an observation with no sidecar goes to `triage`,
+ * `needsAnswers` task/spec items (an observation with no sidecar goes to `triage`,
  * not `surface`). APPLY, however, ALSO carries an ANSWERED OBSERVATION: since the
  * classifier (`buildLifecyclePools`) routes an observation whose sidecar is
  * all-answered to `apply` (CONSUME, always-on), the projection MUST keep it here
@@ -108,7 +108,7 @@ export interface ScannedBlockedItem {
 export interface ScannedLifecycle {
 	/** Untriaged observations → `obs:<slug>` legs (gated by `observationTriage`). */
 	triage: ScannedTriageItem[];
-	/** `needsAnswers` task/prd items with no answered sidecar → surface legs (gated by `surfaceBlockers`). */
+	/** `needsAnswers` task/spec items with no answered sidecar → surface legs (gated by `surfaceBlockers`). */
 	surface: ScannedBlockedItem[];
 	/**
 	 * Items WITH an all-answered sidecar → apply legs (CONSUME, always-on). Carries
@@ -132,7 +132,7 @@ export interface ScannedItem extends ReadyItem {
 }
 
 /**
- * A PRD entry in `scan --json`'s taskable-prd pool — the SAME shape an eligible
+ * A SPEC entry in `scan --json`'s taskable-spec pool — the SAME shape an eligible
  * task carries in `items[]` (a `slug` + an `eligibility.eligible` boolean), so
  * the propose-matrix `jq` filter mirrors the task one: `select(.eligibility.eligible)
  * | "spec:" + .slug`. "Eligible" here means TASKABLE — the per-repo `autoTask`
@@ -159,7 +159,7 @@ export interface RepoReport {
 	items: ScannedItem[];
 	/**
 	 * The TASKABLE-SPEC pool for this repo (the `specs[]` companion of `items[]`):
-	 * every spec in `work/prds/ready/` not already in `work/prds/tasked/`, each tagged with
+	 * every spec in `work/specs/ready/` not already in `work/specs/tasked/`, each tagged with
 	 * `eligibility.eligible` from {@link taskableSpecs} (the SAME `autoslice-gate`
 	 * predicate the mirror-side pool scan uses — NOT a forked predicate). This is
 	 * what makes the propose-mode CI matrix enumerate `spec:<slug>` legs for ready
@@ -183,7 +183,7 @@ export interface RepoReport {
 	 */
 	lifecycle: ScannedLifecycle;
 	/**
-	 * The one-slug-one-folder LINT result (prd `ledger-integrity` story 3): any
+	 * The one-slug-one-folder LINT result (spec `ledger-integrity` story 3): any
 	 * slug present in MORE THAN ONE `work/` status folder in THIS repo's ledger.
 	 * Empty ⇒ a clean ledger. Non-empty ⇒ a corrupt ledger the formatter WARNS
 	 * about loudly and a human must resolve (never auto-fixed). Derived by listing
@@ -191,7 +191,7 @@ export interface RepoReport {
 	 */
 	ledgerDuplicates: DuplicateSlug[];
 	/**
-	 * The PER-ITEM LOCK in-flight view for this repo (prd
+	 * The PER-ITEM LOCK in-flight view for this repo (spec
 	 * `ledger-status-per-item-lock-refs` US #8; task
 	 * `needs-attention-as-stuck-lock-state`): the held lock entries read from the
 	 * repo's `refs/dorfl/lock/*` refs — `active` holds (in-progress) and
@@ -240,7 +240,7 @@ export function readReadyItems(repoPath: string): ReadyItem[] {
  * through the EXACT same eligibility path as in-place (`do-autopick`), not a fork.
  */
 /**
- * Score a prd pool down to its TASKABLE subset, then label every prd with
+ * Score a spec pool down to its TASKABLE subset, then label every spec with
  * `eligibility.eligible` (true ⇔ taskable). REUSES {@link taskableSpecs} —
  * the SAME `autoslice-gate` predicate the mirror-side `scanMirrorPool` + the
  * in-place `do-autopick` pool already run — so what is taskable does not
@@ -281,7 +281,7 @@ export function scoreSpecs(
  *
  * The pool items' `namespace` is the wider {@link SelectedNamespace}. SURFACE by
  * construction only carries `'task'`/`'prd'` (an observation with no sidecar is a
- * `triage` candidate, never `surface`), so it narrows + drops any non-task/prd
+ * `triage` candidate, never `surface`), so it narrows + drops any non-task/spec
  * defensively. APPLY additionally admits `'observation'` (an answered observation
  * sidecar → apply), and it MUST be kept so the matrix `jq` emits its
  * `observation:<slug>` apply leg — narrowing it away here is exactly what stranded
@@ -324,7 +324,7 @@ export function scoreItems(
 	counts: {totalItems: number; totalEligible: number},
 	heldSlugs: Set<string> = new Set(),
 ): ScannedItem[] {
-	// HELD-SLUG SUBTRACTION (prd `ledger-status-per-item-lock-refs` US #15; task
+	// HELD-SLUG SUBTRACTION (spec `ledger-status-per-item-lock-refs` US #15; task
 	// `claim-acquires-unified-lock-no-body-move`): exclude any pool slug whose
 	// per-item lock is currently held — the eligible pool is "in `tasks/ready/` on
 	// `main` AND no lock held".
@@ -435,7 +435,7 @@ export async function scan(
 		// the lock refs from the mirror's origin; non-fatal (empty set on any fault),
 		// so the read-only scan degrades gracefully exactly as its config reads do.
 		const heldSlugs = await heldTaskSlugs(mirror.path, 'origin', options.env);
-		// The PER-ITEM LOCK in-flight view (prd US #8; task
+		// The PER-ITEM LOCK in-flight view (spec US #8; task
 		// `needs-attention-as-stuck-lock-state`): ADDITIONALLY read the full held
 		// lock entries (action × state + reason) from the mirror's lock refs, so the
 		// scan surfaces held (in-progress) + stuck (needs-attention) items. Read from
@@ -448,7 +448,7 @@ export async function scan(
 			'origin',
 			options.env,
 		);
-		// Spec pool — the TASKABLE-PRD companion of the task pool above
+		// Spec pool — the TASKABLE-SPEC companion of the task pool above
 		// (`ci-propose-matrix-must-enumerate-sliceable-prds-not-only-slices`). Resolve
 		// `autoTask` PER REPO from the mirror's COMMITTED `.dorfl.json`
 		// (exactly as the mirror-side pool scan does — NOT forked); a read fault is
@@ -508,7 +508,7 @@ export async function scan(
 				env: options.env,
 			}),
 		);
-		// 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 mirror's committed `main` tree (the SAME `ls-tree`
 		// read the seam uses), so a corrupt ledger is surfaced LOUDLY by the formatter.
 		const ledgerDuplicates = lintRefLedger('main', mirror.path, options.env);
@@ -543,7 +543,7 @@ export function scanRepoPaths(
 	repoPaths: string[],
 	config: Config,
 	/**
-	 * The HELD-SLUG set to SUBTRACT from each repo's pool (`tasks/ready/`) (prd
+	 * The HELD-SLUG set to SUBTRACT from each repo's pool (`tasks/ready/`) (spec
 	 * `ledger-status-per-item-lock-refs` US #15). This is a WORKING-TREE, OFFLINE
 	 * scan (it has no arbiter handle to fetch the lock refs from — that is the
 	 * registry `scan`'s job), so the held set is supplied by the in-place CALLER
@@ -569,7 +569,7 @@ export function scanRepoPaths(
 			global: config,
 			override,
 		}).config;
-		// Spec pool — the TASKABLE-PRD companion of the task pool. Resolve
+		// Spec pool — the TASKABLE-SPEC companion of the task pool. Resolve
 		// `autoTask` PER REPO from the working-tree `.dorfl.json` (the same
 		// way `autoBuild` is resolved); `taskableSpecs` (the SAME `autoslice-gate`
 		// predicate the autopick paths run) decides what is taskable — no forked

package/src/select-order.ts

@@ -28,7 +28,7 @@
  * member of this union and naming it is a usage error.
  *
  *  - `build` — build an eligible task;
- *  - `task` — task a taskable prd;
+ *  - `task` — task a taskable spec;
  *  - `surface` — render a `needsAnswers` blocker into an answerable sidecar;
  *  - `triage` — triage an untriaged observation.
  */

package/src/select-priority.ts

@@ -30,16 +30,16 @@ import {
  * land). Build it standalone; do not assume `run` already calls it.
  *
  * **Up to FIVE pools.** The `scan`/`selectCandidates`/eligibility model is
- * TASK-ONLY (there is no prd candidate). So this helper composes:
+ * TASK-ONLY (there is no spec candidate). So this helper composes:
  *
  *   - the **`build` pool** (eligible TASKS) — the EXISTING {@link selectCandidates}
  *     path (round-robin across repos, capped). This is the EXACT task-selection
  *     primitive `run` uses, so `run` and this helper SHARE it (they share
  *     `selectCandidates`, the task-pool core).
- *   - the **`task` pool** (prd-to-task) — a pool the caller builds from the prd reader
+ *   - the **`task` pool** (spec-to-task) — a pool the caller builds from the spec reader
  *     (`ledgerRead.resolveSpecPool`) filtered by `autoslice-gate`'s pure predicate
  *     ({@link resolveTaskingEligibility}); see {@link taskableSpecs}. The helper
- *     does NOT reinvent prd eligibility.
+ *     does NOT reinvent spec eligibility.
  *
  * `do` is STRICTLY SEQUENTIAL (parallelism is `run`'s job, ADR §3) — this helper
  * only ORDERS + COUNTS the items; the caller runs the existing `do` pipeline per
@@ -82,7 +82,7 @@ export interface SelectedItem {
  */
 export type LifecycleSelectedItem = SelectedItem;
 
-/** A prd candidate for the tasking pool, before the eligibility gate runs. */
+/** A spec candidate for the tasking pool, before the eligibility gate runs. */
 export interface SpecCandidate {
 	repoPath: string;
 	slug: string;
@@ -91,21 +91,21 @@ export interface SpecCandidate {
 	taskedAfter: string[];
 }
 
-/** Inputs to {@link taskableSpecs}: the raw prd pool + the gate context. */
+/** Inputs to {@link taskableSpecs}: the raw spec pool + the gate context. */
 export interface TaskableSpecsInput {
-	/** Every prd enumerated from `work/prds/ready/` (the auto-task candidate source). */
+	/** Every spec enumerated from `work/specs/ready/` (the auto-task candidate source). */
 	candidates: SpecCandidate[];
-	/** Slugs whose prd resides in `work/prds/tasked/` (resolves `taskedAfter`). */
+	/** Slugs whose spec resides in `work/specs/tasked/` (resolves `taskedAfter`). */
 	taskedSlugs: Set<string>;
 	/** The repo's resolved `autoTask` policy (`autoslice-gate`'s per-repo key). */
 	autoTask: boolean;
 }
 
 /**
- * Filter a raw prd pool down to the TASKABLE prds, in declaration order, using
+ * Filter a raw spec pool down to the TASKABLE prds, in declaration order, using
  * `autoslice-gate`'s pure predicate ({@link resolveTaskingEligibility}) — NOT a
- * reinvented eligibility model. A prd is taskable iff `needsAnswers !== true &&
- * humanOnly !== true && autoTask` AND every `taskedAfter` prd is already tasked.
+ * reinvented eligibility model. A spec is taskable iff `needsAnswers !== true &&
+ * humanOnly !== true && autoTask` AND every `taskedAfter` spec is already tasked.
  * Pure: no I/O (the caller reads the pool through `ledgerRead.resolveSpecPool`).
  */
 export function taskableSpecs(input: TaskableSpecsInput): SpecCandidate[] {
@@ -171,7 +171,7 @@ export interface SelectPrioritisedInput {
 	 */
 	lifecycle?: SelectedLifecyclePools;
 	/**
-	 * The HELD-SLUG set to SUBTRACT from the `build` pool (eligible TASKS) — prd
+	 * The HELD-SLUG set to SUBTRACT from the `build` pool (eligible TASKS) — spec
 	 * `ledger-status-per-item-lock-refs` US #15, task
 	 * `claim-acquires-unified-lock-no-body-move`. A task whose per-item lock is
 	 * currently held is dropped from selection, so the eligible pool is "in
@@ -198,7 +198,7 @@ export interface SelectedLifecyclePools {
  * Build the ordered, counted list of items to do across the (up to) FIVE pools,
  * applying the configurable {@link selectionOrder} with `apply` PINNED FIRST and
  * the count bound. The task pool is selected via the EXISTING
- * {@link selectCandidates} (the shared primitive `run` uses); the prd pool is the
+ * {@link selectCandidates} (the shared primitive `run` uses); the spec pool is the
  * pre-filtered {@link taskableSpecs} output; the lifecycle pools (`apply` /
  * `surface` / `triage`) are caller-built (none for `do`).
  *
@@ -235,7 +235,7 @@ export function selectPrioritised(
 
 	// The per-pool item lists, keyed by the orderable pool name. NOTE the
 	// vocabulary bridge: `build` = the eligible-TASK pool (namespace `task`),
-	// `task` = the taskable-prd pool (namespace `prd`) — the action names, not the
+	// `task` = the taskable-spec pool (namespace `prd`) — the action names, not the
 	// item namespaces (task `advance-selection-order-config`).
 	const byPool: Record<SelectionPool, SelectedItem[]> = {
 		build: buildItems,

package/src/sidecar.ts

@@ -2,7 +2,7 @@ import {parseSlugArg, type SlugNamespace} from './slug-namespace.js';
 import {workItemRel} from './work-layout.js';
 
 /**
- * The **question/answer SIDECAR contract** (prd `advance-loop`, task
+ * The **question/answer SIDECAR contract** (spec `advance-loop`, task
  * `advance-sidecar-contract`) — the one genuinely-new piece of the `advance`
  * family. A strict, tooling-OWNED per-item file `work/questions/<type>-<slug>.md`
  * carrying per-entry answered-state, so the tooling fully owns the Q&A artifact
@@ -208,7 +208,7 @@ function typeForNamespace(
 	if (explicit === 'task') {
 		return 'task';
 	}
-	// `parseSlugArg` only knows `task:`/`prd:`; the sidecar adds the
+	// `parseSlugArg` only knows `task:`/`spec:`; the sidecar adds the
 	// `observation:` namespace (`obs:` is the CLI alias the verb resolves; the
 	// sidecar stores the canonical `observation`). A bare slug (no prefix)
 	// defaults to the task namespace, matching the resolver's "bare = task".
@@ -267,7 +267,7 @@ export function sidecarPathFor(identity: string): string {
  * canonical {@link sidecarPathFor} path FIRST, then any legacy-data fallback that
  * may still be on disk before the migration command converts it.
  *
- * MIGRATE step (prd `prd-to-spec-vocabulary-cutover-and-migration-command`): the
+ * MIGRATE step (spec `prd-to-spec-vocabulary-cutover-and-migration-command`): the
  * producer side now emits `spec:<slug>`, so {@link sidecarPathFor} resolves
  * `work/questions/spec-<slug>.md`. But the ON-DISK sidecar is still the legacy
  * `work/questions/prd-<slug>.md` until `dorfl prd-to-spec` renames the DATA. So a

package/src/slug-namespace.ts

@@ -263,7 +263,7 @@ export function resolveSlug(input: ResolveSlugInput): ResolvedSlug {
 	const parsed = parseSlugArg(input.arg);
 
 	if (parsed.explicit === 'observation') {
-		// `do` spans the task/prd namespaces ONLY (build a task OR task a prd).
+		// `do` spans the task/spec namespaces ONLY (build a task OR task a spec).
 		// The `observation` namespace is `advance`'s alone (triage). Reject it here
 		// rather than let a `do obs:<slug>` resolve into a namespace `do` cannot act
 		// on — point the human at the verb that owns it.
@@ -289,7 +289,7 @@ export function resolveSlug(input: ResolveSlugInput): ResolvedSlug {
 }
 
 /**
- * Resolve a slug argument for the `advance` verb (prd `advance-loop`, task
+ * Resolve a slug argument for the `advance` verb (spec `advance-loop`, task
  * `advance-verb-resolver`). `advance` is the SIBLING top-level verb (NOT a `do`
  * subcommand) that reuses this SAME shared `prefix:arg` resolver, EXTENDED with
  * the `observation` namespace `do` does not span:
@@ -362,6 +362,6 @@ export function resolveTaskOnlyArg(arg: string): string {
 		);
 	}
 	// Bare or `task:` → the task slug. (A bare slug on a task-only command is
-	// unambiguously the task; the prd namespace is unreachable here.)
+	// unambiguously the task; the spec namespace is unreachable here.)
 	return parsed.slug;
 }

package/src/spec-complete.ts

@@ -10,7 +10,7 @@ import {
 } from './work-layout.js';
 
 /**
- * The read-only **"is this spec complete?"** core query (prd `issue-intake`, US #8 —
+ * The read-only **"is this spec complete?"** core query (spec `issue-intake`, US #8 —
  * the closure-linkage half). Given a spec slug + a `work/` tree, a spec is COMPLETE
  * iff there is **≥1 task carrying `spec:<slug>`** AND **all such tasks reside in
  * `work/done/`**. Pure `work/`-folder logic — no seam, no git, no `gh`, no mutation.
@@ -32,7 +32,7 @@ import {
  * means the spec is not yet complete.
  */
 
-/** The task lifecycle folders a `prd:<slug>` task can reside in. */
+/** The task lifecycle folders a `spec:<slug>` task can reside in. */
 const TASK_FOLDERS = TASK_LIFECYCLE_FOLDERS;
 
 /** Where a task resides — the folder name under `work/`. */

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
@@ -236,7 +236,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
@@ -620,7 +620,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);
@@ -909,7 +909,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.
  */

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) {