dorfl 0.1.0 → 0.1.2

package/src/advance-loop-driver.ts

@@ -26,7 +26,7 @@ import type {
 } from './run.js';
 
 /**
- * The **`advance` LOOP DRIVER** (prd `advance-loop`, task
+ * The **`advance` LOOP DRIVER** (spec `advance-loop`, task
  * `advance-drivers-and-gates`, US #7/22/26/31) — the second of the two drivers
  * over the substrate-agnostic advance TICK. Where the one-shot driver
  * (`advance-drivers.ts`) runs the tick over named item(s) SEQUENTIALLY, this
@@ -113,7 +113,7 @@ export interface AdvanceOnceOptions {
 
 /** One advanced item's result + the identity it was for (input order preserved). */
 export interface AdvanceBatchItem {
-	/** The namespaced arg the tick was run on (`prd:<slug>` / bare slug). */
+	/** The namespaced arg the tick was run on (`spec:<slug>` / bare slug). */
 	arg: string;
 	/** The tick's result, or a captured throw mapped to a usage-error result. */
 	result: AdvanceResult;
@@ -549,7 +549,7 @@ export interface AdvanceRunTickDeps extends Omit<
  * Adapt the {@link advanceOnce} LOOP DRIVER to the {@link RunTick} swap SEAM so
  * `run` (≡ CI, US #7) drives the ADVANCE tick over the mirror-side eligible pool
  * instead of the build tick. `run.ts` deliberately writes {@link runLoop} against
- * {@link RunTick} (NOT against `runOnce`) precisely so the advance-loop prd can
+ * {@link RunTick} (NOT against `runOnce`) precisely so the advance-loop spec can
  * swap the tick WITHOUT re-architecting the loop — this is that swap.
  *
  * The seam is `(RunOnceOptions) => Promise<RunOnceResult>`; one advance batch is

package/src/advance-treeless-publish.ts

@@ -34,7 +34,7 @@ import {runAsync} from './git.js';
  *
  * **C2 rebase-until-real-conflict (task `c2-rebase-until-real-on-durable-main-
  * promotions`).** This same `HEAD:main` push carries the won't-proceed terminal
- * `tasks/ready → tasks/cancelled` / `prds/ready → prds/dropped` (slug-RELOCATION
+ * `tasks/ready → tasks/cancelled` / `specs/ready → specs/dropped` (slug-RELOCATION
  * family) when `apply-persist.ts` resolves a `dropped` disposition; under sustained
  * parallel load on the shared `main` ref two DIFFERENT items' concurrent promotions
  * can falsely-contend even though nothing tree-conflicts, exhausting a small fixed

package/src/advance.ts

@@ -70,9 +70,9 @@ import type {VerifyConfig} from './verify.js';
 import type {NewQuestion} from './sidecar.js';
 
 /**
- * The **`advance` verb SKELETON** (prd `advance-loop`, task
+ * The **`advance` verb SKELETON** (spec `advance-loop`, task
  * `advance-verb-resolver`, US #1/5/6/18). `advance` is the SIBLING top-level verb
- * (NOT a `do` subcommand — `do` subcommands are REJECTED in the prd) that drives
+ * (NOT a `do` subcommand — `do` subcommands are REJECTED in the spec) that drives
  * a `work/` item ONE lifecycle rung toward "ready/built", reusing the SAME shared
  * `prefix:arg` resolver `do` uses (extended with the `obs:` namespace, see
  * {@link resolveAdvanceArg}).
@@ -96,7 +96,7 @@ import type {NewQuestion} from './sidecar.js';
  * (`advance-rung-surface`), `apply` (`advance-rung-apply`), and
  * `triage-observation` (`advance-rung-triage`) dispatch through the clearly-named
  * executor SEAM ({@link RungExecutor}); the build/task rungs ORCHESTRATE
- * `do`/`do prd:`. What this verb does NOT do (LATER tasks):
+ * `do`/`do spec:`. What this verb does NOT do (LATER tasks):
  *   - The two **DRIVERS** (one-shot sequential / loop) + `-n` + the gate-FAMILY
  *     WIRING that resolves `autoBuild`/`autoTask`/`observationTriage` and threads
  *     them into the build/task gate composition — task `advance-drivers-and-gates`.
@@ -144,7 +144,7 @@ export type AdvanceExitCode = 0 | 1 | 2 | 3;
  * The injectable rung-executor SEAM — WHAT happens once the tick has classified a
  * rung AND won the `advancing` lock. It is the boundary between the skeleton (this
  * task) and the rung bodies (later tasks): the surface/apply/triage rungs are
- * filled by their own tasks; the build/task rungs ORCHESTRATE `do`/`do prd:`.
+ * filled by their own tasks; the build/task rungs ORCHESTRATE `do`/`do spec:`.
  *
  * Production wires {@link defaultRungExecutor}; tests inject a spy to assert the
  * classify→lock→dispatch ORDER (and that a CAS loser never reaches the executor).
@@ -164,7 +164,7 @@ export interface RungExecutor {
 
 /** What a rung executor is handed: the resolved identity + the run context. */
 export interface RungExecInput {
-	/** The canonical namespaced identity (`task:<slug>` / `prd:<slug>` / `observation:<slug>`). */
+	/** The canonical namespaced identity (`task:<slug>` / `spec:<slug>` / `observation:<slug>`). */
 	item: string;
 	/** The resolved namespace (`task` / `prd` / `observation`). */
 	namespace: SlugNamespace;
@@ -172,7 +172,7 @@ export interface RungExecInput {
 	slug: string;
 	/** The classification that selected this rung (the two signals are visible). */
 	classification: TickClassification;
-	/** The tick's run context (cwd, arbiter, …) — threaded to `do`/`do prd:`. */
+	/** The tick's run context (cwd, arbiter, …) — threaded to `do`/`do spec:`. */
 	context: AdvanceContext;
 }
 
@@ -250,14 +250,14 @@ export interface AdvanceContext {
 	 * The AGENTIC apply DECISION seam (task
 	 * `agentic-apply-retire-disposition-vocabulary`): the fresh-context decision
 	 * agent the apply rung runs on a fully-answered OBSERVATION to choose what to DO
-	 * with the signal (`mint-task | mint-prd | mint-adr | delete-source |
+	 * with the signal (`mint-task | mint-spec | mint-adr | delete-source |
 	 * ask-follow-up`),
 	 * grounded in the source's full context. It is the injected
 	 * {@link ApplyDecider} the shared `decide(input, allowedOutcomes)` engine runs;
 	 * tests inject a CANNED verdict (no model). `undefined` ⇒ the apply rung defaults
 	 * to {@link harnessApplyDecider} (a NullHarness, no real model) so the seam is
 	 * never a crash — but the CLI threads the real harness-backed decider. The
-	 * verdict's type SELECTION (task vs prd vs adr) replaces the retired `promote-*`
+	 * verdict's type SELECTION (task vs spec vs adr) replaces the retired `promote-*`
 	 * disposition token; `adr` is now WIRED (task `agentic-apply-mint-adr-route`).
 	 */
 	applyDecide?: ApplyDecider;
@@ -325,7 +325,7 @@ export interface AdvanceContext {
 	 * to the dispatcher, so an answered `kind: merge` entry is REFUSED (clean
 	 * surfacing); the answer stays for a follow-up. The registry-set advance
 	 * driver threads the resolved `workspacesDir` here.
-	 * (prd `land-time-reverify-and-parallel-merge-ceiling`, task
+	 * (spec `land-time-reverify-and-parallel-merge-ceiling`, task
 	 * `apply-rung-merge-disposition`)
 	 */
 	workspacesDir?: string;
@@ -353,7 +353,7 @@ export interface AdvanceContext {
 	/**
 	 * Resolved `strictMergeApproval` boolean (sibling task
 	 * `strict-merge-approval-gate`). Default OFF ⇒ honour the prior approval +
-	 * land on a green re-verify (cheap, the PRD-applied OQ6 default). ON ⇒
+	 * land on a green re-verify (cheap, the SPEC-applied OQ6 default). ON ⇒
 	 * re-surface the merge-question when the merge-base moved between the
 	 * surfacer's question and this apply (the host-agnostic analogue of
 	 * GitHub's "dismiss stale approvals when the base changes").
@@ -377,7 +377,7 @@ export interface AdvanceContext {
 /** The options one `advance` tick consumes. */
 export interface AdvanceOptions extends AdvanceContext {
 	/**
-	 * The raw CLI slug argument: bare (= task), `task:<slug>`, `prd:<slug>`, or
+	 * The raw CLI slug argument: bare (= task), `task:<slug>`, `spec:<slug>`, or
 	 * `obs:<slug>` / `observation:<slug>`. Omit/empty ⇒ the bare eligible-SET form,
 	 * which needs the driver task (a clear error here — see `## Decisions`).
 	 */
@@ -420,7 +420,7 @@ export interface ItemSignals {
 export interface ReadSignalsInput {
 	/** The repo working-tree root. */
 	repoPath: string;
-	/** The item type (task / prd / observation). */
+	/** The item type (task / spec / observation). */
 	type: SidecarType;
 	/** The bare slug. */
 	slug: string;
@@ -469,14 +469,14 @@ export function readItemSignals(input: ReadSignalsInput): ItemSignals {
  * The lifecycle folders each item type may rest in (frontmatter source). After
  * the capstone cut-over (task
  * `cutover-retire-slicing-advancing-markers-and-trim-folder-sets`) the transient
- * `tasking/` folder is GONE — a prd rests in `prds/ready` (source) or
- * `prds/tasked` (tasked); while it is being tasked the body STAYS in
- * `prds/ready` (the lock no longer moves it), so `tasking/` is never a
+ * `tasking/` folder is GONE — a spec rests in `specs/ready` (source) or
+ * `specs/tasked` (tasked); while it is being tasked the body STAYS in
+ * `specs/ready` (the lock no longer moves it), so `tasking/` is never a
  * frontmatter source.
  *
  * STAGING IS INCLUDED (`tasks-backlog` / `prds-proposed`): with `surfaceStaging`
  * on (the user-visible default) the lifecycle surface pool enumerates
- * `needsAnswers` items resting in STAGING as `task:`/`prd:` legs
+ * `needsAnswers` items resting in STAGING as `task:`/`spec:` legs
  * (`lifecycle-gather.ts`). The rung CLASSIFIER's signal read MUST see those
  * staged bodies, or `needsAnswers` reads back `undefined`, the classifier
  * mis-routes the item to the BUILD rung, and claim dies with "not found on
@@ -512,11 +512,11 @@ function readNeedsAnswers(
 
 /**
  * The PRODUCTION rung executor: build/task rungs ORCHESTRATE the existing
- * `do`/`do prd:` machinery ({@link performDo}); the `surface`/`apply`/
+ * `do`/`do spec:` machinery ({@link performDo}); the `surface`/`apply`/
  * `triage-observation` rung bodies are filled by their own tasks
  * ({@link surfaceRung} / {@link applyRung} / {@link triageRung}). It NEVER
  * re-implements the build/task path — it hands the resolved arg to `performDo`,
- * which spans both namespaces (the task path is the `do prd:` rung the prd's
+ * which spans both namespaces (the task path is the `do spec:` rung the spec's
  * 2026-06-09 UPDATE confirms routes through `performIntegration`).
  */
 export const defaultRungExecutor: RungExecutor = {
@@ -807,7 +807,7 @@ async function triageRung(input: RungExecInput): Promise<RungExecResult> {
  * apply rung is now AGENT-DRIVEN: it runs the shared `decide(input, allowedOutcomes)`
  * engine ({@link decide}) over `(the answered question(s) + the SOURCE item + its
  * type/context)` via the injected {@link ApplyDecider}, allowing the set
- * `{task | prd | adr | delete | ask}` (= `{mint-task | mint-prd | mint-adr |
+ * `{task | prd | adr | delete | ask}` (= `{mint-task | mint-spec | mint-adr |
  * delete-source | ask-follow-up}`; `adr` is now WIRED by task
  * `agentic-apply-mint-adr-route`, which added the {@link mintAdr} route). The
  * verdict ROUTES:
@@ -823,9 +823,9 @@ async function triageRung(input: RungExecInput): Promise<RungExecResult> {
  *   - `delete` → {@link applyAnsweredQuestions} discharge-by-deletion (`git rm`
  *     source + sidecar in one revertible commit, the reason in the commit message).
  *
- * For a TASK/PRD (answering its OWN open questions) or a caller-supplied follow-up
+ * For a TASK/SPEC (answering its OWN open questions) or a caller-supplied follow-up
  * batch, it delegates straight to {@link applyAnsweredQuestions} (resolve fully /
- * re-pause) — the lifecycle path is untouched (a task/prd is dropped by its own
+ * re-pause) — the lifecycle path is untouched (a task/spec is dropped by its own
  * lifecycle, not by a question answer).
  *
  * Under the `advancing` CAS lock (held by {@link performAdvance} BEFORE this runs
@@ -844,7 +844,7 @@ async function applyRung(input: RungExecInput): Promise<RungExecResult> {
 		return vanishedSkip({rung: 'apply', item});
 	}
 
-	// RUNNER-ACTION KIND-CHECK (task `apply-rung-merge-disposition`, prd
+	// RUNNER-ACTION KIND-CHECK (task `apply-rung-merge-disposition`, spec
 	// `land-time-reverify-and-parallel-merge-ceiling`): an answered `kind: merge`
 	// sidecar entry is a DETERMINISTIC land action, NOT a content decision. It
 	// dispatches HERE (a sibling of the agentic `decide()`), keyed off the
@@ -862,7 +862,7 @@ async function applyRung(input: RungExecInput): Promise<RungExecResult> {
 	// AGENTIC APPLY for an answered OBSERVATION (the subsumed triage rung): run the
 	// shared decision engine over the answer(s) + source, route the verdict. A
 	// caller-supplied follow-up batch (`applyFollowups`) bypasses the decision and
-	// re-pauses directly (a test/driver hook). TASK/PRD items resolve in place
+	// re-pauses directly (a test/driver hook). TASK/SPEC items resolve in place
 	// (their own lifecycle), so they skip the decision and fall through to the
 	// persist below.
 	const runAgenticDecision =
@@ -910,7 +910,7 @@ async function applyRung(input: RungExecInput): Promise<RungExecResult> {
  * the merge-question surfacer) through the EXISTING land primitive
  * (`performIntegration` with `committedRecovery: true` + `freshWorktreeGate:
  * true`) via the EXISTING per-job worktree seam (`workspace.ts` `createJob`).
- * The deterministic SIBLING of the agentic `decide()` content-decision (PRD
+ * The deterministic SIBLING of the agentic `decide()` content-decision (SPEC
  * `land-time-reverify-and-parallel-merge-ceiling`, task
  * `apply-rung-merge-disposition`; Stories #15, #16): a merge-acceptance has no
  * judgement content (the human's plain `merge | hold | drop` answer IS the
@@ -919,7 +919,7 @@ async function applyRung(input: RungExecInput): Promise<RungExecResult> {
  *
  * Returns `undefined` when there is no answered `kind: merge` entry to dispatch
  * (the apply rung then proceeds to the existing path — agentic for
- * observations, normal `applyAnsweredQuestions` for task/prd content questions).
+ * observations, normal `applyAnsweredQuestions` for task/spec content questions).
  * Returns a {@link RungExecResult} when the dispatcher handled the rung:
  *
  *   - `landed` / `already-integrated` ⇒ the kept commit landed on `main` (or
@@ -1113,7 +1113,7 @@ function findItemPath(
  * The AGENTIC apply DECISION for a fully-answered OBSERVATION (task
  * `agentic-apply-retire-disposition-vocabulary`): run the shared
  * `decide(input, allowedOutcomes)` engine over the answer(s) + source, then ROUTE
- * the verdict. The artifact-type selection (task vs prd) comes from the agent's
+ * the verdict. The artifact-type selection (task vs spec) comes from the agent's
  * VERDICT, NOT a human `promote-*` field (which is retired). Replaces the old
  * `answeredPromoteArtifact` + disposition picker.
  *
@@ -1353,13 +1353,13 @@ export async function performAdvance(
 		const message =
 			'`advance` with no item is the eligible-SET form (the one-shot driver). ' +
 			'The single-item tick needs a named item: ' +
-			'`advance <slug>` / `advance prd:<slug>` / `advance obs:<slug>`.';
+			'`advance <slug>` / `advance spec:<slug>` / `advance obs:<slug>`.';
 		note(message);
 		return {exitCode: 1, outcome: 'usage-error', message};
 	}
 
 	// 1. RESOLVE the arg via the SHARED resolver (extended with `obs:`). `advance`
-	//    spans task / prd / observation; a collision / bad arg is a loud usage error.
+	//    spans task / spec / observation; a collision / bad arg is a loud usage error.
 	let resolved;
 	try {
 		resolved = resolveAdvanceArg({
@@ -1419,7 +1419,7 @@ export async function performAdvance(
 	// 3. LOCK — take the `advancing` CAS borrow for the classified rung, keyed on
 	//    the item's `<type>-<slug>` identity. The expensive phase is POST-lock.
 	//
-	//    UNIFIED PER-ITEM LOCK, TREE-LESS RUNGS ONLY (prd
+	//    UNIFIED PER-ITEM LOCK, TREE-LESS RUNGS ONLY (spec
 	//    `ledger-status-per-item-lock-refs` US #1/#3/#18; ADR
 	//    `ledger-status-on-per-item-lock-refs`). The rung kind is KNOWN here
 	//    (`classification.kind`, classified pre-lock), so the tree-less-only policy
@@ -1428,7 +1428,7 @@ export async function performAdvance(
 	//    TREE-LESS rung (`surface`/`apply`/`triage-observation`) the advancing acquire
 	//    ALSO takes the item's unified lock (`action: advance`) — these rungs have NO
 	//    inner `do`, so the unified hold is what realises advance∥claim / advance∥task
-	//    exclusion. For a BUILD-TASK / TASK-PRD rung we do NOT take the unified lock
+	//    exclusion. For a BUILD-TASK / TASK-SPEC rung we do NOT take the unified lock
 	//    at the advance layer: `performAdvance` ORCHESTRATES an inner `performDo` that
 	//    ITSELF acquires the SAME `task-<slug>`/`prd-<slug>` ref (the create-only CAS
 	//    with NO re-entrancy/auto-steal, per the ADR), so taking it here too would

package/src/advancing-lock.ts

@@ -7,11 +7,11 @@ import {acquireItemLock, releaseItemLock} from './item-lock.js';
 import {realSleep, type Sleep} from './retry-backoff.js';
 
 /**
- * The **advancing-lock BORROW** (prd `advance-loop`, task
+ * The **advancing-lock BORROW** (spec `advance-loop`, task
  * `advancing-lock-borrow`, US #19–24).
  *
  * The surface/apply/triage phase's SHORT borrow. As of the capstone cut-over
- * (task `cutover-retire-slicing-advancing-markers-and-trim-folder-sets`, prd
+ * (task `cutover-retire-slicing-advancing-markers-and-trim-folder-sets`, spec
  * `ledger-status-per-item-lock-refs`; ADR `ledger-status-on-per-item-lock-refs`)
  * the legacy `work/advancing/<entry>.md` presence-MARKER on `main` is GONE. The
  * advancing borrow now rides ONLY the UNIFIED per-item lock
@@ -21,7 +21,7 @@ import {realSleep, type Sleep} from './retry-backoff.js';
  *
  * The borrow is keyed by item IDENTITY (`<type>-<slug>`, via
  * {@link resolveSidecarIdentity} — the single source of truth the unified lock,
- * the sidecar, and the work branch all share), so a task, a prd, and an
+ * the sidecar, and the work branch all share), so a task, a spec, and an
  * observation that share a slug NEVER collide, and the SAME `<entry>` ref means an
  * `advance` hold is MUTUALLY EXCLUSIVE with a claim/task hold of the SAME item BY
  * CONSTRUCTION (the second acquirer loses the SAME create-only ref CAS).
@@ -29,7 +29,7 @@ import {realSleep, type Sleep} from './retry-backoff.js';
  * It is file-ORTHOGONAL to the item it locks: the item's own lifecycle file NEVER
  * moves (the borrow is a LOCK, not a lifecycle transition), which is exactly why
  * it can lock items resting in DIFFERENT source folders (a backlog task, a `prds/`
- * prd, an `observations/` note) with one uniform mechanism.
+ * spec, an `observations/` note) with one uniform mechanism.
  *
  * **TREE-LESS vs BUILD/TASK RUNGS (`acquireUnified`).** The advance tick sets
  * `acquireUnified` PER RUNG (the policy lives in `advance.ts`, where the rung is
@@ -40,7 +40,7 @@ import {realSleep, type Sleep} from './retry-backoff.js';
  *     IS the advance∥claim / advance∥task exclusion. Acquire/release delegate to
  *     {@link acquireItemLock} / {@link releaseItemLock} (a parentless ref CAS, no
  *     working-tree write, no retry budget).
- *   - **BUILD-TASK / TASK-PRD rungs** never take the unified lock at the advance
+ *   - **BUILD-TASK / TASK-SPEC rungs** never take the unified lock at the advance
  *     layer (`acquireUnified` false): `performAdvance` orchestrates an inner
  *     `performDo` that ITSELF acquires the SAME `task-<slug>`/`prd-<slug>` ref
  *     (the create-only CAS with NO re-entrancy/auto-steal), so taking it again here
@@ -81,7 +81,7 @@ export type AcquireAdvancingLockExitCode = 0 | 1 | 2 | 3;
 
 export interface AcquireAdvancingLockOptions {
 	/**
-	 * The NAMESPACED item identity to lock (`task:<slug>` / `prd:<slug>` /
+	 * The NAMESPACED item identity to lock (`task:<slug>` / `spec:<slug>` /
 	 * `obs:<slug>` / `observation:<slug>`, or a bare `<slug>` = task). The
 	 * resolver derives the type-encoded entry `<type>-<slug>` from it.
 	 */

package/src/apply-decide.ts

@@ -11,7 +11,7 @@ import {
 } from './decision-engine.js';
 
 /**
- * The **AGENTIC apply DECIDER** (prd
+ * The **AGENTIC apply DECIDER** (spec
  * `agentic-question-resolution-retire-disposition-vocabulary` US #1/#2/#3, task
  * `agentic-apply-retire-disposition-vocabulary`) — the input-ADAPTER + prompt +
  * production decider for the apply rung's call into the SHARED
@@ -35,7 +35,7 @@ import {
  * `agentic-apply-mint-adr-route`, which added the {@link
  * import('./mint-adr.js').mintAdr} route and widened this set. Intake's set is
  * UNCHANGED (`{task | spec | ask | bounce}`) \u2014 the engine stays outcome-AGNOSTIC
- * (PRD decision 14), so widening this caller's subset does NOT touch intake or the
+ * (SPEC decision 14), so widening this caller's subset does NOT touch intake or the
  * engine's superset union.
  *
  * The INPUT adapter ({@link buildApplyDecisionInput}) sits HERE in the caller, not

package/src/apply-merge-action.ts

@@ -17,7 +17,7 @@ import {
 import type {VerifyConfig} from './verify.js';
 
 /**
- * The **answered MERGE-QUESTION ACTION DISPATCH** (prd
+ * The **answered MERGE-QUESTION ACTION DISPATCH** (spec
  * `land-time-reverify-and-parallel-merge-ceiling`, task
  * `apply-rung-merge-disposition`; Stories #15, #16) — the deterministic,
  * answer-driven RUNNER-ACTION layer that turns an answered
@@ -29,7 +29,7 @@ import type {VerifyConfig} from './verify.js';
  * `apply-decide.ts`, NOT a route through it: a merge-acceptance has no
  * judgement content (the human's plain `merge | hold | drop` answer IS the
  * decision; the apply-time fresh-worktree re-verify on the rebased tip is the
- * real correctness gate). Per the PRD's resolved mechanism, routing this
+ * real correctness gate). Per the SPEC's resolved mechanism, routing this
  * through an LLM only adds cost and non-determinism, so the apply rung
  * KIND-CHECKS the sidecar BEFORE calling the agentic decider: a sidecar entry
  * carrying `kind: merge` (the typed dispatch field from `sidecar-kind-field`,
@@ -54,7 +54,7 @@ import type {VerifyConfig} from './verify.js';
  *     branch itself is out of this task's scope — the question is recorded as
  *     "drop" and the human / a later surfacer handles the artifact.)
  *
- * The STALE-APPROVAL POLICY (PRD OQ6, applied answer q1): default is the cheap
+ * The STALE-APPROVAL POLICY (SPEC OQ6, applied answer q1): default is the cheap
  * "HONOUR the prior approval + land on a green re-verify" path; opt-in
  * `strictMergeApproval` (resolved per-repo via the gate-family precedence chain
  * by the sibling task `strict-merge-approval-gate`, default OFF) RE-SURFACES
@@ -120,7 +120,7 @@ export function parseMergeAnswer(text: string): MergeActionVerb | undefined {
  * a fully-answered sidecar (the apply rung's pre-decider kind-check). Returns
  * `undefined` when the sidecar carries no answered `kind: merge` entry (the
  * apply rung then proceeds to the existing path — agentic for observations,
- * normal apply for task/prd content questions).
+ * normal apply for task/spec content questions).
  *
  * The sidecar is read OFF DISK keyed off the namespaced item identity; the
  * model is parsed via the SAME `parseSidecar` the rest of the engine uses.
@@ -266,7 +266,7 @@ function resolveArbiterUrl(input: MergeActionInput): string | undefined {
 }
 
 /**
- * The `strictMergeApproval` re-stale check (PRD OQ6 opt-in): did `<arbiter>/
+ * The `strictMergeApproval` re-stale check (SPEC OQ6 opt-in): did `<arbiter>/
  * main` move past the merge-base of the work branch since the surfacer
  * authored the question? The git-alone analogue of GitHub's "dismiss stale
  * approvals when the base changes" — host-agnostic by reachability.

package/src/apply-persist.ts

@@ -17,7 +17,7 @@ import {
 } from './item-path.js';
 
 /**
- * The engine-owned APPLY PERSIST (prd `advance-loop`, task `advance-rung-apply`;
+ * The engine-owned APPLY PERSIST (spec `advance-loop`, task `advance-rung-apply`;
  * AGENTIC apply, task `agentic-apply-retire-disposition-vocabulary`) — the half of
  * the APPLY rung the ENGINE owns. On `classify=apply` (ALL sidecar entries
  * answered), it applies the HUMAN's answers to the item ATOMICALLY (item body +
@@ -45,9 +45,9 @@ import {
  * `promoteObservation` for a mint). A signal is still-open, acted-on, or deleted
  * — there is no \"retain as resolved\" state.
  *
- * The work-item (task/prd) terminal MOVES (`tasks/cancelled`, `prds/dropped`) and
+ * The work-item (task/spec) terminal MOVES (`tasks/cancelled`, `specs/dropped`) and
  * the `needs-attention/` LIFECYCLE state are a SEPARATE lifecycle concern (a
- * task/prd is dropped by its own lifecycle, not by a question answer) — they are
+ * task/spec is dropped by its own lifecycle, not by a question answer) — they are
  * NOT routed from here any more (they were the removed disposition vocabulary).
  *
  * It is the SIBLING of {@link import('./surface-persist.js').persistSurfacedQuestions}:
@@ -87,7 +87,7 @@ const APPLIED_HEADING = '## Applied answers';
  * resolved (no leftover "these are still open" prose above `## Applied answers`).
  *
  * The strip is STRUCTURAL (marker-pair based), NOT a heading-text regex — the
- * prd's D1 decision: a `## Open questions` heading match would be fragile to
+ * spec's D1 decision: a `## Open questions` heading match would be fragile to
  * author wording (`## Open questions (clear needsAnswers when resolved)` vs.
  * `## Open questions`). Items authored WITHOUT the markers are left untouched
  * (backward compat — no marker ⇒ nothing to strip ⇒ identical bytes).
@@ -102,7 +102,7 @@ export const OPEN_QUESTIONS_MARKER_CLOSE = '<!-- /open-questions -->';
 export interface ApplyAnsweredQuestionsOptions {
 	/** Working clone/worktree the apply commits in. */
 	cwd: string;
-	/** The namespaced item identity (`task:foo` / `prd:bar` / `observation:baz`). */
+	/** The namespaced item identity (`task:foo` / `spec:bar` / `observation:baz`). */
 	item: string;
 	/**
 	 * The item file path RELATIVE to `cwd` (e.g. `work/backlog/foo.md`). The
@@ -274,7 +274,7 @@ function withAppliedAnswers(body: string, entries: SidecarEntry[]): string {
 
 /**
  * Strip ALL marker-fenced open-questions blocks from an item body — the FULL
- * RESOLUTION reconcile step (prd `apply-reconciles-stale-open-questions`,
+ * RESOLUTION reconcile step (spec `apply-reconciles-stale-open-questions`,
  * decisions D1 / D3). Removes each `<!-- open-questions -->` … `<!--
  * /open-questions -->` pair (markers included) plus the blank lines that
  * flanked it, so the answers in `## Applied answers` no longer sit beneath a
@@ -342,11 +342,11 @@ export function applyAnsweredQuestions(
 
 	const {model, path: sidecarPath} = readSidecar(cwd, item);
 
-	// FOLDER-AGNOSTIC at WRITE-TIME (F3a, prd
+	// FOLDER-AGNOSTIC at WRITE-TIME (F3a, spec
 	// `staging-surface-and-apply-promote-safety`): re-resolve the item's CURRENT
 	// path by IDENTITY, mirroring the sidecar's already-folder-agnostic
 	// resolution. The captured `itemPath` is ADVISORY — a concurrent `promote`
-	// (`tasks/backlog → tasks/ready`, `prds/proposed → prds/ready`) may have
+	// (`tasks/backlog → tasks/ready`, `specs/proposed → specs/ready`) may have
 	// moved the item between capture and now, and we MUST write the post-move
 	// path, never the stale one. If the item has vanished entirely, exit CLEAN
 	// (no commit, no ghost file) — the matching benign skip the surface/triage

package/src/buildable-body.ts

@@ -1,7 +1,7 @@
 /**
- * The SINGLE owner of the buildable-task (and PRD-body) markdown SECTION SCHEMA
- * (prd `centralize-buildable-task-renderer-shared-by-intake-and-promotion`, US
- * #1/#4/#7). dorfl has TWO independent producers of a buildable task/PRD body —
+ * The SINGLE owner of the buildable-task (and SPEC-body) markdown SECTION SCHEMA
+ * (spec `centralize-buildable-task-renderer-shared-by-intake-and-promotion`, US
+ * #1/#4/#7). dorfl has TWO independent producers of a buildable task/SPEC body —
  * `intake.ts` (`renderBacklogTask`/`renderSpec`, a wrapper+fallback) and
  * `triage-persist.ts` (`buildPromotedBody`, a structured renderer) — and until
  * this module they each HAND-ROLLED the `## What to build` / `## Acceptance
@@ -28,14 +28,14 @@
  *     mechanism prose, and NO `## Acceptance criteria`. Reproduced by omitting
  *     `acceptanceCriteria` and passing the open-questions block + the seed prose.
  *
- * Symmetrically, {@link renderSpecBody} owns the FULL PRD section schema both PRD
- * producers need: intake's default PRD scaffold is `## Problem Statement` +
+ * Symmetrically, {@link renderSpecBody} owns the FULL SPEC section schema both SPEC
+ * producers need: intake's default SPEC scaffold is `## Problem Statement` +
  * `## Solution` + `## User Stories` (reproduced by passing all three), while
- * promotion's structured PRD body is `## Problem Statement` + optional
+ * promotion's structured SPEC body is `## Problem Statement` + optional
  * `## Open questions` (reproduced by omitting `solution`/`userStories`). Each
  * optional section is emitted only when its input is non-empty.
  *
- * `## Prompt` is TASK-ONLY: a PRD is not dispatched by `do`/`run`, so a PRD body
+ * `## Prompt` is TASK-ONLY: a SPEC is not dispatched by `do`/`run`, so a SPEC body
  * carries none (the symmetric reason the task body MUST carry one — the consumer
  * `extractPromptSection`/`resolveTask` in `prompt.ts` throws "has no '## Prompt'
  * section" at dispatch time without it). {@link renderTaskBody} always emits a
@@ -136,28 +136,28 @@ export interface RenderSpecBodyInput {
 	problemStatement: string;
 	/**
 	 * The `## Solution` prose (markdown). OMIT it (or pass empty) to drop the
-	 * section — promotion's structured PRD body carries no Solution section, intake's
-	 * default PRD scaffold does.
+	 * section — promotion's structured SPEC body carries no Solution section, intake's
+	 * default SPEC scaffold does.
 	 */
 	solution?: string;
 	/**
 	 * The `## User Stories` block (markdown, e.g. a numbered list). OMIT it (or pass
-	 * empty) to drop the section — promotion's structured PRD body carries no User
-	 * Stories section, intake's default PRD scaffold does.
+	 * empty) to drop the section — promotion's structured SPEC body carries no User
+	 * Stories section, intake's default SPEC scaffold does.
 	 */
 	userStories?: string;
 	/**
 	 * The `## Open questions` block (markdown). OMIT it (or pass empty) to drop the
-	 * section. A PRD carries NO `## Prompt` (it is not dispatched).
+	 * section. A SPEC carries NO `## Prompt` (it is not dispatched).
 	 */
 	openQuestions?: string;
 }
 
 /**
- * Render a PRD body (the markdown AFTER the frontmatter fence). Emits, in the
+ * Render a SPEC body (the markdown AFTER the frontmatter fence). Emits, in the
  * canonical order, `## Problem Statement`, then `## Solution`, `## User Stories`,
  * and `## Open questions` (each only when its input is given), and NEVER a
- * `## Prompt` — a PRD is a north-star doc, not a dispatchable task. The symmetric twin of
+ * `## Prompt` — a SPEC is a north-star doc, not a dispatchable task. The symmetric twin of
  * {@link renderTaskBody}, owning the FULL SPEC section schema both producers need
  * (intake's default scaffold supplies Problem Statement + Solution + User Stories;
  * promotion's structured body supplies Problem Statement + optional Open

package/src/claim-cas.ts

@@ -10,7 +10,7 @@ import {workItemRel} from './work-layout.js';
  * `scripts/CLAIM-PROTOCOL.md`. This is the first-class `dorfl claim`
  * command (ADR §9: dorfl is the PRIMARY implementation of the claim
  * protocol; `scripts/claim.sh` is retained as the portable, zero-dependency
- * bootstrap / reference). The lock-substrate cut-over (prd
+ * bootstrap / reference). The lock-substrate cut-over (spec
  * `ledger-status-per-item-lock-refs`) has since diverged it from `claim.sh`'s
  * body-move semantics — see the lock note below — but the exit codes are the same.
  *
@@ -26,7 +26,7 @@ import {workItemRel} from './work-layout.js';
  *   3  (legacy) push contention — no longer reachable: the per-item lock never
  *      falsely contends, so there is no retry budget to exhaust
  *
- * UNIFIED PER-ITEM LOCK (prd `ledger-status-per-item-lock-refs` US #1/#15/#16,
+ * UNIFIED PER-ITEM LOCK (spec `ledger-status-per-item-lock-refs` US #1/#15/#16,
  * ADR `ledger-status-on-per-item-lock-refs`): a claim ACQUIRES the item's
  * per-item lock (`action: implement`) via the lock module and writes NOTHING to
  * `main` — the body STAYS at `work/backlog/<slug>.md`. The claimable predicate is
@@ -86,7 +86,7 @@ export interface ClaimCasOptions {
 	 */
 	override?: boolean;
 	/**
-	 * `--allow-backlog` (prd
+	 * `--allow-backlog` (spec
 	 * `do-allow-backlog-drive-staged-tasks-without-promotion`): WIDEN the claimable
 	 * predicate to ALSO accept a `tasks/backlog/`-resident body (staging), so a
 	 * human can drive a staged task in place WITHOUT promoting it to the pool. The
@@ -336,7 +336,7 @@ async function runClaim(
 		}
 	}
 
-	// UNIFIED PER-ITEM LOCK — the WHOLE of the claim now (prd
+	// UNIFIED PER-ITEM LOCK — the WHOLE of the claim now (spec
 	// `ledger-status-per-item-lock-refs` US #1/#15/#16; ADR
 	// `ledger-status-on-per-item-lock-refs`). The interim dual-write is GONE: claim
 	// acquires the item's per-item lock (`action: implement`) and writes NOTHING to