dorfl 0.1.0 → 0.1.2

package/src/do-config.ts

@@ -90,7 +90,7 @@ export function doFlagOverrides(
 		...surfaceBlockersFlagOverrides(flags),
 		// `--merge-questions <off|ask|auto>` rides the SAME flag-override chain
 		// (flag > env > per-repo > global > default `ask`): the 3-state gate over
-		// the merge-question SURFACER (prd `land-time-reverify-and-parallel-
+		// the merge-question SURFACER (spec `land-time-reverify-and-parallel-
 		// merge-ceiling` Story 17 / task `merge-questions-gate-axis`). SEPARATE
 		// axis from `--observation-triage` with a HIGHER default — NEVER rides
 		// `--observation-triage`.
@@ -122,7 +122,7 @@ export function doFlagOverrides(
 		// `--no-pr` (the PR-INTENT axis): suppress the PR even on an authed GitHub
 		// arbiter. Rides the SAME flag > env > per-repo > global > default chain.
 		...noPRFlagOverrides(flags),
-		// `--merge-retries <n>` (the cross-job merge serialiser's CAS-retry cap — prd
+		// `--merge-retries <n>` (the cross-job merge serialiser's CAS-retry cap — spec
 		// `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer
 		// q1 (a)) rides the SAME chain (flag > env > per-repo > global > default).
 		...mergeRetriesFlagOverrides(flags),
@@ -130,7 +130,7 @@ export function doFlagOverrides(
 	if (integration !== undefined) {
 		// An explicit `--merge`/`--propose` flag ALWAYS wins for the transition this
 		// command runs. `do` runs EITHER the build transition (a task) OR the tasking
-		// transition (a `do prd:`) per invocation, and the typed flag is
+		// transition (a `do spec:`) per invocation, and the typed flag is
 		// transition-AGNOSTIC, so it must override BOTH the build mode (`integration`)
 		// AND the tasking mode (`taskingIntegration`). Setting both at the top of the
 		// precedence chain means a `--propose` on a `taskingIntegration:'merge'` repo
@@ -346,7 +346,7 @@ export function observationTriageFlagOverrides(
 /**
  * The surface-blockers CLI flag (`advance`): `--surface-blockers` /
  * `--no-surface-blockers`, the BOOLEAN gate over DECLARED blocked work (whether a
- * `needsAnswers:true` task/prd is rendered into a question sidecar; ADR
+ * `needsAnswers:true` task/spec is rendered into a question sidecar; ADR
  * `ci-config-policy-and-gate-family`). The orthogonal PEER of
  * `--observation-triage`. Resolved through the SAME
  * `flag > env > per-repo > global > default` chain as the other gate flags.
@@ -414,7 +414,7 @@ export function mergeRetriesFlagOverrides(
 
 /**
  * The merge-questions CLI flag (`advance`): `--merge-questions <off|ask|auto>`,
- * the 3-state gate over the MERGE-QUESTION SURFACER (prd
+ * the 3-state gate over the MERGE-QUESTION SURFACER (spec
  * `land-time-reverify-and-parallel-merge-ceiling` Story 17 / task
  * `merge-questions-gate-axis`). MIRRORS `--observation-triage`'s SHAPE but is a
  * SEPARATE axis with a HIGHER default (`ask`, never `off` — a dropped merge-
@@ -459,7 +459,7 @@ export function mergeQuestionsFlagOverrides(
 
 /**
  * **The strict-merge-approval CLI flag** (`--strict-merge-approval` /
- * `--no-strict-merge-approval`) — prd
+ * `--no-strict-merge-approval`) — spec
  * `land-time-reverify-and-parallel-merge-ceiling` sidecar OQ6 / task
  * `strict-merge-approval-gate`. The OPT-IN strictness layered on the OQ6
  * stale-approval default: ON re-surfaces the merge-question on a merge-base

package/src/do-remote-auto.ts

@@ -6,7 +6,7 @@ import {selectPrioritised, type SelectedItem} from './select-priority.js';
 import type {Config} from './config.js';
 
 /**
- * The MIRROR-SIDE auto-pick / `-n` caller for `do --remote` (prd `advance-loop`,
+ * The MIRROR-SIDE auto-pick / `-n` caller for `do --remote` (spec `advance-loop`,
  * task `advance-drivers-and-gates`, US #25) — the THIN caller the mirror-side
  * eligible-pool scan (`mirror-side-eligible-pool-scan`) makes possible, the
  * isolated counterpart of `do-autopick`'s in-place {@link performDoAuto}.
@@ -154,7 +154,7 @@ function remoteArgFor(item: SelectedItem): string {
  * the GIVEN order (no pool/priority — the operator chose them), each through the
  * EXISTING {@link performDoRemote} pipeline, SEQUENTIALLY. No mirror scan is
  * needed (the args are explicit); the per-item pipeline resolves each
- * bare/`task:`/`prd:` arg itself.
+ * bare/`task:`/`spec:` arg itself.
  */
 export async function performDoRemoteArgs(
 	args: string[],

package/src/do.ts

@@ -130,14 +130,14 @@ export type DoOutcome =
 	| 'agent-stopped' // the agent DELIBERATELY stopped (task drifted/ambiguous) OR produced no change → surfaced; gate + Gate-2 SKIPPED
 	| 'refused' // refused (dirty tree, wrong folder, nothing to complete, …)
 	| 'usage-error' // usage / environment problem, or a slug-resolution error
-	| 'tasked' // `do prd:<slug>` — the prd was tasked into work/backlog/ (runner-owned)
-	| 'gate-refused' // `do prd:<slug>` — the tasking gate refused (honest skip)
-	| 'stale'; // `do prd:<slug>` — the held prd was edited under the lock (stale tasking)
+	| 'tasked' // `do spec:<slug>` — the spec was tasked into work/backlog/ (runner-owned)
+	| 'gate-refused' // `do spec:<slug>` — the tasking gate refused (honest skip)
+	| 'stale'; // `do spec:<slug>` — the held spec was edited under the lock (stale tasking)
 
 export interface DoResult {
 	exitCode: 0 | 1 | 2 | 3;
 	outcome: DoOutcome;
-	/** The resolved bare slug acted on (task or prd), when one was resolved. */
+	/** The resolved bare slug acted on (task or spec), when one was resolved. */
 	slug?: string;
 	/** The work branch the run operated on, when one was created/switched-to. */
 	branch?: string;
@@ -171,7 +171,7 @@ export type DoDorfl = (input: {
 };
 
 export interface DoOptions {
-	/** The raw CLI slug argument: bare (= task), `task:<slug>`, or `prd:<slug>`. */
+	/** The raw CLI slug argument: bare (= task), `task:<slug>`, or `spec:<slug>`. */
 	arg: string;
 	/** The working clone/checkout to run in-place in. */
 	cwd: string;
@@ -187,10 +187,10 @@ export interface DoOptions {
 	/**
 	 * Per-repo `autoTask` policy (resolved by `autoslice-gate`: flag > env >
 	 * per-repo > global > default false). It gates the AUTO-PICK / pool path only
-	 * (`do-autopick.ts`'s taskable-prd pool): "may an agent auto-task an
-	 * UNDECLARED prd in this repo?". An EXPLICITLY-named `do prd:<slug>` tasks
+	 * (`do-autopick.ts`'s taskable-spec pool): "may an agent auto-task an
+	 * UNDECLARED spec in this repo?". An EXPLICITLY-named `do spec:<slug>` tasks
 	 * REGARDLESS of this policy (the dispatch passes `explicit: true` to
-	 * `performTask` — naming the prd IS the authorization, exactly as `do <task>`
+	 * `performTask` — naming the spec IS the authorization, exactly as `do <task>`
 	 * builds regardless of `autoBuild`). Ignored by the task-build path.
 	 */
 	autoTask?: boolean;
@@ -205,7 +205,7 @@ export interface DoOptions {
 	promptGuidance?: PromptGuidance;
 	/**
 	 * **The tasker review→edit→converge LOOP seam** (`slicer-review-edit-loop`):
-	 * consumed ONLY by the `do prd:<slug>` tasking path — after the agent produces
+	 * consumed ONLY by the `do spec:<slug>` tasking path — after the agent produces
 	 * candidate tasks, run the `review` SKILL as a review→edit→re-review loop that
 	 * improves them, routing the verdict through the needsAnswers / needs-attention
 	 * sink. Ignored by the task-build path. Omitted ⇒ no loop (candidate tasks land
@@ -234,20 +234,20 @@ export interface DoOptions {
 	explicitMerge?: boolean;
 	/**
 	 * **Per-TRANSITION override for the TASKING transition only** (config
-	 * `taskingIntegration`). Consumed ONLY by the `do prd:<slug>` tasking path: the
+	 * `taskingIntegration`). Consumed ONLY by the `do spec:<slug>` tasking path: the
 	 * value threaded into {@link performTask} is `taskingIntegration ?? integration`,
 	 * so an unset override is byte-for-byte today's behaviour (tasking uses
 	 * `integration`). The task-BUILD path ALWAYS threads `integration` (never this
 	 * key). An explicit `--merge`/`--propose` flag wins over BOTH (the flag-override
 	 * layer sets `integration` AND `taskingIntegration` to the typed mode — see
-	 * `do-config.ts`). DISTINCT from intake's per-EMITTED-TYPE `{task, prd}` resolver.
+	 * `do-config.ts`). DISTINCT from intake's per-EMITTED-TYPE `{task, spec}` resolver.
 	 */
 	taskingIntegration?: IntegrationMode;
 	/**
-	 * **The per-repo TASK-PLACEMENT default** (prd
+	 * **The per-repo TASK-PLACEMENT default** (spec
 	 * `staging-pool-position-gate-and-trust-model` US #5, task
 	 * `runner-deterministic-slice-placement-policy-and-precedence`). Consumed by
-	 * the `do prd:<slug>` tasking path: the value is fed as the
+	 * the `do spec:<slug>` tasking path: the value is fed as the
 	 * CONFIGURED-DEFAULT rung into the runner-deterministic placement resolver
 	 * (`src/placement.ts`). Resolved per-repo through the SAME chain as
 	 * `taskingIntegration` (flag > env > per-repo > global > built-in
@@ -274,7 +274,7 @@ export interface DoOptions {
 	 */
 	ignoreDivergedMain?: boolean;
 	/**
-	 * **`--allow-backlog`** (prd
+	 * **`--allow-backlog`** (spec
 	 * `do-allow-backlog-drive-staged-tasks-without-promotion`): let this `do task:`
 	 * invocation FIND, CLAIM, and COMPLETE a task that lives in `tasks/backlog/`
 	 * (staging) IN PLACE, WITHOUT first promoting it to the pool — so no `advance`
@@ -284,7 +284,7 @@ export interface DoOptions {
 	 * build/gate are identical, and the done-move goes `tasks/backlog/ → tasks/done/`
 	 * directly (the explicit drive IS the promotion). EXPLICIT-INVOCATION-ONLY:
 	 * default off, never set by `run`/auto-pick/`advance` (the leak-fence). The
-	 * task-build path only; the `do prd:` path is unaffected.
+	 * task-build path only; the `do spec:` path is unaffected.
 	 */
 	allowBacklog?: boolean;
 	/** The declared per-repo ENV-PREP step (string | list), run ONCE before the
@@ -300,7 +300,7 @@ export interface DoOptions {
 	 */
 	freshWorktreeGate?: boolean;
 	/**
-	 * **The cross-job merge-serialiser CAS-retry cap** (config `mergeRetries`, prd
+	 * **The cross-job merge-serialiser CAS-retry cap** (config `mergeRetries`, spec
 	 * `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1
 	 * (a)). Threaded VERBATIM into `performComplete` → `performIntegration` so a
 	 * wide-matrix CI's raised cap actually reaches the cross-job land queue (the
@@ -335,7 +335,7 @@ export interface DoOptions {
 	 */
 	providerInstance?: ReviewProvider;
 	/**
-	 * **Gate 2 — the PR/code review gate** (GATES prd `work/prds/tasked/review.md`):
+	 * **Gate 2 — the PR/code review gate** (GATES spec `work/specs/tasked/review.md`):
 	 * threaded VERBATIM into `performComplete` (the gate rides inside the shared
 	 * `do`/`complete` pipeline, so CI inherits it for free). When `review` is on,
 	 * the `review` SKILL runs as a fresh-context agent AFTER the green `verify` and
@@ -349,7 +349,7 @@ export interface DoOptions {
 	reviewGate?: ReviewGate;
 	/**
 	 * **The task-SET ACCEPTANCE GATE seam** (task `slice-acceptance-gate`):
-	 * consumed ONLY by the `do prd:<slug>` tasking path. When `review` resolves on,
+	 * consumed ONLY by the `do spec:<slug>` tasking path. When `review` resolves on,
 	 * a fresh-context review of the produced task SET runs BEFORE the tasks
 	 * integrate (riding `performIntegration`'s review block); `block` routes the set
 	 * to needs-attention, `approve` lets it integrate. It rides the SAME BUILD
@@ -453,7 +453,7 @@ interface DoAgentLaunchOptions {
  * there is no checkout, so the worktree is materialised under `workspacesDir`.
  */
 export interface DoRemoteOptions extends DoAgentLaunchOptions {
-	/** The raw CLI slug argument: bare (= task), `task:<slug>`, or `prd:<slug>`. */
+	/** The raw CLI slug argument: bare (= task), `task:<slug>`, or `spec:<slug>`. */
 	arg: string;
 	/**
 	 * The registered remote spec/URL to run against (`do --remote <r>`). Resolved
@@ -473,12 +473,12 @@ export interface DoRemoteOptions extends DoAgentLaunchOptions {
 	arbiter?: string;
 	/**
 	 * Per-repo `autoTask` policy — gates the AUTO-PICK / pool path only. An
-	 * EXPLICITLY-named `do --remote prd:<slug>` tasks regardless of it (the
+	 * EXPLICITLY-named `do --remote spec:<slug>` tasks regardless of it (the
 	 * dispatch passes `explicit: true`), mirroring `do <task>` vs `autoBuild`.
 	 * Ignored by the task-build path.
 	 */
 	autoTask?: boolean;
-	/** The tasker review→edit→converge loop seam — `do --remote prd:<slug>` path only (see {@link DoOptions.reviewLoop}). */
+	/** The tasker review→edit→converge loop seam — `do --remote spec:<slug>` path only (see {@link DoOptions.reviewLoop}). */
 	reviewLoop?: TaskReviewGate;
 	/** The tasker improver loop's `taskerLoopMax` cap. Loop only. */
 	taskerLoopMax?: number;
@@ -495,22 +495,22 @@ export interface DoRemoteOptions extends DoAgentLaunchOptions {
 	explicitMerge?: boolean;
 	/**
 	 * **Per-TRANSITION override for the TASKING transition only** (config
-	 * `taskingIntegration`) on the `do --remote prd:<slug>` path: threaded into
+	 * `taskingIntegration`) on the `do --remote spec:<slug>` path: threaded into
 	 * {@link performTask} as `taskingIntegration ?? integration`. Unset ⇒ tasking
 	 * uses `integration` (today's behaviour); the task-BUILD path always threads
 	 * `integration`. See {@link DoOptions.taskingIntegration}.
 	 */
 	taskingIntegration?: IntegrationMode;
 	/**
-	 * **The per-repo TASK-PLACEMENT default** (prd
+	 * **The per-repo TASK-PLACEMENT default** (spec
 	 * `staging-pool-position-gate-and-trust-model` US #5) on the `do --remote
-	 * prd:<slug>` path: threaded into {@link performTask} as the
+	 * spec:<slug>` path: threaded into {@link performTask} as the
 	 * configured-default rung. See {@link DoOptions.tasksLandIn}.
 	 */
 	tasksLandIn?: 'pre-backlog' | 'ready';
 	/**
 	 * **The OPERATOR's EXPLICIT task-placement override** on the `do --remote
-	 * prd:` path. See {@link DoOptions.explicitTasksLandIn}.
+	 * spec:` path. See {@link DoOptions.explicitTasksLandIn}.
 	 */
 	explicitTasksLandIn?: 'pre-backlog' | 'ready';
 	/** The declared per-repo ENV-PREP step (string | list), run ONCE before the
@@ -526,7 +526,7 @@ export interface DoRemoteOptions extends DoAgentLaunchOptions {
 	 */
 	freshWorktreeGate?: boolean;
 	/**
-	 * **The cross-job merge-serialiser CAS-retry cap** (config `mergeRetries`, prd
+	 * **The cross-job merge-serialiser CAS-retry cap** (config `mergeRetries`, spec
 	 * `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1
 	 * (a)). Threaded VERBATIM into `performComplete` → `performIntegration` so the
 	 * resolved cap reaches the cross-job land queue (the CAS loop IS the queue
@@ -564,7 +564,7 @@ export interface DoRemoteOptions extends DoAgentLaunchOptions {
 	reviewModel?: string;
 	reviewMaxRounds?: number;
 	reviewGate?: ReviewGate;
-	/** The task-SET ACCEPTANCE GATE seam — `do --remote prd:<slug>` path only (see {@link DoOptions.taskReviewGate}). */
+	/** The task-SET ACCEPTANCE GATE seam — `do --remote spec:<slug>` path only (see {@link DoOptions.taskReviewGate}). */
 	taskReviewGate?: ReviewGate;
 	/**
 	 * **`--allow-backlog`** on the no-checkout `do --remote`/`--isolated` path (see
@@ -586,7 +586,7 @@ export interface DoRemoteOptions extends DoAgentLaunchOptions {
 const DEFAULT_ARBITER = 'origin';
 
 /**
- * Map a `do prd:<slug>` {@link TaskResult} onto the `do` {@link DoResult}
+ * Map a `do spec:<slug>` {@link TaskResult} onto the `do` {@link DoResult}
  * contract: outcomes pass through (tasked / gate-refused / stale / agent-failed /
  * usage-error), the lock-lost outcome splits into `lost` (exit 2) vs `contended`
  * (exit 3) by its exit code, and the tasking-only exit 4 (stale) is reported on
@@ -620,7 +620,7 @@ function taskResultToDoResult(tasked: TaskResult): DoResult {
 			break;
 		case 'needs-attention':
 			// The tasker review→edit loop found the decomposition unclear and routed the
-			// prd to needs-attention (no guessed tasks). Same exit class as a stuck
+			// spec to needs-attention (no guessed tasks). Same exit class as a stuck
 			// build (1).
 			outcome = 'needs-attention';
 			exitCode = 1;
@@ -684,8 +684,8 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 	}
 
 	// 1. Resolve the slug across BOTH namespaces — `do` is the ONE command that
-	//    spans them (ADR §3a): bare → task (after a no-prd-collision check;
-	//    ERROR on collision), `task:`/`prd:` explicit. A collision / resolution
+	//    spans them (ADR §3a): bare → task (after a no-spec-collision check;
+	//    ERROR on collision), `task:`/`spec:` explicit. A collision / resolution
 	//    failure is a loud usage error (exit 1).
 	let resolved;
 	try {
@@ -717,10 +717,10 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 			arbiter,
 			doer: 'agent',
 			autoTask: options.autoTask,
-			// EXPLICIT dispatch: a `do prd:<slug>` target was NAMED (the operator typed
+			// EXPLICIT dispatch: a `do spec:<slug>` target was NAMED (the operator typed
 			// it, or the auto-pick POOL already filtered it on `autoTask` before
 			// dispatching here — the single policy-enforcement point). So the tasking gate
-			// drops the `autoTask` policy term and binds only the prd's own readiness
+			// drops the `autoTask` policy term and binds only the spec's own readiness
 			// (`humanOnly`/`needsAnswers`) + `taskedAfter`, EXACTLY as `do <task>` builds a
 			// named task regardless of `autoBuild` (the pool gates the policy, not the
 			// explicit claim).
@@ -746,14 +746,14 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 			// precedence`). The tasker reads them as the configured-default + the
 			// top rung of the runner-deterministic placement resolver; the
 			// `originTrust: untrusted` force is read inside the tasker from the
-			// prd's stamped frontmatter.
+			// spec's stamped frontmatter.
 			tasksLandIn: options.tasksLandIn,
 			explicitTasksLandIn: options.explicitTasksLandIn,
 			noPR: options.noPR,
 			providerInstance: options.providerInstance,
 			// The tasker review→edit→converge loop (slicer-review-edit-loop): improves the
 			// candidate tasks in place + routes the verdict through the needsAnswers /
-			// needs-attention sink. Threaded only on the `do prd:` path; omitted ⇒ no loop.
+			// needs-attention sink. Threaded only on the `do spec:` path; omitted ⇒ no loop.
 			reviewLoop: options.reviewLoop,
 			taskerLoopMax: options.taskerLoopMax,
 			reviewExecutions: options.reviewExecutions,
@@ -1008,7 +1008,7 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 
 	// 5. Run the agent autonomously in the checkout, ON the work branch — the
 	//    SAME prompt assembly `dorfl prompt` emits (canonical wrapper +
-	//    source prd + the task's ## Prompt). The agent only edits code (it does
+	//    source spec + the task's ## Prompt). The agent only edits code (it does
 	//    no git). This is the one NEW middle step `ar-run.sh` shelled out for
 	//    (`prompt | pi`).
 	//    The post-claim pipeline reads the uniform `IsolatedTree` handle (`tree.dir`)
@@ -1047,14 +1047,14 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 			content: readFileSync(task.path, 'utf8'),
 			env,
 		});
-		// 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.
 		const itemGuidance = resolvePromptGuidanceForItem({
 			cwd: tree.dir,
 			repoResolved: {testFirst: options.promptGuidance?.testFirst === true},
 			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,
@@ -1175,7 +1175,7 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 		verify: options.verify,
 		freshWorktreeGate: options.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-and-
+		// git-alone FLOOR of the cross-job land queue (spec `land-time-reverify-and-
 		// parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)). Threaded so a
 		// wide-matrix CI's raised cap actually reaches the merge loop.
 		mergeRetries: options.mergeRetries,
@@ -1875,7 +1875,7 @@ export async function performDoRemote(
 	try {
 		// 2a. Resolve the slug across BOTH namespaces against the claim clone (it
 		//     carries `work/` from the mirror's main). A collision / resolution
-		//     failure is a loud usage error; a `prd:` arg reaches the not-yet-wired
+		//     failure is a loud usage error; a `spec:` arg reaches the not-yet-wired
 		//     stub — identical behaviour to in-place `do`.
 		let resolved;
 		try {
@@ -1905,9 +1905,9 @@ export async function performDoRemote(
 				arbiter: 'origin',
 				doer: 'agent',
 				autoTask: options.autoTask,
-				// EXPLICIT dispatch (same as the in-place path above): the `prd:<slug>` was
+				// EXPLICIT dispatch (same as the in-place path above): the `spec:<slug>` was
 				// NAMED (typed, or pool-filtered on `autoTask` before reaching here), so the
-				// tasking gate drops the policy term — only the prd's own readiness +
+				// tasking gate drops the policy term — only the spec's own readiness +
 				// `taskedAfter` bind, mirroring the build path vs `autoBuild`.
 				explicit: true,
 				dorfl: options.dorfl,
@@ -1919,22 +1919,22 @@ export async function performDoRemote(
 				// `provider` is the SAME the task-build path threads (arg parity), but the
 				// MODE is the per-TRANSITION TASKING resolution
 				// (`per-transition-integration-mode-slicing-vs-build`):
-				// `taskingIntegration ?? integration`, so the `--remote prd:` output ALSO
+				// `taskingIntegration ?? integration`, so the `--remote spec:` output ALSO
 				// routes through the shared core with the tasking-resolved mode.
 				integration: options.taskingIntegration ?? options.integration,
 				// The per-repo TASK-PLACEMENT default + the operator's explicit
 				// override (task `runner-deterministic-slice-placement-policy-and-
-				// precedence`). Same threading as the in-place `do prd:` path.
+				// precedence`). Same threading as the in-place `do spec:` path.
 				tasksLandIn: options.tasksLandIn,
 				explicitTasksLandIn: options.explicitTasksLandIn,
 				noPR: options.noPR,
 				providerInstance: options.providerInstance,
-				// The tasker review→edit→converge loop on the `do --remote prd:` path too.
+				// The tasker review→edit→converge loop on the `do --remote spec:` path too.
 				reviewLoop: options.reviewLoop,
 				taskerLoopMax: options.taskerLoopMax,
 				reviewExecutions: options.reviewExecutions,
 				taskerLoopModel: options.taskerLoopModel,
-				// The task-SET ACCEPTANCE GATE on the `do --remote prd:` path too.
+				// The task-SET ACCEPTANCE GATE on the `do --remote spec:` path too.
 				review: options.review,
 				reviewGate: options.taskReviewGate,
 				acceptanceReviewModel: options.reviewModel,
@@ -2238,14 +2238,14 @@ async function runRemotePipeline(
 			content: readFileSync(task.path, 'utf8'),
 			env,
 		});
-		// Per-item override layer (mirrors in-place `do`): the task/prd frontmatter
+		// Per-item override layer (mirrors in-place `do`): the task/spec frontmatter
 		// may override the resolved repo `promptGuidance.testFirst` for THIS item.
 		const itemGuidance = resolvePromptGuidanceForItem({
 			cwd,
 			repoResolved: {testFirst: options.promptGuidance?.testFirst === true},
 			taskContent: readFileSync(task.path, 'utf8'),
 		});
-		prompt = buildAgentPrompt(task.slug, task.prd, task.taskPrompt, {
+		prompt = buildAgentPrompt(task.slug, task.spec, task.taskPrompt, {
 			cwd,
 			continueContext,
 			promptGuidance: itemGuidance,
@@ -2568,7 +2568,7 @@ async function primeWorktreeTrackingRef(
  * identity) ride VERBATIM from the threaded `DoOptions` onto the structurally-
  * matching {@link DoRemoteOptions} fields; `cwd` is DROPPED (the worktree replaces
  * it) and `remote` + `workspacesDir` are supplied from this driver's closure (the
- * mirror's arbiter URL + the agents' execution area). A `prd:` arg flows through
+ * mirror's arbiter URL + the agents' execution area). A `spec:` arg flows through
  * unchanged — `performDoRemote` tasks it against the claim clone with NO build
  * worktree (the tasking/surface/triage/apply rungs are tree-less ledger moves, the
  * substrate the task's criterion 4 preserves).

package/src/drop-source.ts

@@ -5,7 +5,7 @@ import {resolveSidecarIdentity, sidecarPathFor} from './sidecar.js';
 import {resolveItemPathByIdentity} from './item-path.js';
 
 /**
- * The DIRECT-DELETE helper (prd
+ * The DIRECT-DELETE helper (spec
  * `agentic-question-resolution-retire-disposition-vocabulary`, US #5/#11; task
  * `direct-delete-question-cli-helper`) — the "I just want to throw this away"
  * path that `git rm`s a source item AND its question sidecar (when present) in
@@ -33,7 +33,7 @@ export interface DropSourceOptions {
 	/** Working clone/worktree the deletion commits in. */
 	cwd: string;
 	/**
-	 * The namespaced item identity to delete (`task:foo` / `prd:bar` /
+	 * The namespaced item identity to delete (`task:foo` / `spec:bar` /
 	 * `observation:baz` / `obs:baz` / a bare `<slug>` = task). Resolved to its
 	 * on-disk path by identity, folder-agnostic.
 	 */

package/src/env-config.ts

@@ -65,7 +65,7 @@ const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
 	// LOUDLY naming the variable + the valid options.
 	observationTriage: {enum: ['off', 'ask', 'auto']},
 	// The merge-question SURFACER gate is a 3-state ENUM coercion (mirrors
-	// `observationTriage`'s shape; SEPARATE axis with a HIGHER default, prd
+	// `observationTriage`'s shape; SEPARATE axis with a HIGHER default, spec
 	// `land-time-reverify-and-parallel-merge-ceiling` Story 17 / task
 	// `merge-questions-gate-axis`), so `DORFL_MERGE_QUESTIONS=off|ask|auto`
 	// works and a typo FAILS LOUDLY naming the variable + the valid options.
@@ -74,8 +74,8 @@ const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
 	// `DORFL_SURFACE_BLOCKERS=true|false` works and a typo FAILS LOUDLY.
 	surfaceBlockers: 'boolean',
 	// `surfaceStaging` (the BOOLEAN gate-family member that widens the SURFACE
-	// candidate set to include STAGING — `tasks/backlog/` + `prds/proposed/` —
-	// not only the agent pool; prd
+	// candidate set to include STAGING — `tasks/backlog/` + `specs/proposed/` —
+	// not only the agent pool; spec
 	// `staging-surface-and-apply-promote-safety` F2) coerces as a BOOLEAN like
 	// `autoBuild`/`surfaceBlockers`, so `DORFL_SURFACE_STAGING=true|false`
 	// works and a typo FAILS LOUDLY. Resolution chain identical to the other
@@ -98,7 +98,7 @@ const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
 	// works and a typo FAILS LOUDLY. Unset ⇒ the tasking transition falls back to
 	// `integration` (the flat value). It NEVER touches the build transition or intake.
 	taskingIntegration: {enum: ['propose', 'merge']},
-	// `tasksLandIn` (the per-repo TASK-PLACEMENT default — prd
+	// `tasksLandIn` (the per-repo TASK-PLACEMENT default — spec
 	// `staging-pool-position-gate-and-trust-model` US #5) coerces as the
 	// `pre-backlog`/`ready` enum, so `DORFL_TASKS_LAND_IN=ready` works and a
 	// typo FAILS LOUDLY. Same
@@ -113,7 +113,7 @@ const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
 	// > global > built-in `pre-proposed`); fed into the shared placement resolver
 	// (`src/placement.ts`) as the configured-default rung for the spec lifecycle.
 	// The legacy `prdsLandIn` key / `DORFL_PRDS_LAND_IN` env are GONE after the
-	// prd → spec hard cutover (clean break).
+	// `prd` → `spec` hard cutover (clean break).
 	specsLandIn: {enum: ['pre-proposed', 'ready']},
 	// `noPR` (the PR-INTENT axis) is a BOOLEAN coercion (like `review`), so
 	// `DORFL_NO_PR=true|false` works and a typo FAILS LOUDLY. The removed
@@ -139,14 +139,14 @@ const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
 	// `freshWorktreeGate` is a BOOLEAN coercion (like `taskerLoop`), so
 	// `DORFL_FRESH_WORKTREE_GATE=true|false` works and a typo FAILS LOUDLY.
 	freshWorktreeGate: 'boolean',
-	// `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))
 	// coerces as a NUMBER (like `reviewMaxRounds`), so `DORFL_MERGE_RETRIES=20`
 	// works and a typo FAILS LOUDLY. A wide-matrix CI raises it; the default
 	// (1000 — the C2 large liveness ceiling) stays in place when unset.
 	mergeRetries: 'number',
 	// `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`) coerces as a BOOLEAN
 	// (like `freshWorktreeGate`), so `DORFL_STRICT_MERGE_APPROVAL=true|false`
 	// works and a typo FAILS LOUDLY. Default OFF; ON re-surfaces the
@@ -163,7 +163,7 @@ const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
 /**
  * The env vars for the nested members of the `promptGuidance` namespace. The
  * key is the env var name (`DORFL_PROMPT_GUIDANCE_<MEMBER>`, the nested
- * naming the prd specifies); the value is the (boolean) coercion. Each member
+ * naming the spec specifies); the value is the (boolean) coercion. Each member
  * present in env contributes `{<member>: bool}` into a single
  * `promptGuidance` partial — mergeConfig replaces the whole namespace per the
  * layered precedence, which is correct because EVERY member is included (env

package/src/format.ts

@@ -202,7 +202,7 @@ export function formatCwdSection(section: CwdSection): string[] {
 		}
 	}
 
-	// The PER-ITEM LOCK in-flight SURFACE for the cwd (prd
+	// The PER-ITEM LOCK in-flight SURFACE for the cwd (spec
 	// `ledger-status-per-item-lock-refs` US #8): held (`active` = in-progress) and
 	// `stuck` (= needs-attention) lock entries + their reasons. This is what keeps a
 	// held/stuck cwd item from vanishing: the held-slug subtraction removes it from
@@ -263,7 +263,7 @@ export function formatReport(report: ScanReport, cwd?: CwdSection): string {
 			lines.push('No participating repos found.');
 			lines.push(
 				'(A repo participates iff its work/ tree has lifecycle content in any ' +
-					'pool: tasks/ready, tasks/backlog, prds/proposed, prds/ready, ' +
+					'pool: tasks/ready, tasks/backlog, specs/proposed, specs/ready, ' +
 					'notes/observations, or questions.)',
 			);
 		} else {
@@ -281,7 +281,7 @@ export function formatReport(report: ScanReport, cwd?: CwdSection): string {
 		const groups = categoriseItems(repo.items);
 		allGroups.push(groups);
 		lines.push(...formatRepo(repo.path, groups));
-		// 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
 		// when any slug in this repo's ledger resides in >1 status folder (a corrupt
 		// ledger — never a silent pass). Clean ledgers add no lines.
 		const warnings = formatDuplicateWarnings(repo.ledgerDuplicates ?? []);