dorfl 0.1.1 → 0.1.2

package/src/close-job-template.ts

@@ -1,12 +1,12 @@
 /**
- * The `install-ci` CLOSE-JOB capability (prd `runner-in-ci`, task
+ * The `install-ci` CLOSE-JOB capability (spec `runner-in-ci`, task
  * `install-ci-close-job-workflow`; capability E: close issues when their work
  * lands). This module GENERATES the one fixed workflow file for the close-job and
  * STRUCTURALLY VALIDATES it, mirroring the snapshot-assertion style of
  * `advance-lifecycle-template.ts` / `advance-ci-template.ts` (the package depends on
  * NO YAML lib, so the checks are presence/shape assertions over the raw text).
  *
- * The discipline (from the prd capability-E row + the Out-of-Scope fence):
+ * The discipline (from the spec capability-E row + the Out-of-Scope fence):
  *
  *   - TRIGGER: a MERGE to `main`. There is no native "PR merged" event, so the
  *     workflow uses `push: {branches: [main]}` (NOT `pull_request: closed`): it
@@ -16,7 +16,7 @@
  *     cannot close. (See the `## Decisions` block in the task.)
  *   - The job INVOKES the close machinery via `dorfl close-merged-issues`,
  *     which CONSUMES the UNCHANGED engine pieces: the resolution
- *     (`resolveClosingIssue`), the "prd complete?" query (`prd-complete-query`,
+ *     (`resolveClosingIssue`), the "spec complete?" query (`prd-complete-query`,
  *     done), and `IssueProvider.closeIssue`. CI owns ONLY the job + trigger; it
  *     re-implements NONE of those (the Out-of-Scope fence).
  *   - CI runs IN-PLACE (the CI container IS the isolation): no
@@ -54,7 +54,7 @@ export const CLOSE_JOB_WORKFLOW_PATH = 'workflows/close-job.yml';
  */
 export function generateCloseJobWorkflow(_config: ResolvedCIConfig): string {
 	return `\
-# dorfl — the ISSUE CLOSE-JOB in CI (capability E, prd runner-in-ci).
+# dorfl — the ISSUE CLOSE-JOB in CI (capability E, spec runner-in-ci).
 # EMITTED by \`dorfl install-ci\`; the human commits it. DO NOT hand-edit a
 # copy — re-run install-ci to upgrade the shell.
 #
@@ -69,9 +69,9 @@ export function generateCloseJobWorkflow(_config: ResolvedCIConfig): string {
 # the landed work closes and closes them. CI owns ONLY this job + the trigger; the
 # command CONSUMES the engine's UNCHANGED pieces and re-implements none of them:
 #   * the RESOLUTION (resolveClosingIssue): a lone task closes its own \`issue:\`;
-#     a fanned task reaches the number via \`task.prd: → prd issue:\`.
-#   * the "prd complete?" QUERY (prd-complete-query, done): a prd's issue closes
-#     ONLY when ALL its \`prd:<slug>\` tasks are in work/done/.
+#     a fanned task reaches the number via \`task.spec: → spec issue:\`.
+#   * the "spec complete?" QUERY (prd-complete-query, done): a spec's issue closes
+#     ONLY when ALL its \`spec:<slug>\` tasks are in work/done/.
 #   * the CLOSE (IssueProvider.closeIssue): the atomic comment+close seam — NO
 #     direct \`gh\` in the engine core; any comment rides this close, never the PR
 #     comment seam.
@@ -117,7 +117,7 @@ jobs:
       - name: close issues whose work has landed on main
         # In-place in this checkout (no --isolated/--remote): the CI container IS
         # the isolation. Resolves the closing issue(s) from the work/ tree, runs
-        # the "prd complete?" query for the prd case, and closes via the provider
+        # the "spec complete?" query for the spec case, and closes via the provider
         # seam — all UNCHANGED engine pieces, consumed not re-built.
         env:
           GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}

package/src/close-job.ts

@@ -1,14 +1,14 @@
 /**
- * The CI CLOSE-JOB driver (prd `runner-in-ci`, capability E; task
+ * The CI CLOSE-JOB driver (spec `runner-in-ci`, capability E; task
  * `install-ci-close-job-workflow`). When work lands on `main`, this resolves which
  * source issue(s) the landed work closes and closes them — but it OWNS none of the
  * machinery it relies on. It is the thin JOB that WIRES three UNCHANGED engine
  * pieces together (the Out-of-Scope fence: do NOT re-build them):
  *
  *   - the RESOLUTION — {@link resolveClosingIssue} (`frontmatter.ts`): an artifact
- *     uses `issue:` XOR `prd:`; a lone task closes its own `issue:` directly, a
- *     fanned task reaches the number via `task.prd: → work/prds/<prd>.md prd
- *     issue:`, and `prd:` WINS on a (hand-edited) conflict;
+ *     uses `issue:` XOR `spec:`; a lone task closes its own `issue:` directly, a
+ *     fanned task reaches the number via `task.spec: → work/specs/<spec>.md spec
+ *     issue:`, and `spec:` WINS on a (hand-edited) conflict;
  *   - the QUERY — {@link isSpecComplete} (`spec-complete.ts`, task
  *     `prd-complete-query`, done): a spec is COMPLETE iff ≥1 `spec:<slug>` task AND
  *     all such tasks are in `work/done/`;
@@ -19,12 +19,12 @@
  *
  * The closure conditions, per artifact kind:
  *
- *   - a **lone task** (`issue:`, no `prd:`) that resides in `work/done/` — its PR
+ *   - a **lone task** (`issue:`, no `spec:`) that resides in `work/done/` — its PR
  *     merged, so its own issue closes (reason `completed`);
- *   - a **prd** (`issue:`) — closes ONLY when {@link isSpecComplete} says ALL its
+ *   - a **spec** (`issue:`) — closes ONLY when {@link isSpecComplete} says ALL its
  *     `spec:<slug>` tasks are in `work/done/` (reason `completed`).
  *
- * A prd whose query is NOT yet complete is left OPEN (the final fanned task's
+ * A spec whose query is NOT yet complete is left OPEN (the final fanned task's
  * merge tick closes it). A lone task still outside `work/done/` is skipped. The
  * close DEGRADES (never throws) on a missing/unauthenticated provider, exactly
  * like intake's bounce close — the run reports the real cause and stays exit-0.
@@ -62,7 +62,7 @@ const SPEC_LIFECYCLE_FOLDERS = SPEC_FOLDERS;
 /** Why the close-job acted (or did not act) on a candidate issue. */
 export type CloseDecision =
 	| 'closed' // the issue was closed via the provider seam
-	| 'not-complete' // a prd whose query says it is not yet complete → left open
+	| 'not-complete' // a spec whose query says it is not yet complete → left open
 	| 'not-landed' // a lone task not yet in work/done/ → left open
 	| 'close-failed'; // closure condition held but the provider close degraded
 
@@ -111,9 +111,9 @@ function listMarkdown(repoPath: string, folder: WorkFolderKey): string[] {
 }
 
 /**
- * Read a prd's `issue:` number by slug, scanning the prd folders. Returns
- * `undefined` when no prd with that slug carries an `issue:` (a prd with no source
- * issue, or a typo'd `prd:` hop — degrades to "no issue to close", never crashes).
+ * Read a spec's `issue:` number by slug, scanning the spec folders. Returns
+ * `undefined` when no spec with that slug carries an `issue:` (a spec with no source
+ * issue, or a typo'd `spec:` hop — degrades to "no issue to close", never crashes).
  */
 function specIssueNumber(
 	repoPath: string,
@@ -137,14 +137,14 @@ function specIssueNumber(
  * Resolve the DEDUPLICATED set of closure candidates from the `work/` tree, each
  * via the UNCHANGED {@link resolveClosingIssue}:
  *
- *   - every prd carrying `issue:` (in `work/prds/ready/` or `work/prds/tasked/`) is a
- *     prd-kind candidate keyed on its own `prd:` query;
- *   - every LONE task (`issue:` and NO `prd:`) is an `issue`-kind candidate.
+ *   - every spec carrying `issue:` (in `work/specs/ready/` or `work/specs/tasked/`) is a
+ *     spec-kind candidate keyed on its own `spec:` query;
+ *   - every LONE task (`issue:` and NO `spec:`) is an `issue`-kind candidate.
  *
- * A fanned task carries `prd:` (NOT its own `issue:`), so it reaches the number
- * through its prd's candidate, never as its own — the issue number lives ONLY on
- * the prd. Deduplicated by issue number: a prd enumerated once even though many
- * tasks point at it. Prd candidates are listed before lone-task candidates, each
+ * A fanned task carries `spec:` (NOT its own `issue:`), so it reaches the number
+ * through its spec's candidate, never as its own — the issue number lives ONLY on
+ * the spec. Deduplicated by issue number: a spec enumerated once even though many
+ * tasks point at it. Spec candidates are listed before lone-task candidates, each
  * group slug-sorted, for a deterministic log.
  */
 function resolveCandidates(repoPath: string): {
@@ -165,9 +165,9 @@ function resolveCandidates(repoPath: string): {
 			);
 			const slug = fm.slug ?? basename(file, '.md');
 			const closing = resolveClosingIssue(fm);
-			// A prd's own closing link is its `issue:` (a prd has no `prd:`); on the
-			// hand-edit conflict `prd:` wins via resolveClosingIssue, so only a true
-			// `issue:`-bearing prd becomes a candidate here.
+			// A spec's own closing link is its `issue:` (a spec has no `spec:`); on the
+			// hand-edit conflict `spec:` wins via resolveClosingIssue, so only a true
+			// `issue:`-bearing spec becomes a candidate here.
 			if (closing?.via === 'issue' && !seen.has(closing.issue)) {
 				seen.add(closing.issue);
 				specCandidates.push({issueNumber: closing.issue, via: 'spec', slug});
@@ -175,7 +175,7 @@ function resolveCandidates(repoPath: string): {
 		}
 	}
 
-	// Lone-task candidates: a task with `issue:` and NO `prd:` closes its OWN
+	// Lone-task candidates: a task with `issue:` and NO `spec:` closes its OWN
 	// issue directly when it lands in work/done/.
 	for (const folder of TASK_FOLDERS) {
 		for (const file of listMarkdown(repoPath, folder)) {
@@ -184,9 +184,9 @@ function resolveCandidates(repoPath: string): {
 			);
 			const slug = fm.slug ?? basename(file, '.md');
 			const closing = resolveClosingIssue(fm);
-			// `resolveClosingIssue` returns `via: 'issue'` ONLY when there is no `prd:`
-			// (prd wins on conflict), so a fanned task never lands here — it reaches
-			// its issue through the prd candidate above.
+			// `resolveClosingIssue` returns `via: 'issue'` ONLY when there is no `spec:`
+			// (spec wins on conflict), so a fanned task never lands here — it reaches
+			// its issue through the spec candidate above.
 			if (closing?.via === 'issue' && !seen.has(closing.issue)) {
 				seen.add(closing.issue);
 				taskCandidates.push({issueNumber: closing.issue, via: 'issue', slug});
@@ -222,7 +222,7 @@ function closeComment(via: 'issue' | 'spec', slug: string): string {
 
 /**
  * Run the close-job over a repo's `work/` tree: resolve the closure candidates,
- * apply the per-kind closure condition (a landed lone task; a prd whose
+ * apply the per-kind closure condition (a landed lone task; a spec whose
  * {@link isSpecComplete} query holds), and close the qualifying issues through the
  * {@link IssueProvider.closeIssue} seam (reason `completed`, an informational
  * comment riding the SAME atomic close). REUSES the unchanged resolution + query +

package/src/complete.ts

@@ -160,7 +160,7 @@ export interface CompleteOptions {
 	 */
 	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 {@link performIntegration} as `mergeRetries` so
 	 * the resolved per-repo value controls how many re-rebase-and-retry attempts
@@ -172,7 +172,7 @@ export interface CompleteOptions {
 	/** Skip the acceptance gate (human-only escape hatch; never used unattended). */
 	skipVerify?: boolean;
 	/**
-	 * **`--allow-backlog`** (prd
+	 * **`--allow-backlog`** (spec
 	 * `do-allow-backlog-drive-staged-tasks-without-promotion`): TREAT a
 	 * `tasks/backlog/`-resident body (staging) as a VALID build source, so a
 	 * staged task driven in place done-moves `tasks/backlog/ → tasks/done/`
@@ -185,7 +185,7 @@ export interface CompleteOptions {
 	 */
 	allowBacklog?: boolean;
 	/**
-	 * **Gate 2 — the PR/code review gate** (GATES prd `work/prds/tasked/review.md`). When
+	 * **Gate 2 — the PR/code review gate** (GATES spec `work/specs/tasked/review.md`). When
 	 * `true`, after the green `verify` and BEFORE the done-move, run the `review`
 	 * SKILL as a FRESH-CONTEXT agent (its own harness launch) and route its verdict:
 	 * `approve` → proceed to done-move/commit/integrate; `block` → route to
@@ -417,7 +417,7 @@ export async function performComplete(
 		return await runComplete(options, note);
 	} catch (err) {
 		// AUTONOMOUS-STRAND SURFACE (task
-		// `autonomous-integration-refusal-surfaces-not-strands-in-progress`, prd
+		// `autonomous-integration-refusal-surfaces-not-strands-in-progress`, spec
 		// `ledger-integrity` story 7). On the AUTONOMOUS path (`surfaceArbiter` set
 		// — the human-vs-autonomous gate the core's other failures use), a SOURCE-
 		// STRAND `CompleteRefusal` (the slug-is-stuck `nothing to complete`) and the
@@ -633,7 +633,7 @@ async function runComplete(
 		);
 	}
 	// The branch HEAD is on when it IS a work branch for this slug (so an explicit
-	// `prd:`-style recovery still completes the branch it is standing on); else
+	// `spec:`-style recovery still completes the branch it is standing on); else
 	// synthesise the task branch.
 	const branch =
 		headParsed && headParsed.slug === slug
@@ -676,7 +676,7 @@ async function runComplete(
 	const inProgress = workItemPath(cwd, 'in-progress', slug);
 	const done = workItemPath(cwd, 'done', slug);
 	const onBacklog = existsSync(backlog);
-	// `--allow-backlog` drive (prd
+	// `--allow-backlog` drive (spec
 	// `do-allow-backlog-drive-staged-tasks-without-promotion`): a staged task driven
 	// in place RESTS in `tasks/backlog/` (claim never moved it). Detect it as a build
 	// source so the done-move goes `tasks/backlog/ → tasks/done/` DIRECTLY (the
@@ -699,7 +699,7 @@ async function runComplete(
 			!onPreBacklog &&
 			!onInProgress &&
 			recordAtRenamedDonePosition(cwd, slug));
-	// STRANDED-DONE AUTO-RECOVER (prd `ledger-integrity` story 6, the autonomous
+	// STRANDED-DONE AUTO-RECOVER (spec `ledger-integrity` story 6, the autonomous
 	// half of `finish-already-committed-branch`). When neither in-progress/ nor
 	// needs-attention/ holds the slug on the BRANCH tree BUT done/ does, the work
 	// branch was already built + done-moved + committed by a prior run that never
@@ -892,7 +892,7 @@ async function runComplete(
 		freshWorktreeGate: options.freshWorktreeGate,
 		// The cross-job merge-serialiser CAS-retry cap (config `mergeRetries`) — the
 		// git-alone FLOOR of the cross-job land-queue, resolved through the gate-family
-		// precedence chain (prd `land-time-reverify-and-parallel-merge-ceiling` Story
+		// precedence chain (spec `land-time-reverify-and-parallel-merge-ceiling` Story
 		// 5). Threaded so a wide-matrix CI's raised cap actually reaches the merge loop.
 		mergeRetries: options.mergeRetries,
 		skipVerify: options.skipVerify,
@@ -983,7 +983,7 @@ async function runComplete(
 		// because the work is already integrated and the branch may or may not
 		// still exist locally.
 		//
-		// CROSS-SUBSTRATE RELEASE (prd `ledger-status-per-item-lock-refs` US #9/#10;
+		// CROSS-SUBSTRATE RELEASE (spec `ledger-status-per-item-lock-refs` US #9/#10;
 		// task `complete-lock-then-durable-main-move-crash-safe`): the durable
 		// `main` record is already terminal (the kept tip is provably on
 		// `<arbiter>/main`), so the per-item lock claim took is now stale: release it
@@ -1021,7 +1021,7 @@ async function runComplete(
 	const commitMessage = core.commitMessage;
 	const mode = result.mode;
 
-	// CROSS-SUBSTRATE RELEASE, gated on the work being DURABLY ON `main` (prd
+	// CROSS-SUBSTRATE RELEASE, gated on the work being DURABLY ON `main` (spec
 	// `ledger-status-per-item-lock-refs` US #9/#10; ADR
 	// `ledger-status-on-per-item-lock-refs`; the trail's Amendment 6; task
 	// `complete-lock-then-durable-main-move-crash-safe`). ORDER MATTERS: the
@@ -1158,7 +1158,7 @@ async function runComplete(
 /**
  * Release the per-item lock `claim` ALSO acquired (`action: implement`, keyed
  * `task:<slug>`) AFTER the durable `main` move has landed — the SECOND, lock-
- * release half of complete's cross-substrate ordering (prd
+ * release half of complete's cross-substrate ordering (spec
  * `ledger-status-per-item-lock-refs` US #9/#10; task
  * `complete-lock-then-durable-main-move-crash-safe`).
  *

package/src/concurrency.ts

@@ -49,7 +49,7 @@ export interface RunConcurrentOptions<I, T> {
 /**
  * A per-key async serialiser: `withKeyedLock(key, fn)` runs `fn` to completion
  * before the next caller for the SAME key starts; different keys never block each
- * other. Used to serialise the prd, shared-working-tree CLAIM step PER REPO
+ * other. Used to serialise the spec, shared-working-tree CLAIM step PER REPO
  * inside the otherwise-concurrent tick.
  *
  * Two concurrent claims in ONE repo would prepare their claim micro-commit in the

package/src/config.ts

@@ -17,7 +17,7 @@ import {
 export type IntegrationMode = 'propose' | 'merge';
 
 /**
- * **Per-repo TASK-PLACEMENT default** (prd
+ * **Per-repo TASK-PLACEMENT default** (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`). Which
@@ -38,24 +38,24 @@ export type IntegrationMode = 'propose' | 'merge';
 export type TasksLandIn = 'pre-backlog' | 'ready';
 
 /**
- * **Per-repo PRD-PLACEMENT default** (prd
+ * **Per-repo SPEC-PLACEMENT default** (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`). Which
- * folder the runner lands `intake`-authored prd files in BY DEFAULT —
+ * folder the runner lands `intake`-authored spec files in BY DEFAULT —
  * `'pre-proposed'` (staging — durable + readable but NOT in the auto-tasking
- * POOL; a runner/human promotion is needed to make the prd auto-taskable; the
- * on-disk folder for this value is `work/prds/proposed/`) or `'ready'` (the
+ * POOL; a runner/human promotion is needed to make the spec auto-taskable; the
+ * on-disk folder for this value is `work/specs/proposed/`) or `'ready'` (the
  * auto-tasking POOL — the trusted fast-path landing, on-disk
- * `work/prds/ready/`). The same runner-deterministic placement RESOLVER
+ * `work/specs/ready/`). The same runner-deterministic placement RESOLVER
  * (`src/placement.ts`) layers on top:
  * `explicit operator flag > untrusted-origin ⇒ pre-proposed > specsLandIn
  * default > built-in (pre-proposed)`. An untrusted-origin intake spec is FORCED
  * to staging even in a `'ready'` repo (the positional analogue of the existing
- * `untrusted-origin-forces-build-propose` rule). The PRD twin of
+ * `untrusted-origin-forces-build-propose` rule). The SPEC twin of
  * {@link TasksLandIn}; the SAME shape, the SAME precedence chain. The value
- * spellings mirror the live prd folders (`prds/proposed/` staging,
- * `prds/ready/` pool), exactly as {@link TasksLandIn} mirrors the task folders.
+ * spellings mirror the live spec folders (`specs/proposed/` staging,
+ * `specs/ready/` pool), exactly as {@link TasksLandIn} mirrors the task folders.
  */
 export type SpecsLandIn = 'pre-proposed' | 'ready';
 
@@ -79,7 +79,7 @@ export type ObservationTriage = 'off' | 'ask' | 'auto';
 
 /**
  * **The `mergeQuestions` gate axis** — the 3-state member of the question-
- * surfacing gate family that governs the MERGE-QUESTION surfacer (prd
+ * surfacing gate family that governs the MERGE-QUESTION surfacer (spec
  * `land-time-reverify-and-parallel-merge-ceiling` Story 17 / task
  * `merge-questions-gate-axis`). MIRRORS `observationTriage`'s shape
  * (`off | ask | auto`) but is a SEPARATE axis — "should this built work merge?"
@@ -99,7 +99,7 @@ export type ObservationTriage = 'off' | 'ask' | 'auto';
  *     invoke the agentic decider — a merge-land is never an agent decision.
  * Resolved through the SAME precedence chain as the other gates (flag > env >
  * per-repo > global > default `ask`). The exact name + default + shape were
- * answered in this task's Applied answers 2026-06-26 (q1/q2/q3) + PRD sidecar
+ * answered in this task's Applied answers 2026-06-26 (q1/q2/q3) + SPEC sidecar
  * Q3.
  */
 export type MergeQuestions = 'off' | 'ask' | 'auto';
@@ -201,10 +201,10 @@ export interface Config {
 	/**
 	 * Per-repo policy: may an agent auto-task *undeclared* (not `humanOnly`,
 	 * no open questions) prds in this repo? `false` (default, strict, human-first)
-	 * ⇒ a human must drive every prd's tasking; `true` ⇒ an agent may auto-task
-	 * any prd that is not `humanOnly: true` and has no `needsAnswers`. Resolved like
+	 * ⇒ a human must drive every spec's tasking; `true` ⇒ an agent may auto-task
+	 * any spec that is not `humanOnly: true` and has no `needsAnswers`. Resolved like
 	 * `autoBuild`: flag > `DORFL_AUTO_TASK` env > per-repo > global >
-	 * default. The two-axis tasking gate (`work/prds/auto-task.md`), one level up
+	 * default. The two-axis tasking gate (`work/specs/auto-task.md`), one level up
 	 * from the build gate's `autoBuild`.
 	 */
 	autoTask: boolean;
@@ -227,7 +227,7 @@ export interface Config {
 	observationTriage: ObservationTriage;
 	/**
 	 * Per-repo policy governing the MERGE-QUESTION SURFACER — the 3-state member
-	 * of the question-surfacing gate family (prd
+	 * of the question-surfacing gate family (spec
 	 * `land-time-reverify-and-parallel-merge-ceiling` Story 17 / task
 	 * `merge-questions-gate-axis`). MIRRORS `observationTriage`'s SHAPE
 	 * (`off | ask | auto`) but is a SEPARATE axis with a DIFFERENT default —
@@ -251,7 +251,7 @@ export interface Config {
 	 * Per-repo policy governing DECLARED blocked work — the BOOLEAN member of the
 	 * question-surfacing gate family (its orthogonal PEER is `observationTriage`,
 	 * which governs the raw observation INBOX; ADR `ci-config-policy-and-gate-family`
-	 * §2). It gates whether a task/prd carrying `needsAnswers: true` is rendered
+	 * §2). It gates whether a task/spec carrying `needsAnswers: true` is rendered
 	 * into an answerable question sidecar (`on`) or left silently blocked in the
 	 * backlog (`off`). `false` (default, calm) ⇒ the `needsAnswers`-blocked pool is
 	 * dropped from the auto-pick SELECTION, so a bare `advance` does NOT proactively
@@ -271,11 +271,11 @@ export interface Config {
 	/**
 	 * Per-repo policy governing whether SURFACING (the question-minting polarity)
 	 * inspects STAGING in addition to the agent pool — the BOOLEAN gate-family
-	 * member added by prd `staging-surface-and-apply-promote-safety` (F2). The
+	 * member added by spec `staging-surface-and-apply-promote-safety` (F2). The
 	 * BUILD polarity is UNCHANGED in either mode: staging items stay non-claimable,
 	 * the trust model is untouched. `true` (default) ⇒ the SURFACE candidate set
-	 * draws from STAGING (`tasks/backlog/`, `prds/proposed/`) PLUS the pool, so
-	 * a `needsAnswers` task/prd in staging surfaces its questions BEFORE a human
+	 * draws from STAGING (`tasks/backlog/`, `specs/proposed/`) PLUS the pool, so
+	 * a `needsAnswers` task/spec in staging surfaces its questions BEFORE a human
 	 * promotes it (you promote an already-clarified item, not blind and then get
 	 * asked after); `false` ⇒ the legacy POOL-ONLY behaviour (staging is not
 	 * inspected for questions). Resolved like `surfaceBlockers`/`autoBuild`:
@@ -340,14 +340,14 @@ export interface Config {
 	/** Integration mode for completed items: `propose` (default) or `merge`. */
 	integration: IntegrationMode;
 	/**
-	 * **Per-TRANSITION override for the prd→tasks (TASKING) transition only.** When
-	 * set, the tasking transition (a `do prd:<slug>` run: emit `work/tasks/backlog/*.md` +
-	 * the `work/prds/ready/ → work/prds/tasked/` lifecycle move) integrates with THIS
+	 * **Per-TRANSITION override for the spec→tasks (TASKING) transition only.** When
+	 * set, the tasking transition (a `do spec:<slug>` run: emit `work/tasks/backlog/*.md` +
+	 * the `work/specs/ready/ → work/specs/tasked/` lifecycle move) integrates with THIS
 	 * mode instead of the flat {@link integration}; the task-BUILD transition is
 	 * unaffected (it always reads {@link integration}). UNSET (the default) ⇒ tasking
 	 * falls back to {@link integration} — byte-for-byte today's behaviour for any repo
 	 * that does not set it. The maintainer's target is `integration: 'propose'` +
-	 * `taskingIntegration: 'merge'`: task a prd straight onto `main` (the task FILES
+	 * `taskingIntegration: 'merge'`: task a spec straight onto `main` (the task FILES
 	 * land, no PR) but build each task as a reviewable PR. Resolved per-repo like
 	 * {@link integration}: flag (`--merge`/`--propose`) > env
 	 * (`DORFL_TASKING_INTEGRATION`) > per-repo > global > (fall back to)
@@ -357,7 +357,7 @@ export interface Config {
 	 */
 	taskingIntegration?: IntegrationMode;
 	/**
-	 * **Per-repo DEFAULT landing for the TASKER's emitted tasks** (prd
+	 * **Per-repo DEFAULT landing for the TASKER's emitted tasks** (spec
 	 * `staging-pool-position-gate-and-trust-model` US #5, task
 	 * `runner-deterministic-slice-placement-policy-and-precedence`). Resolved
 	 * per-repo EXACTLY like {@link taskingIntegration} (flag `--tasks-land-in`
@@ -366,7 +366,7 @@ export interface Config {
 	 * CONFIGURED-DEFAULT rung into the shared placement resolver
 	 * (`src/placement.ts`); the resolver overlays an EXPLICIT operator flag
 	 * (top) and the UNTRUSTED-ORIGIN force (staging) on top, in that order. The
-	 * tasker NEVER sets placement itself. Prd US #6 / the governing ADR: the
+	 * tasker NEVER sets placement itself. Spec US #6 / the governing ADR: the
 	 * runner OWNS placement from unforgeable inputs; the agent cannot
 	 * influence it.
 	 */
@@ -385,7 +385,7 @@ export interface Config {
 	 * influence it. KEY-LEVEL SYMMETRY with `tasksLandIn` — one resolver, two
 	 * lifecycles, one precedence change touches ONE place.
 	 *
-	 * The sole spec-placement key after the prd → spec HARD CUTOVER (spec
+	 * The sole spec-placement key after the `prd` → `spec` HARD CUTOVER (spec
 	 * `prd-to-spec-vocabulary-cutover-and-migration-command`): the legacy
 	 * `prdsLandIn` config key + `--prds-land-in` flag are GONE (clean break).
 	 */
@@ -483,7 +483,7 @@ export interface Config {
 	 */
 	verify?: VerifyConfig;
 	/**
-	 * **Gate 2 — the PR/code review gate** (GATES prd `work/prds/tasked/review.md`): run the
+	 * **Gate 2 — the PR/code review gate** (GATES spec `work/specs/tasked/review.md`): run the
 	 * `review` SKILL as a fresh-context judgement gate ON TOP of the deterministic
 	 * `verify` floor, AFTER `verify` passes and BEFORE the done-move, on the
 	 * `do`/`complete` path. Default **OFF** (it puts a model on the merge path —
@@ -519,7 +519,7 @@ export interface Config {
 	reviewMaxRounds: number;
 	/**
 	 * **The tasker IMPROVER loop on/off toggle** (`--tasker-loop` /
-	 * `--no-tasker-loop`). On the `do prd:<slug>` tasking path the improver loop is
+	 * `--no-tasker-loop`). On the `do spec:<slug>` tasking path the improver loop is
 	 * the task path's quality engine (auto-tasking has no `verify` floor), so it is
 	 * ON by default; setting this false gates wiring the loop seam (the candidate
 	 * tasks land as-is). Resolved per-repo like `integration`: flag
@@ -529,8 +529,8 @@ export interface Config {
 	taskerLoop: boolean;
 	/**
 	 * **The tasker IMPROVER loop's convergence cap** (`slicer-review-edit-loop`,
-	 * GATES prd `work/prds/tasked/review.md` RESOLVED DESIGN — Shape 2 / insertion point
-	 * A). On the `do prd:<slug>` tasking path, AFTER the agent produces candidate
+	 * GATES spec `work/specs/tasked/review.md` RESOLVED DESIGN — Shape 2 / insertion point
+	 * A). On the `do spec:<slug>` tasking path, AFTER the agent produces candidate
 	 * tasks the loop runs the `review` SKILL, APPLIES its edits, and re-reviews
 	 * until a pass finds no NEW blocking issue (the natural terminator).
 	 * `taskerLoopMax` is the HARD CAP on the in-context review passes (N) so the
@@ -583,7 +583,7 @@ export interface Config {
 	freshWorktreeGate: boolean;
 	/**
 	 * **The cross-job merge serialiser's CAS-retry cap** — the git-alone FLOOR of the
-	 * land-time cross-job queue (prd `land-time-reverify-and-parallel-merge-ceiling`,
+	 * land-time cross-job queue (spec `land-time-reverify-and-parallel-merge-ceiling`,
 	 * Story 5 + Applied Answer q1 (a)). The merge-mode `${branch}:main` push retries
 	 * a non-fast-forward rejection by re-rebasing onto the moved `<arbiter>/main` and
 	 * pushing again, up to this cap; only after exhaustion does a loser bounce to
@@ -605,7 +605,7 @@ export interface Config {
 	mergeRetries: number;
 	/**
 	 * **Per-repo OPT-IN strictness layered on the OQ6 stale-approval default**
-	 * (prd `land-time-reverify-and-parallel-merge-ceiling`, sidecar OQ6 / task
+	 * (spec `land-time-reverify-and-parallel-merge-ceiling`, sidecar OQ6 / task
 	 * `strict-merge-approval-gate`). Controls how the apply rung treats a prior
 	 * merge-answer when the merge-base CHANGED between the human's answer and
 	 * the apply step. The default (`false`) honours the prior answer and lands
@@ -711,7 +711,7 @@ export const DEFAULT_CONFIG: Config = {
 	// auto-dispose the no-question cases). ADR `ci-config-policy-and-gate-family` §3.
 	observationTriage: 'off',
 	// The merge-question SURFACER defaults to `ask` — the conservative default
-	// (prd `land-time-reverify-and-parallel-merge-ceiling` Applied answer q2 /
+	// (spec `land-time-reverify-and-parallel-merge-ceiling` Applied answer q2 /
 	// task `merge-questions-gate-axis` Applied answer q2). NEVER `off` by default:
 	// a silently-dropped merge-question means finished, pushed work never lands —
 	// strictly more consequential than a dropped observation-promote prompt, so
@@ -728,9 +728,9 @@ export const DEFAULT_CONFIG: Config = {
 	// (a stuck build) is separate + always-on. ADR `ci-config-policy-and-gate-family` §3.
 	surfaceBlockers: false,
 	// SURFACING widens to STAGING by default (`true`) — a `needsAnswers` task in
-	// `tasks/backlog/` or a `needsAnswers` prd in `prds/proposed/` surfaces
+	// `tasks/backlog/` or a `needsAnswers` spec in `specs/proposed/` surfaces
 	// its questions BEFORE promotion, so a human promotes an already-clarified
-	// item. Prd `staging-surface-and-apply-promote-safety` (F2). BUILD/claim
+	// item. Spec `staging-surface-and-apply-promote-safety` (F2). BUILD/claim
 	// stays pool-only + trust-gated regardless: this widens ONLY the surface
 	// polarity, not the build polarity. Set `false` to restore the legacy
 	// pool-only surface behaviour.
@@ -791,7 +791,7 @@ export const DEFAULT_CONFIG: Config = {
 	// (positive name, default-on).
 	freshWorktreeGate: true,
 	// The cross-job merge serialiser's CAS-retry cap — the git-alone FLOOR of the
-	// land-time cross-job queue (prd `land-time-reverify-and-parallel-merge-ceiling`,
+	// land-time cross-job queue (spec `land-time-reverify-and-parallel-merge-ceiling`,
 	// Story 5 + Applied Answer q1 (a)). Matches `integration-core.ts`'s built-in
 	// `DEFAULT_MERGE_RETRIES` fallback (1000 — the C2 large liveness ceiling, NOT a
 	// small Race-1 budget) so resolving it through this layer is byte-for-byte
@@ -800,7 +800,7 @@ export const DEFAULT_CONFIG: Config = {
 	mergeRetries: 1000,
 	// The strict-merge-approval gate defaults OFF (sidecar OQ6 / task
 	// `strict-merge-approval-gate`): the cheap "green re-verify is enough" path
-	// is the default; the OQ6 PRD answer pins this. A repo opts in to the
+	// is the default; the OQ6 SPEC answer pins this. A repo opts in to the
 	// host-agnostic "dismiss stale approvals on base change" discipline with
 	// `strictMergeApproval: true` (or `--strict-merge-approval` /
 	// `DORFL_STRICT_MERGE_APPROVAL=true`). The re-surface vs. land branch is

package/src/continue-branch.ts

@@ -156,7 +156,7 @@ export interface ContinueRebaseResult {
  * (ADR §10: rebase, NOT merge — linear history; the prior attempt's commits were
  * based on an OLD main that moved while the item sat in backlog).
  *
- * This is a PLAIN rebase. After the per-item-lock cut-over (prd
+ * This is a PLAIN rebase. After the per-item-lock cut-over (spec
  * `ledger-status-per-item-lock-refs`, tasks 9a–9d) NO transient status lands on
  * a work branch: claim does not move the body (it rests in `backlog/`),
  * needs-attention is the lock `state: stuck` (not a `git mv`), and the

package/src/cwd-section.ts

@@ -268,7 +268,7 @@ export async function resolveCwdSection(
 	const localReport = scanRepoPaths([cwd], config, heldSlugs, options.override);
 	const repo = localReport.repos[0];
 
-	// 3b. The PER-ITEM LOCK in-flight SURFACE for the cwd (prd
+	// 3b. The PER-ITEM LOCK in-flight SURFACE for the cwd (spec
 	//     `ledger-status-per-item-lock-refs` US #8). The subtraction above removes a
 	//     held slug from the eligible `items[]` pool; on its OWN that leaves a
 	//     held/stuck cwd item in a BLIND SPOT — gone from every bucket with nothing

package/src/decision-engine.ts

@@ -1,7 +1,7 @@
 import {extractJsonObjectSpan} from './verdict-json.js';
 
 /**
- * **The SHARED decision engine** (prd
+ * **The SHARED decision engine** (spec
  * `agentic-question-resolution-retire-disposition-vocabulary` US #9, decision 3 +
  * 13/14; task `decision-engine-shared-decide-seam`): the GENERALISED
  * `decide(input, allowedOutcomes) → verdict` core every question-resolution
@@ -20,7 +20,7 @@ import {extractJsonObjectSpan} from './verdict-json.js';
  *   "the INPUT adapter differs per front door and is NOT forced to be shared").
  * - **the ALLOWED-OUTCOME SET** ({@link decide}'s `allowedOutcomes`): each caller
  *   passes the SUBSET of {@link DecisionOutcome} it permits — advance-apply allows
- *   `{task | prd | adr | delete | ask}`, intake keeps its own `{task | prd | ask |
+ *   `{task | prd | adr | delete | ask}`, intake keeps its own `{task | spec | ask |
  *   bounce}` (intake is NOT refactored onto this engine here — decision 13). The
  *   engine never hard-codes which outcomes a caller permits; it only VALIDATES the
  *   returned verdict against the set and rejects (loudly) one outside it
@@ -51,7 +51,7 @@ import {extractJsonObjectSpan} from './verdict-json.js';
  * No caller is forced to allow ALL of these: each passes its own SUBSET to
  * {@link decide}. The engine is agnostic to which subset a caller permits.
  */
-// MIGRATE step (prd `prd-to-spec-vocabulary-cutover-and-migration-command`): the
+// MIGRATE step (spec `prd-to-spec-vocabulary-cutover-and-migration-command`): the
 // parent-spec verdict outcome is `'spec'` (renamed from `'prd'`); the decider
 // prompt emits it and the parser accepts it. This is a fresh per-call LLM verdict
 // (nothing `'prd'`-valued is persisted), so the rename needs no on-disk alias.

package/src/do-autopick.ts

@@ -24,9 +24,9 @@ import type {ConfigOverrideMap} from './config-override.js';
  * Auto-pick / `-n` draw from TWO POOLS ordered by the configurable
  * `selectionOrder` (the shared, pure {@link selectPrioritised} helper): eligible
  * TASKS (the `build` pool — the existing `scan`/`selectCandidates`/eligibility
- * path) and TASKABLE prds (the `task` pool — built from the prd reader +
+ * path) and TASKABLE prds (the `task` pool — built from the spec reader +
  * `autoslice-gate`'s predicate), in the per-repo `selectionOrder` (default `drain`
- * = tasks-first). A selected prd dispatches to the `do prd:<slug>` path (tasking
+ * = tasks-first). A selected spec dispatches to the `do spec:<slug>` path (tasking
  * itself is `autoslice-command`, not built here).
  *
  * Explicit multi-arg (`do <a> <b>`) bypasses the pools/priority entirely — the
@@ -41,7 +41,7 @@ type SharedDoOptions = Omit<DoOptions, 'arg'>;
 
 export interface PerformDoMultiOptions extends SharedDoOptions {
 	/**
-	 * The resolved repo config (provides `autoTask` for the prd gate,
+	 * The resolved repo config (provides `autoTask` for the spec gate,
 	 * `selectionOrder` for the pool order, and the task-pool selection caps). The
 	 * per-item runs still receive `autoTask`/`integration`/etc. via the spread
 	 * `SharedDoOptions`.
@@ -62,7 +62,7 @@ export interface PerformDoMultiOptions extends SharedDoOptions {
 	count?: number;
 	/** Override the single-`do` runner (tests inject a stub). Defaults to {@link performDo}. */
 	run?: DoRunner;
-	/** Override the read seam (prd pool); defaults to the active {@link ledgerRead}. */
+	/** Override the read seam (spec pool); defaults to the active {@link ledgerRead}. */
 	read?: LedgerReadStrategy;
 }
 
@@ -85,7 +85,7 @@ export interface DoMultiResult {
  * The task-pool caps for an in-place `do` selection. `do` is per-repo +
  * sequential, so the REAL bound is the requested `count` (handled by the
  * priority helper); the task-pool selection should not truncate BEFORE the
- * count + the prd pool are combined. We therefore cap the task pool at "all
+ * count + the spec pool are combined. We therefore cap the task pool at "all
  * eligible" (a large bound) and let {@link selectPrioritised}'s `count` do the
  * trimming across both pools.
  */
@@ -116,7 +116,7 @@ export async function performDoAuto(
 		options.override,
 	);
 
-	// Pool 2 — TASKABLE prds: the NEW pool from the shared prd read path
+	// Pool 2 — TASKABLE prds: the NEW pool from the shared spec read path
 	// (`resolveSpecPool`) filtered by `autoslice-gate`'s predicate (not reinvented).
 	const pool = read.resolveSpecPool({repoPath: cwd});
 	const specCandidates: SpecCandidate[] = pool.specs.map((spec) => ({
@@ -155,8 +155,8 @@ export async function performDoAuto(
 /**
  * Run the EXPLICIT multi-arg form (`do <a> <b> …`): the named items in the GIVEN
  * order (no pool/priority — the operator chose them). Each arg is run through the
- * existing `do` pipeline, which itself resolves bare/`task:`/`prd:` (so a named
- * prd dispatches to the tasking path and a collision errors), SEQUENTIALLY.
+ * existing `do` pipeline, which itself resolves bare/`task:`/`spec:` (so a named
+ * spec dispatches to the tasking path and a collision errors), SEQUENTIALLY.
  */
 export async function performDoArgs(
 	args: string[],
@@ -176,7 +176,7 @@ export async function performDoArgs(
 /**
  * Run a list of selected items through the existing `do` pipeline, SEQUENTIALLY,
  * threading the shared options to each. For the pool path the `do` arg encodes
- * the namespace (`prd:<slug>` for a selected prd, bare slug for a task); for the
+ * the namespace (`spec:<slug>` for a selected spec, bare slug for a task); for the
  * explicit-arg path the caller's raw arg is passed verbatim.
  */
 async function runSelectedInSequence(