dorfl 0.1.1 → 0.1.2

package/src/scan.ts

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

package/src/select-order.ts

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

package/src/select-priority.ts

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

package/src/sidecar.ts

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

package/src/slug-namespace.ts

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

package/src/spec-complete.ts

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

package/src/start.ts

@@ -78,7 +78,7 @@ export interface StartOptions {
 	 */
 	override?: boolean;
 	/**
-	 * `--allow-backlog` (prd
+	 * `--allow-backlog` (spec
 	 * `do-allow-backlog-drive-staged-tasks-without-promotion`): recognise a
 	 * `tasks/backlog/`-resident body (staging) as a valid start/onboard residence,
 	 * so the no-checkout `do --remote/--isolated … --allow-backlog` flow (which
@@ -236,7 +236,7 @@ async function runStart(
  *     resume the lock `stuck → active`, onboard).
  * Everything else dispatches by folder unchanged.
  *
- * Under `--allow-backlog` (prd
+ * Under `--allow-backlog` (spec
  * `do-allow-backlog-drive-staged-tasks-without-promotion`) a body resting in
  * `tasks/backlog/` (staging) is treated EXACTLY like the pool for this re-key
  * (held active ⇒ in-progress; held stuck ⇒ needs-attention; else the backlog
@@ -620,7 +620,7 @@ async function switchToWorkBranch(params: {
 }): Promise<SwitchResult> {
 	const {slug, arbiter, cwd, env, note} = params;
 	// `start` is a TASK-only command: the branch is the task-namespaced
-	// `work/task-<slug>` (distinct from a same-slug prd-tasking branch).
+	// `work/task-<slug>` (distinct from a same-slug spec-tasking branch).
 	const branch = workBranchRef('task', slug);
 
 	await gitHard(['fetch', '--quiet', arbiter], cwd, env);
@@ -909,7 +909,7 @@ async function inferSlugFromBranch(
 
 /**
  * Which work/ folder the slug currently lives in on `<arbiter>/main`. Under
- * `--allow-backlog` (prd `do-allow-backlog-drive-staged-tasks-without-promotion`)
+ * `--allow-backlog` (spec `do-allow-backlog-drive-staged-tasks-without-promotion`)
  * it ALSO recognises `tasks/backlog/` (staging) at LOWEST priority — after the
  * pool — so a same-slug pool copy still wins; otherwise staging is invisible.
  */

package/src/status.ts

@@ -81,7 +81,7 @@ export interface JobStatus {
 }
 
 /**
- * One repo's PER-ITEM LOCK refs, surfaced for the dashboard (prd
+ * One repo's PER-ITEM LOCK refs, surfaced for the dashboard (spec
  * `ledger-status-per-item-lock-refs` US #8; task
  * `needs-attention-as-stuck-lock-state`). The in-flight view read from the lock
  * refs — held (`active` = in-progress) and stuck (`needs-attention`) entries +
@@ -111,7 +111,7 @@ export interface StatusReport {
 	/** Stuck (needs-attention), crashed (running-but-dead), or un-reaped (done) jobs. */
 	attention: JobStatus[];
 	/**
-	 * The PER-ITEM LOCK in-flight view (prd `ledger-status-per-item-lock-refs` US
+	 * The PER-ITEM LOCK in-flight view (spec `ledger-status-per-item-lock-refs` US
 	 * #8; task `needs-attention-as-stuck-lock-state`): per registered hub mirror,
 	 * the held lock entries read from the mirror's `refs/dorfl/lock/*` refs —
 	 * `active` holds (in-progress) and `stuck` holds (needs-attention) + reasons.
@@ -124,7 +124,7 @@ export interface StatusReport {
 	 */
 	lockHeld?: RepoLockEntries[];
 	/**
-	 * The one-slug-one-folder LINT (prd `ledger-integrity` story 3): per registered
+	 * The one-slug-one-folder LINT (spec `ledger-integrity` story 3): per registered
 	 * hub mirror, any slug present in MORE THAN ONE `work/` status folder (a corrupt
 	 * ledger). Read from the mirror's bare `main` ref (the SAME `ls-tree` source the
 	 * needs-attention surface uses). Only repos WITH a duplicate appear. `status`
@@ -235,7 +235,7 @@ export async function status(options: StatusOptions): Promise<StatusReport> {
 		// reflects the remote truth. Never fatal — a failed fetch WARNS and falls back
 		// to the mirror's last-known `main`.
 		fetchMirrorMainOrWarn({mirrorPath, warn: options.warn, env: options.env});
-		// The PER-ITEM LOCK in-flight view (prd US #8): read the mirror's lock refs to
+		// The PER-ITEM LOCK in-flight view (spec US #8): read the mirror's lock refs to
 		// surface held (`active` = in-progress) and stuck (`needs-attention`) entries +
 		// reasons/questions. A bare hub mirror's arbiter is its `origin` (the SAME
 		// handle the `scan` held-slug subtraction reads). Best-effort: a fetch/read
@@ -249,7 +249,7 @@ export async function status(options: StatusOptions): Promise<StatusReport> {
 		if (entries.length > 0) {
 			lockHeld.push({repoPath: mirrorPath, entries});
 		}
-		// The one-slug-one-folder LINT (prd story 3): derive any slug residing in >1
+		// The one-slug-one-folder LINT (spec story 3): derive any slug residing in >1
 		// status folder from the SAME freshly-fetched `main` ref, surfaced LOUDLY.
 		const dups = lintRefLedger('main', mirrorPath, options.env);
 		if (dups.length > 0) {
@@ -359,7 +359,7 @@ export function formatStatus(report: StatusReport): string {
 		}
 	}
 
-	// The PER-ITEM LOCK in-flight view (prd US #8; task
+	// The PER-ITEM LOCK in-flight view (spec US #8; task
 	// `cutover-needs-attention-becomes-lock-stuck-recovery-surface`): the held lock
 	// refs read from each mirror — `active` holds (in-progress) and `stuck` holds
 	// (needs-attention) + their reasons/questions. This is the SOLE stuck-state
@@ -377,7 +377,7 @@ export function formatStatus(report: StatusReport): string {
 		}
 	}
 
-	// The one-slug-one-folder LINT (prd `ledger-integrity` story 3): WARN LOUDLY
+	// The one-slug-one-folder LINT (spec `ledger-integrity` story 3): WARN LOUDLY
 	// about every slug residing in >1 status folder of a registered mirror's ledger
 	// (a corrupt ledger — never a silent pass). A human must resolve each.
 	if (dupCount > 0) {

package/src/surface-gate.ts

@@ -6,7 +6,7 @@ import {parseableJsonContractPrompt} from './review-verdict.js';
 import type {NewQuestion} from './sidecar.js';
 
 /**
- * The **SURFACE gate** (prd `advance-loop`, task `advance-rung-surface`,
+ * The **SURFACE gate** (spec `advance-loop`, task `advance-rung-surface`,
  * US #32/33) — the surface-question rung's fresh-context spawn, the DIRECT mirror
  * of the PR/code review gate ({@link import('./review-gate.js')}). On
  * `classify=surface`, the advance engine spawns a FRESH-CONTEXT agent with the
@@ -70,7 +70,7 @@ export interface SurfaceEmit {
 
 /** What the surface gate needs to launch a fresh-context surface of one item. */
 export interface SurfaceGateInput {
-	/** The namespaced identity the surface is for (`task:foo` / `prd:bar` / `observation:baz`). */
+	/** The namespaced identity the surface is for (`task:foo` / `spec:bar` / `observation:baz`). */
 	item: string;
 	/** The working clone/checkout the gate runs in. */
 	cwd: string;

package/src/surface-persist.ts

@@ -13,7 +13,7 @@ import {
 } from './sidecar.js';
 
 /**
- * The engine-owned SURFACE PERSIST (prd `advance-loop`, task
+ * The engine-owned SURFACE PERSIST (spec `advance-loop`, task
  * `advance-rung-surface`, US #15/33) — the half of the surface rung the ENGINE
  * owns (the skill JUDGES, the engine PERSISTS). Given the questions the
  * `surface-questions` skill EMITTED (gathered by `surface-gate.ts`'s spawn), the
@@ -53,7 +53,7 @@ import {
 export interface SurfacePersistOptions {
 	/** Working clone/worktree the persist 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

package/src/tasker-review-loop.ts

@@ -29,9 +29,9 @@ export {parseReviewVerdict as parseTaskReviewVerdict} from './review-verdict.js'
 
 /**
  * **The tasker review→edit→re-review→converge LOOP** (`slicer-review-edit-loop`,
- * GATES prd `work/prds/ready/review.md` RESOLVED DESIGN — Shape 2 / insertion point A).
+ * GATES spec `work/specs/ready/review.md` RESOLVED DESIGN — Shape 2 / insertion point A).
  *
- * On the `do prd:<slug>` tasking path (`tasking.ts`/`performTask`), AFTER the
+ * On the `do spec:<slug>` tasking path (`tasking.ts`/`performTask`), AFTER the
  * agent produces a candidate set of `work/tasks/backlog/<slug>.md` tasks and BEFORE the
  * runner finalises/lands them, this loop RUNS the `review` SKILL
  * (`skills/review/SKILL.md`), APPLIES its findings as EDITS to the candidate task
@@ -47,7 +47,7 @@ export {parseReviewVerdict as parseTaskReviewVerdict} from './review-verdict.js'
  *     N so the loop can never run forever.
  *
  *     ⚠️ ASPIRATION-VS-BUILT (2026-06-10): the "single context" wording above is the
- *     prd's ASPIRATION, NOT what this module does at runtime. The ACTUAL N loop is
+ *     spec's ASPIRATION, NOT what this module does at runtime. The ACTUAL N loop is
  *     RUNNER-DRIVEN and PER-PASS: `runOneExecution` does `for (pass …) { gate(…);
  *     applyEdits(…to disk…) }` — ONE agent LAUNCH per pass, the runner writing the
  *     agent's edits to the candidate task FILES (`work/tasks/backlog/`) between passes, the
@@ -75,7 +75,7 @@ export {parseReviewVerdict as parseTaskReviewVerdict} from './review-verdict.js'
  *   - **a specific uncertain task** → emit it `needsAnswers: true` with the
  *     questions in its body (created, not agent-buildable until a human answers).
  *   - **the whole decomposition unclear / `taskerLoopMax` exhausted with blockers** →
- *     route the prd to `work/needs-attention/<slug>.md` with the questions as the
+ *     route the spec to `work/needs-attention/<slug>.md` with the questions as the
  *     reason, emitting NO guessed tasks.
  *
  * The verdict sink itself (the git transitions for those three outcomes) is the
@@ -101,7 +101,7 @@ export type TaskReviewVerdict = ReviewVerdict;
 
 /** What the review gate needs to launch a fresh-context review+edit pass. */
 export interface TaskReviewGateInput {
-	/** The prd slug whose candidate tasks are under review. */
+	/** The spec slug whose candidate tasks are under review. */
 	slug: string;
 	/** The working clone/checkout the loop runs in (candidate tasks live here). */
 	cwd: string;
@@ -141,7 +141,7 @@ export type LoopOutcome =
 	| 'converged'
 	/** `taskerLoopMax` hit with blockers → specific uncertain task(s) → needsAnswers. */
 	| 'uncertain-tasks'
-	/** `taskerLoopMax` hit / decomposition unclear → route the prd to needs-attention. */
+	/** `taskerLoopMax` hit / decomposition unclear → route the spec to needs-attention. */
 	| 'decomposition-unclear';
 
 /** The result of running the loop — the disposition the caller's sink routes. */
@@ -174,7 +174,7 @@ export interface RunTaskReviewLoopResult {
 }
 
 export interface RunTaskReviewLoopOptions {
-	/** The prd slug whose candidate tasks are being improved. */
+	/** The spec slug whose candidate tasks are being improved. */
 	slug: string;
 	/** The working clone/checkout the loop runs in. */
 	cwd: string;
@@ -226,7 +226,7 @@ export interface RunTaskReviewLoopOptions {
  * to the candidate task files, then re-review — until `verdict === 'approve'` (no
  * NEW blocking issue → converged) or the pass count reaches `taskerLoopMax`. On the cap
  * with a still-`block` verdict, ROUTE per the verdict's channels:
- *   - `decompositionUnclear` set ⇒ `decomposition-unclear` (prd → needs-attention,
+ *   - `decompositionUnclear` set ⇒ `decomposition-unclear` (spec → needs-attention,
  *     no guessed tasks);
  *   - else `uncertainTasks` (or, as a floor, every candidate task) ⇒
  *     `uncertain-tasks` (those tasks emitted `needsAnswers: true` + questions).
@@ -296,7 +296,7 @@ export async function runTaskReviewLoop(
 		note(
 			`Tasker review loop did not converge within taskerLoopMax=${taskerLoopMax} ` +
 				`across ${executions} fresh context(s); the whole decomposition is ` +
-				'unclear — routing the prd to needs-attention (no guessed tasks).',
+				'unclear — routing the spec to needs-attention (no guessed tasks).',
 		);
 		return {
 			outcome: 'decomposition-unclear',
@@ -308,7 +308,7 @@ export async function runTaskReviewLoop(
 			message:
 				`The decomposition of '${options.slug}' is still unclear after ` +
 				`taskerLoopMax=${taskerLoopMax} review pass(es) across ${executions} fresh ` +
-				'context(s); routing the prd to needs-attention with the open ' +
+				'context(s); routing the spec to needs-attention with the open ' +
 				'questions, emitting no guessed tasks.',
 		};
 	}
@@ -617,18 +617,18 @@ export function buildTaskReviewPrompt(input: TaskReviewGateInput): string {
 	const list = input.candidateTasks.map((p) => `  - ${p}`).join('\n');
 	return [
 		`You are a FRESH-CONTEXT reviewer in the TASKER review→edit→converge LOOP`,
-		`(insertion point A). Review the CANDIDATE TASKS just produced for the prd`,
+		`(insertion point A). Review the CANDIDATE TASKS just produced for the spec`,
 		`"${input.slug}":`,
 		list || '  (no candidate tasks found)',
 		``,
 		reviewDisciplinePrompt(),
 		``,
-		`Read the source prd (work/prds/ready/${input.slug}.md) and review the candidate`,
+		`Read the source spec (${workItemRel('specs-ready', `${input.slug}.md`)}) and review the candidate`,
 		`decomposition ADVERSARIALLY. Review the WHOLE SET — graph coherence / gaps /`,
 		`overlap / goal-composition (dependency-graph coherence, set-level gaps,`,
-		`overlapping/duplicated tasks, and "does the set compose into the prd goal")`,
+		`overlapping/duplicated tasks, and "does the set compose into the spec goal")`,
 		`— not just per-task well-formedness. The DESTINATION CHECK ("if every task`,
-		`is built exactly as written, do we end up with the system the prd describes?")`,
+		`is built exactly as written, do we end up with the system the spec describes?")`,
 		`is PART OF this pass and may ITSELF trigger edits — that is why this is a`,
 		`loop, not a one-shot gate.`,
 		``,
@@ -645,7 +645,7 @@ export function buildTaskReviewPrompt(input: TaskReviewGateInput): string {
 		`    can FIX a finding by editing (the natural improver step).`,
 		`  - "uncertainTasks" — specific tasks you cannot make buildable (each gets`,
 		`    \`needsAnswers: true\` with the questions in its body).`,
-		`  - "decompositionUnclear" — the WHOLE decomposition is unsound (the prd is`,
+		`  - "decompositionUnclear" — the WHOLE decomposition is unsound (the spec is`,
 		`    routed to needs-attention; emit no guessed tasks).`,
 		`Do NOT fill "review" / "edit" / "questions" — those are other callers'`,
 		`channels. Flag, do not guess: a flagged question costs one human glance; a`,

package/src/tasking-eligibility.ts

@@ -1,46 +1,46 @@
 /**
  * Pure tasking-eligibility resolution — the auto-task decision layer, one level
- * UP from the build gate (`eligibility.ts`). No I/O: callers pass in the prd's
+ * UP from the build gate (`eligibility.ts`). No I/O: callers pass in the spec's
  * two autonomy axes (`humanOnly`, `needsAnswers`), the repo's `autoTask` policy,
- * the prd's `taskedAfter` slugs, and the set of slugs whose prds are already
- * TASKED (resolved against `work/prds/tasked/` residence, NOT `work/done/`).
+ * the spec's `taskedAfter` slugs, and the set of slugs whose prds are already
+ * TASKED (resolved against `work/specs/tasked/` residence, NOT `work/done/`).
  *
  * This mirrors the build-gate shape deliberately (CONTEXT.md / the `auto-slice`
- * prd): the same `needsAnswers !== true && humanOnly !== true && <repo policy>`
- * predicate, applied to a prd's two axes + the repo's `autoTask` toggle — and a
- * cross-prd ordering check that resolves against tasked-ness rather than done-ness.
+ * spec): the same `needsAnswers !== true && humanOnly !== true && <repo policy>`
+ * predicate, applied to a spec's two axes + the repo's `autoTask` toggle — and a
+ * cross-spec ordering check that resolves against tasked-ness rather than done-ness.
  */
 
 import type {HumanOnlyGate} from './eligibility.js';
 
 export type {HumanOnlyGate};
 
-/** Resolution of a prd's `taskedAfter` against the set of already-tasked prds. */
+/** Resolution of a spec's `taskedAfter` against the set of already-tasked prds. */
 export interface TaskedAfterResult {
-	/** True when every listed prd is already tasked. */
+	/** True when every listed spec is already tasked. */
 	satisfied: boolean;
-	/** Listed prd slugs not yet tasked, in declaration order. */
+	/** Listed spec slugs not yet tasked, in declaration order. */
 	missing: string[];
 }
 
 export interface TaskingEligibilityInput {
-	/** Autonomy axis 1 (DECIDED): a human must drive THIS prd's tasking. */
+	/** Autonomy axis 1 (DECIDED): a human must drive THIS spec's tasking. */
 	humanOnly: HumanOnlyGate;
-	/** Autonomy axis 2 (DISCOVERED): the prd has unresolved questions. */
+	/** Autonomy axis 2 (DISCOVERED): the spec has unresolved questions. */
 	needsAnswers: HumanOnlyGate;
-	/** Cross-prd order: prd slugs that must already be tasked before this one. */
+	/** Cross-spec order: spec slugs that must already be tasked before this one. */
 	taskedAfter: string[];
-	/** Slugs of prds that are already TASKED (residence in `work/prds/tasked/`). */
+	/** Slugs of prds that are already TASKED (residence in `work/specs/tasked/`). */
 	taskedSlugs: Set<string>;
 	/** Per-repo policy: may an agent auto-task *undeclared* prds in this repo? */
 	autoTask: boolean;
 	/**
-	 * The target was named EXPLICITLY by the operator (`do prd:<slug>`), so the
-	 * `autoTask` POLICY is already satisfied — naming the prd IS the authorization,
+	 * The target was named EXPLICITLY by the operator (`do spec:<slug>`), so the
+	 * `autoTask` POLICY is already satisfied — naming the spec IS the authorization,
 	 * exactly as `do <task>` builds a named task regardless of `autoBuild` (the
 	 * `autoBuild` precedent: the pool/scan gates the policy, the explicit claim path
 	 * never re-checks it). When `true`, the policy term drops from the gate and ONLY
-	 * the prd's own readiness axes (`humanOnly`/`needsAnswers`) + `taskedAfter` bind.
+	 * the spec's own readiness axes (`humanOnly`/`needsAnswers`) + `taskedAfter` bind.
 	 * Defaults `false` (the AUTO-PICK pool path, where the `autoTask` policy DOES
 	 * gate). The pool is the single policy-enforcement point; the per-invocation gate
 	 * applies the policy only when NOT explicit.
@@ -49,7 +49,7 @@ export interface TaskingEligibilityInput {
 }
 
 export interface TaskingEligibilityResult {
-	/** Taskable now = gate passes AND every `taskedAfter` prd is already tasked. */
+	/** Taskable now = gate passes AND every `taskedAfter` spec is already tasked. */
 	taskable: boolean;
 	/** Whether the autonomy gate alone passes (agent-taskable on its own axes). */
 	gatePass: boolean;
@@ -61,7 +61,7 @@ export interface TaskingEligibilityResult {
  * `true` AND `humanOnly` is not `true` AND the repo's `autoTask` POLICY is
  * satisfied — where the policy is satisfied either by the repo's `autoTask`
  * toggle being on (the AUTO-PICK pool path) OR by the target being named
- * EXPLICITLY (`explicit: true` — `do prd:<slug>`, where naming IS the
+ * EXPLICITLY (`explicit: true` — `do spec:<slug>`, where naming IS the
  * authorization, mirroring `do <task>` vs `autoBuild`). Both readiness axes
  * block orthogonally and are never agent-taskable regardless of policy; a human
  * is never bound by either. The exact mirror of `resolveGate` (the build gate),
@@ -82,9 +82,9 @@ export function resolveTaskGate(
 }
 
 /**
- * Resolve a prd's `taskedAfter` against the slugs of prds already TASKED (NOT
- * `done/`): satisfied iff every listed prd is present in `taskedSlugs`. An
- * untasked blocker ⇒ not yet taskable (so this prd's emitted tasks can
+ * Resolve a spec's `taskedAfter` against the slugs of prds already TASKED (NOT
+ * `done/`): satisfied iff every listed spec is present in `taskedSlugs`. An
+ * untasked blocker ⇒ not yet taskable (so this spec's emitted tasks can
  * reference the real slugs of those prds' tasks).
  */
 export function resolveTaskedAfter(