dorfl 0.1.0 → 0.1.2

package/src/integration-core.ts

@@ -57,8 +57,8 @@ import {isAncestor} from './gc.js';
  * integrates), so verify-then-review holds on the merged tree, never split across
  * two trees. Any failure routes to needs-attention.
  *
- * It is the CORE in the head / core / tail decomposition (prd
- * `work/prds/tasked/run-do-integrate-convergence.md`): the caller-specific HEAD
+ * It is the CORE in the head / core / tail decomposition (spec
+ * `work/specs/tasked/run-do-integrate-convergence.md`): the caller-specific HEAD
  * (repo/arbiter/branch checks, source resolution, the `recovering` flag) and TAIL
  * (switch-to-main / `syncLocalMain` / delete-local-branch / `--no-switch` / the
  * propose next-step block, or — for `run` — the job-record + worktree reap) stay
@@ -98,7 +98,7 @@ export type IntegrationCoreOutcome =
 /**
  * The CORE's input — everything the band needs, nothing caller-shaped. Every
  * divergence between the human `complete` path and the autonomous `do`/`run` path
- * maps to a FIELD VALUE here, not an `if (caller === …)` branch (prd: "zero
+ * maps to a FIELD VALUE here, not an `if (caller === …)` branch (spec: "zero
  * caller-identity leakage"). In-place vs worktree = `cwd`; arbiter name =
  * `arbiter`; human vs autonomous surfacing = `surfaceArbiter`; do's recovery =
  * `source` + `recovering`; per-repo/lang gate = `verify`.
@@ -108,9 +108,9 @@ export type IntegrationCoreOutcome =
  * task-shaped done-move + title source. The shared band
  * (verify→review→commit→rebase→integrate→propose-PR-with-title/body) is
  * IDENTICAL; only the "which item move + which file to read the title from" step
- * is caller-supplied. This is the seam the `do prd:<slug>` TASKING transition
- * rides (task `slice-output-through-integration`): its "item move" is the prd
- * LIFECYCLE move (`work/prds/ready/<slug>.md → work/prds/tasked/<slug>.md`, residence =
+ * is caller-supplied. This is the seam the `do spec:<slug>` TASKING transition
+ * rides (task `slice-output-through-integration`): its "item move" is the spec
+ * LIFECYCLE move (`work/specs/ready/<slug>.md → work/specs/tasked/<slug>.md`, residence =
  * tasked-ness) plus its EMITTED backlog files — NOT a task done-move. Supplying it
  * makes every integrate-time arg (`--propose`/`--merge`, provider, title/body)
  * apply to tasking BY CONSTRUCTION, because they resolve ONCE here.
@@ -127,7 +127,7 @@ export interface IntegrationLifecycle {
 	/**
 	 * Absolute path to the item file whose `title:` frontmatter seeds the default
 	 * commit summary AND the synthesised propose-mode PR title. For the tasking
-	 * transition this is the held prd (`work/prds/ready/<slug>.md`) — read BEFORE
+	 * transition this is the held spec (`work/specs/ready/<slug>.md`) — read BEFORE
 	 * {@link stage} moves it. IGNORED when {@link title} is supplied (the explicit
 	 * title wins — no file read).
 	 */
@@ -137,16 +137,16 @@ export interface IntegrationLifecycle {
 	 * uses THIS as the title source for the default commit summary AND the synthesised
 	 * propose-mode PR title, INSTEAD of reading {@link titlePath}. This is the seam for
 	 * a lifecycle whose output file does NOT yet exist at title-read time — the intake
-	 * lone-task / prd path WRITES `work/backlog/<slug>.md` / `work/prds/ready/<slug>.md` in
+	 * lone-task / spec path WRITES `work/backlog/<slug>.md` / `work/specs/ready/<slug>.md` in
 	 * {@link stage}, which runs AFTER the title read, so a `titlePath` read would race
-	 * the write and fall back to a generic subject. The `do prd:` tasking transition
-	 * leaves this unset (its `titlePath` is an already-existing held prd, read fine).
+	 * the write and fall back to a generic subject. The `do spec:` tasking transition
+	 * leaves this unset (its `titlePath` is an already-existing held spec, read fine).
 	 */
 	title?: string;
 	/**
 	 * STAGE the lifecycle move + emitted files into the index on the current work
 	 * branch (runner-owned git; the agent never does git). For the tasking
-	 * transition: `git mv work/prds/ready/<slug>.md → work/prds/tasked/<slug>.md`
+	 * transition: `git mv work/specs/ready/<slug>.md → work/specs/tasked/<slug>.md`
 	 * (residence = tasked-ness; no marker), and write+`git add` the produced
 	 * `work/backlog/*.md` files. The band's subsequent `git add -A` + atomic commit
 	 * folds this staging
@@ -165,8 +165,8 @@ export interface IntegrationLifecycle {
 
 /**
  * The default LIVENESS CEILING for the merge-mode `${branch}:main` push (the
- * durable promotions `tasks/ready → tasks/done` and, via `lifecycle`, `prds/ready
- * → prds/tasked`). Task `c2-rebase-until-real-on-durable-main-promotions` turned
+ * durable promotions `tasks/ready → tasks/done` and, via `lifecycle`, `specs/ready
+ * → specs/tasked`). Task `c2-rebase-until-real-on-durable-main-promotions` turned
  * the previous SMALL FIXED CAP (was 5, the `run-fleet-claim-integrate-and-sibling-
  * rebase-concurrency-safe` Race-1 budget) into rebase-until-real-conflict: a CLEAN
  * re-rebase no longer counts against a tiny give-up budget — only a GENUINE
@@ -271,7 +271,7 @@ export interface IntegrationCoreInput {
 	 * `work/<type>-<slug>` identity. When omitted, the core derives it from the
 	 * branch HEAD is on (the robust default — the type is encoded IN the name). A
 	 * caller that knows the type explicitly may pass it (e.g. the tasking path
-	 * passes its `work/prds/ready-<slug>`).
+	 * passes its `work/specs/ready-<slug>`).
 	 */
 	branch?: string;
 	/**
@@ -279,7 +279,7 @@ export interface IntegrationCoreInput {
 	 * freshly-built path — since claim no longer moves the body, a freshly-built
 	 * task RESTS in the pool on `main`, task
 	 * `cutover-claim-body-stays-and-complete-sources-from-backlog`),
-	 * `tasks-backlog` (the `--allow-backlog` staged-drive path, prd
+	 * `tasks-backlog` (the `--allow-backlog` staged-drive path, spec
 	 * `do-allow-backlog-drive-staged-tasks-without-promotion`: a human drove a
 	 * STAGED task in place, so the done-move goes `tasks/backlog/ → tasks/done/`
 	 * DIRECTLY — the explicit drive IS the promotion, never bouncing through the
@@ -325,7 +325,7 @@ export interface IntegrationCoreInput {
 	 */
 	recovering: boolean;
 	/**
-	 * **RECOVER an already-committed, already-done-moved STRANDED branch** (prd
+	 * **RECOVER an already-committed, already-done-moved STRANDED branch** (spec
 	 * `ledger-integrity` story 6, the `finish-already-committed-branch` task). When
 	 * `true`, the work is ALREADY committed on the work branch with the task already
 	 * `git mv`'d into `work/done/` (a terminal push failed AFTER steps 2–3, leaving
@@ -564,7 +564,7 @@ export interface IntegrationCoreInput {
 	 * `slice-output-through-integration`). When set, the band reads the title from
 	 * its {@link IntegrationLifecycle.titlePath}, calls its
 	 * {@link IntegrationLifecycle.stage} INSTEAD of the task `git mv → work/done/`,
-	 * and uses the plain rebase ({@link recovering} is irrelevant). The `do prd:`
+	 * and uses the plain rebase ({@link recovering} is irrelevant). The `do spec:`
 	 * TASKING transition supplies it; `do`/`complete`/`run` leave it unset (the
 	 * task done-move is unchanged).
 	 */
@@ -606,8 +606,8 @@ export interface IntegrationCoreResult {
 	 * needs-attention routing can record the findings as the item-body prose. The
 	 * tasking path (task `slice-acceptance-gate`) reads this: the core's build
 	 * `applyNeedsAttentionTransition` is keyed on a TASK lock, so the tasking path
-	 * routes the prd itself via the lock release's needs-attention redirect (amend the
-	 * `prd:<slug>` unified lock `active -> stuck`, no folder move), using THIS
+	 * routes the spec itself via the lock release's needs-attention redirect (amend the
+	 * `spec:<slug>` unified lock `active -> stuck`, no folder move), using THIS
 	 * findings text as the body. Absent on every non-`review-blocked` outcome. (The
 	 * build path ignores it — its routing already records the findings in-body.)
 	 */
@@ -667,7 +667,7 @@ export async function performIntegration(
 	// in the `run` caller, not here.
 	const freshWorktreeGate = input.freshWorktreeGate === true;
 
-	// RECOVER an already-committed, already-done-moved STRANDED branch (prd
+	// RECOVER an already-committed, already-done-moved STRANDED branch (spec
 	// `ledger-integrity` story 6). The work + the done-move are ALREADY committed on
 	// the work branch (a terminal push failed AFTER steps 2–3); SKIP steps 0–3
 	// (prepare / gate / review / done-move / commit) and run ONLY the
@@ -688,7 +688,7 @@ export async function performIntegration(
 			recoveryRebaseSleep: input.recoveryRebaseSleep,
 			recoveryRebaseRandom: input.recoveryRebaseRandom,
 			// Answered-merge land (task `committed-recovery-honours-fresh-worktree-gate`,
-			// prd `land-time-reverify-and-parallel-merge-ceiling`): the apply-rung
+			// spec `land-time-reverify-and-parallel-merge-ceiling`): the apply-rung
 			// dispatches an answered `merge` through this committed-recovery tail (the
 			// branch already carries its done-move commit, so the build path's
 			// `git mv`+`add -A`+commit would raise `IntegrationNothingStaged`). UNLIKE
@@ -713,7 +713,7 @@ export async function performIntegration(
 	}
 
 	// The file whose `title:` seeds the commit summary + PR title. For a TASKING
-	// transition (a non-task `lifecycle`) this is the held prd it supplies; for a
+	// transition (a non-task `lifecycle`) this is the held spec it supplies; for a
 	// build it is the task in its source folder. Read BEFORE any move.
 	const lifecycle = input.lifecycle;
 	// CONTINUE-BUILD (`source: 'done'`, task
@@ -869,7 +869,7 @@ export async function performIntegration(
 		}
 	}
 
-	// 1b. Gate 2 — the PR/code REVIEW gate (GATES prd `work/prds/tasked/review.md`). It is a
+	// 1b. Gate 2 — the PR/code REVIEW gate (GATES spec `work/specs/tasked/review.md`). It is a
 	//     JUDGEMENT gate layered ON TOP of the deterministic `verify` floor (ADR §8)
 	//     — NEVER a replacement, and ALWAYS verify-THEN-review on the SAME tree.
 	//
@@ -924,10 +924,10 @@ export async function performIntegration(
 	// never be the multi-line commit-subject run-on `--fill` would derive.
 	//
 	// When the lifecycle supplies an EXPLICIT `title`, use it DIRECTLY (no file read):
-	// the intake lone-task / prd path writes its output file in `stage()`, which runs
+	// the intake lone-task / spec path writes its output file in `stage()`, which runs
 	// AFTER this point, so a `titlePath` read would race the write and degrade the
-	// subject/PR title to the generic fallback. The `do prd:` tasking path leaves
-	// `title` unset and keeps reading its already-existing held prd (unchanged).
+	// subject/PR title to the generic fallback. The `do spec:` tasking path leaves
+	// `title` unset and keeps reading its already-existing held spec (unchanged).
 	const explicitTitle = lifecycle?.title;
 	const taskTitle =
 		explicitTitle !== undefined ? explicitTitle : readTaskTitle(sourcePath);
@@ -943,7 +943,7 @@ export async function performIntegration(
 
 	// 2. STAGE the item move into the index. For a build that is the task done-move
 	//    (`work/<source>/<slug>.md → work/done/<slug>.md`); for a TASKING
-	//    transition (a non-task `lifecycle`) it is the caller-supplied prd
+	//    transition (a non-task `lifecycle`) it is the caller-supplied spec
 	//    lifecycle move + emitted backlog files (the runner stages them, the agent
 	//    never does git). Either way the subsequent `git add -A` folds the agent's
 	//    uncommitted work + this staging into ONE atomic commit.
@@ -1001,7 +1001,7 @@ export async function performIntegration(
 	// they are TRACKED, not dropped/untracked. Rule B is extended HERE: the runner REPORTS
 	// exactly which note files landed (honest reporting — what actually reached the commit,
 	// read from the staged set, not assumed). This is the ONE shared place — BOTH the build
-	// path (`do <task>`/`run`/`complete`) and the tasking path (`do prd:`, via the
+	// path (`do <task>`/`run`/`complete`) and the tasking path (`do spec:`, via the
 	// `lifecycle` seam) route through it, so the channel is NOT forked. Zero notes ⇒ no
 	// report (the no-note case is byte-for-byte unchanged).
 	await reportScoopedNotes(cwd, env, note);
@@ -1099,7 +1099,7 @@ export async function performIntegration(
 					};
 				}
 			}
-			// PLAIN rebase. After the per-item-lock cut-over (prd
+			// 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: needs-attention is the lock `state: stuck` (not a
 			// `git mv` to `needs-attention/`), the body rests in `backlog/` while
@@ -1580,7 +1580,7 @@ export async function performIntegration(
 }
 
 /**
- * RECOVER an already-committed, already-done-moved STRANDED branch (prd
+ * RECOVER an already-committed, already-done-moved STRANDED branch (spec
  * `ledger-integrity` story 6, the `finish-already-committed-branch` task). The
  * green work AND the `git mv → work/done/` are ALREADY committed on the work
  * branch (a terminal push failed AFTER `performIntegration`'s steps 2–3), and the
@@ -1635,7 +1635,7 @@ async function recoverAlreadyCommitted(params: {
 	/**
 	 * Run the EXISTING `runFreshWorktreeGate` (`prepare` then `verify`) on the
 	 * rebased tip AFTER the rebase loop and BEFORE `applyCompleteTransition`
-	 * (task `committed-recovery-honours-fresh-worktree-gate`, prd
+	 * (task `committed-recovery-honours-fresh-worktree-gate`, spec
 	 * `land-time-reverify-and-parallel-merge-ceiling`). The original stranded-
 	 * recovery caller (`complete --integration`'s already-built strand) leaves
 	 * this UNSET ⇒ no gate, no extra fetch — byte-identical to before. The
@@ -2322,7 +2322,7 @@ async function stagedCaptureNotes(
  * The DURABLE `work/` status folders a slug's ledger file can resting-live in (the
  * one-slug-one-folder set the invariant is asserted over). After the capstone
  * cut-over (task `cutover-retire-slicing-advancing-markers-and-trim-folder-sets`,
- * prd `ledger-status-per-item-lock-refs`) the ONLY `work/` moves on `main` are the
+ * spec `ledger-status-per-item-lock-refs`) the ONLY `work/` moves on `main` are the
  * durable resting transitions, so the source a build completes FROM is `backlog/`
  * (claim no longer moves the body, task
  * `cutover-claim-body-stays-and-complete-sources-from-backlog`) and the canonical
@@ -2337,7 +2337,7 @@ async function stagedCaptureNotes(
  * The folders {@link readArbiterLedgerPlacement} scans for a slug's source on the
  * arbiter: the durable `LEDGER_STATUS_FOLDERS` (`tasks-ready`/`done`/`cancelled`)
  * PLUS `tasks-backlog` (staging). Staging is included ONLY for the arbiter-side
- * source RESOLUTION of a `--allow-backlog` done-move (prd
+ * source RESOLUTION of a `--allow-backlog` done-move (spec
  * `do-allow-backlog-drive-staged-tasks-without-promotion`) and the one-slug-one-
  * folder guard over the malformed "same slug in `tasks/ready/` AND `tasks/backlog/`"
  * state; it is DELIBERATELY NOT added to the shared `LEDGER_STATUS_FOLDERS` (which
@@ -2384,12 +2384,12 @@ interface ArbiterLedgerPlacement {
  * destination is unambiguous), mirroring the manual `279b542` cleanup.
  *
  * It scans {@link ARBITER_PLACEMENT_FOLDERS} — the durable `LEDGER_STATUS_FOLDERS`
- * PLUS `tasks-backlog`, so a `--allow-backlog` staged drive (prd
+ * PLUS `tasks-backlog`, so a `--allow-backlog` staged drive (spec
  * `do-allow-backlog-drive-staged-tasks-without-promotion`) whose done-move sources
  * from `tasks/backlog/` is DISCOVERED here too (the arbiter is the authority for
  * the actual source folder; the local `source` is the fallback). Including staging
  * also makes the one-slug-one-folder guard cover the malformed "same slug in both
- * `tasks/ready/` and `tasks/backlog/`" state (the prd's decision 5): it FAILS LOUD
+ * `tasks/ready/` and `tasks/backlog/`" state (the spec's decision 5): it FAILS LOUD
  * rather than the resolver silently arbitrating a collision the contract forbids.
  */
 function readArbiterLedgerPlacement(

package/src/isolation.ts

@@ -112,10 +112,10 @@ export interface PrepareInput {
 	slug: string;
 	/**
 	 * The item TYPE — `'task'` for a build (intake/`do task:`), `'prd'` for a
-	 * prd-tasking run (`do prd:`). It NAMESPACES the work branch via
-	 * {@link workBranchRef} so a same-slug task and prd never collide on the
+	 * spec-tasking run (`do spec:`). It NAMESPACES the work branch via
+	 * {@link workBranchRef} so a same-slug task and spec never collide on the
 	 * arbiter branch. Defaults to `'task'` (the overwhelmingly-common build
-	 * path); the prd-tasking path passes `'prd'` explicitly.
+	 * path); the spec-tasking path passes `'prd'` explicitly.
 	 */
 	type?: SlugNamespace;
 	/**

package/src/issue-provider.ts

@@ -9,7 +9,7 @@ import {brand} from './brand.js';
 
 /**
  * The single provider-native PROCESSING LOCK label (task `intake-processing-lock`,
- * prd `issue-intake` US #10): a TRANSIENT concurrency mutex — added on start (the
+ * spec `issue-intake` US #10): a TRANSIENT concurrency mutex — added on start (the
  * winner only), removed on finish — that serialises two concurrent `intake` runs on
  * the SAME issue. It is namespaced under the brand (`dorfl:processing`) so it
  * cannot collide with a user's own labels. It carries NO `work/` state — it is NOT a
@@ -19,7 +19,7 @@ import {brand} from './brand.js';
 export const PROCESSING_LOCK_LABEL = `${brand.base}:processing`;
 
 /**
- * The **issue seam** (prd `issue-intake`, task `intake-tracer-slice-outcome`):
+ * The **issue seam** (spec `issue-intake`, task `intake-tracer-slice-outcome`):
  * the provider-pluggable surface `intake <N>` reads an issue + its comment thread
  * through, and posts a clarifying comment back onto. It is the SIBLING of the
  * review-request `ReviewProvider` (`integrator.ts` / `github.ts`): both name a
@@ -33,7 +33,7 @@ export const PROCESSING_LOCK_LABEL = `${brand.base}:processing`;
  * `intake-closes-issue-on-bounce`) is the ATOMIC close used on a BOUNCE — a
  * terminal outcome, so intake closes the issue directly (comment + `not planned`
  * + close in ONE call). It is ALSO the method CI's future close-job uses for the
- * task/prd path; only the BOUNCE close is intake's.
+ * task/spec path; only the BOUNCE close is intake's.
  *
  * The label ops are a TRANSIENT CONCURRENCY MUTEX carrying NO `work/` state — ONE
  * lock label, added-on-start / removed-on-finish. They are NOT a label
@@ -295,7 +295,7 @@ export interface IssueProvider {
 	 * reason IN THE SAME atomic operation (`gh issue close <N> [--comment <body>]
 	 * [--reason "not planned"]`). Used on a BOUNCE (terminal: comment + `not
 	 * planned` + close in ONE call — no post-then-close partial-failure window) and,
-	 * later, by CI's task/prd close-job. The RUNNER calls this; the agent stays
+	 * later, by CI's task/spec close-job. The RUNNER calls this; the agent stays
 	 * seam-free. NEVER throws — a missing/unauthenticated `gh` DEGRADES, surfacing
 	 * the REAL `gh` stderr via {@link CloseIssueResult.reason} (NOT a hard-coded
 	 * guess), so the terminal outcome is unchanged and the cause stays diagnosable.

package/src/item-lock.ts

@@ -4,7 +4,7 @@ import {resolveSidecarIdentity, type SidecarType} from './sidecar.js';
 import {workItemRel} from './work-layout.js';
 
 /**
- * The **unified item-lock module** (prd `ledger-status-per-item-lock-refs`, ADR
+ * The **unified item-lock module** (spec `ledger-status-per-item-lock-refs`, ADR
  * `ledger-status-on-per-item-lock-refs`). The runner's ONE lock primitive: ONE
  * lock per item, on a PER-ITEM hidden ref `refs/dorfl/lock/<entry>`,
  * acquired by an ATOMIC create-only push and released by DELETING the ref, with a
@@ -16,12 +16,12 @@ import {workItemRel} from './work-layout.js';
  * It GENERALISES the green tracer that proved the dangerous core end-to-end on a
  * bare `file://` arbiter (the tracer is now this file). The one production
  * difference from the tracer is the IDENTITY SEAM: callers pass a NAMESPACED item
- * identity (`task:<slug>` / `prd:<slug>` / `observation:<slug>` / `obs:<slug>`,
+ * identity (`task:<slug>` / `spec:<slug>` / `observation:<slug>` / `obs:<slug>`,
  * or a bare `<slug>` = task), and this module derives the type-encoded lock
  * `<entry>` (`<type>-<slug>`) through {@link resolveSidecarIdentity} — the SAME
  * single source of truth the sidecar (`work/questions/<type>-<slug>.md`) and the
  * work branch (`work/<type>-<slug>`) already use. There is deliberately NO second
- * identity scheme: a task, a prd,
+ * identity scheme: a task, a spec,
  * and an observation that share a slug get DISTINCT lock refs, and the SAME item
  * under different actions shares ONE ref (so implement / task / advance on one
  * item are mutually exclusive by construction).
@@ -63,7 +63,7 @@ export const LOCK_REF_PREFIX = 'refs/dorfl/lock';
  * (`<type>-<slug>`) from a NAMESPACED item identity, through the shared
  * {@link resolveSidecarIdentity} resolver (the single source of truth, which the
  * sidecar filename + the advancing-lock marker also key onto). Accepts the same
- * forms as that resolver: `task:<slug>` / `prd:<slug>` / `observation:<slug>` /
+ * forms as that resolver: `task:<slug>` / `spec:<slug>` / `observation:<slug>` /
  * `obs:<slug>`, or a bare `<slug>` (= task). Acquire/release/read ALL key
  * through THIS function, so there is one — and only one — addressing scheme.
  */
@@ -132,7 +132,7 @@ export interface ReleaseResult {
 
 /**
  * Outcome of an AMEND-style transition (mark-stuck / resume / requeue) — the
- * lock-entry STATE MACHINE's interior moves (prd `ledger-status-per-item-lock-refs`,
+ * lock-entry STATE MACHINE's interior moves (spec `ledger-status-per-item-lock-refs`,
  * the C8 lock-entry state machine in the design trail). Each is a single CAS on the
  * held ref (no retry loop), so the verdict is definitive:
  *   - `transitioned` — we won the CAS; the entry now holds the target `(action, state)`.
@@ -269,7 +269,7 @@ async function gitHardInput(
 }
 export interface AcquireOptions {
 	/**
-	 * The NAMESPACED item identity to lock (`task:<slug>` / `prd:<slug>` /
+	 * The NAMESPACED item identity to lock (`task:<slug>` / `spec:<slug>` /
 	 * `observation:<slug>` / `obs:<slug>`, or a bare `<slug>` = task). Resolved to
 	 * the type-encoded lock `<entry>` through {@link lockEntryFor}.
 	 */
@@ -440,7 +440,7 @@ export interface ReleaseHeldResult {
 }
 
 /**
- * GUARDED release for a runner that KNOWS it acquired and HELD the lock (prd
+ * GUARDED release for a runner that KNOWS it acquired and HELD the lock (spec
  * `ledger-status-per-item-lock-refs` US #13): unlike {@link releaseItemLock} —
  * whose `not-held` is a BENIGN idempotent case the complete/tasking/needs-attention
  * callers tolerate (the body may predate the lock, or a crash-recovery may have
@@ -866,15 +866,15 @@ export async function readItemLock(
  * authoritative resting records the cross-substrate reconciliation reads. An
  * item is TERMINAL on `main` iff ANY of these paths exists on `<arbiter>/main`.
  * The won't-proceed terminal is PER-REGIME (the slug-collision correctness fix:
- * a dropped task and a dropped prd sharing a slug used to collide on one
+ * a dropped task and a dropped spec sharing a slug used to collide on one
  * bare-slug `work/dropped/<slug>.md`):
  *   - a TASK: `work/tasks/done/<slug>.md` (completed) OR
  *     `work/tasks/cancelled/<slug>.md` (the task regime's won't-proceed terminal).
- *   - a PRD: `work/prds/tasked/<slug>.md` (tasked) OR `work/prds/dropped/<slug>.md`
- *     (the prd regime's won't-proceed terminal).
+ *   - a SPEC: `work/specs/tasked/<slug>.md` (tasked) OR `work/specs/dropped/<slug>.md`
+ *     (the spec regime's won't-proceed terminal).
  *   - an OBSERVATION: NONE. A note has no durable terminal folder — it leaves by
  *     deletion (its absence, not a terminal record, is the end state). A promoted
- *     observation becomes a NEW task/prd with its own ref.
+ *     observation becomes a NEW task/spec with its own ref.
  */
 export function terminalMainPaths(type: SidecarType, slug: string): string[] {
 	const file = `${slug}.md`;
@@ -895,7 +895,7 @@ export function terminalMainPaths(type: SidecarType, slug: string): string[] {
 }
 
 /** The outcome of a cross-substrate reconciliation of one item's lock against
- * the authoritative `main` durable record (prd `ledger-status-per-item-lock-refs`
+ * the authoritative `main` durable record (spec `ledger-status-per-item-lock-refs`
  * US #9/#10; ADR `ledger-status-on-per-item-lock-refs`). */
 export type ReconcileOutcome =
 	| 'cleared-stale' // `main` is terminal + the lock was `active` (stranded) → cleared
@@ -910,20 +910,20 @@ export interface ReconcileResult {
 	entry: string;
 	ref: string;
 	/** Whether `<arbiter>/main` shows the item terminal (per {@link terminalMainPaths}:
-	 * a task at `tasks/done`/`tasks/cancelled`, a prd at `prds/tasked`/`prds/dropped`). */
+	 * a task at `tasks/done`/`tasks/cancelled`, a spec at `specs/tasked`/`specs/dropped`). */
 	terminalOnMain: boolean;
 	message: string;
 }
 
 /**
  * Reconcile ONE item's per-item lock against the AUTHORITATIVE `main` durable
- * record — the heart of complete's cross-substrate crash-safety (prd
+ * record — the heart of complete's cross-substrate crash-safety (spec
  * `ledger-status-per-item-lock-refs` US #9/#10; ADR
  * `ledger-status-on-per-item-lock-refs`; the design trail's Amendment 6).
  *
  * complete's order is hold lock → land the DURABLE `main` move FIRST → release
  * the lock SECOND. A crash BETWEEN the move and the release leaves a
- * terminal-on-`main` item (a completed/cancelled task or a tasked/dropped prd,
+ * terminal-on-`main` item (a completed/cancelled task or a tasked/dropped spec,
  * per {@link terminalMainPaths}) with a STILL-HELD lock — a stale lock with no
  * in-flight work behind it. This is the recovery that converges it.
  *
@@ -1219,7 +1219,7 @@ export interface LockReportEntry {
 	reconcile: ReconcileOutcome;
 }
 
-/** The `gc --ledger` stuck/orphaned-lock REPORT (prd
+/** The `gc --ledger` stuck/orphaned-lock REPORT (spec
  * `ledger-status-per-item-lock-refs` US #14): every lingering per-item lock on the
  * arbiter, each classified read-only against `main`. An EMPTY list = no locks held
  * (an absent ref namespace reads as `[]`, the recoverable "all locks released"
@@ -1229,7 +1229,7 @@ export interface ItemLockReport {
 }
 
 /**
- * Build the `gc --ledger` stuck/orphaned-lock REPORT (prd
+ * Build the `gc --ledger` stuck/orphaned-lock REPORT (spec
  * `ledger-status-per-item-lock-refs` US #12/#13/#14; ADR
  * `ledger-status-on-per-item-lock-refs`): enumerate every per-item lock currently
  * held on the arbiter ({@link listItemLockEntries} — held active + stuck, with
@@ -1282,7 +1282,7 @@ export async function reportItemLocks(
  */
 /**
  * Does the `gc --ledger` lock report contain a lock that NEEDS HUMAN ATTENTION
- * (prd US#14/#21; ADR `ledger-status-on-per-item-lock-refs`: this surface is the
+ * (spec US#14/#21; ADR `ledger-status-on-per-item-lock-refs`: this surface is the
  * STUCK / crash-orphaned lock, NOT every held one)? TRUE iff some lock is
  * `kept-stuck` (terminal-on-`main` + stuck) or `cleared-stale`-eligible
  * (terminal-on-`main` + a stale active orphan). A `kept-in-flight` (active,
@@ -1391,7 +1391,7 @@ export interface ReapReport {
 }
 
 /**
- * The OPT-IN `gc --ledger --reap-stale-locks` SWEEP (prd
+ * The OPT-IN `gc --ledger --reap-stale-locks` SWEEP (spec
  * `ledger-status-per-item-lock-refs` US #14): a human asserting "clear the dead
  * TERMINAL locks now", so one command sweeps every orphaned terminal lock instead
  * of N hand-run `release-lock`s. It is the WRITE twin of {@link reportItemLocks}
@@ -1631,7 +1631,7 @@ export async function listItemLocks(
 
 /**
  * Read the FULL lock entries currently held on the arbiter — the `status`/`scan`
- * in-flight read path (prd `ledger-status-per-item-lock-refs` US #8; task
+ * in-flight read path (spec `ledger-status-per-item-lock-refs` US #8; task
  * `needs-attention-as-stuck-lock-state`). One fetch of the lock refs, then read
  * each held entry's `lock.md` blob, returning the parsed {@link LockEntry} for
  * every ref (so a caller can surface `active` (in-progress) and `stuck`
@@ -1688,7 +1688,7 @@ export async function listItemLockEntries(
 
 /**
  * List the TASK slugs currently lock-held on the arbiter — the held-slug set the
- * `ready/` pool readers SUBTRACT (prd `ledger-status-per-item-lock-refs` US #15;
+ * `ready/` pool readers SUBTRACT (spec `ledger-status-per-item-lock-refs` US #15;
  * task `claim-acquires-unified-lock-no-body-move`). Enumerates {@link listItemLocks}
  * and keeps only the `task-<slug>` entries (a prd/observation lock does not gate
  * the TASK pool), mapping each to its bare `<slug>`.

package/src/item-path.ts

@@ -25,7 +25,7 @@ import type {WorkFolderKey} from './work-layout.js';
  * (`tasks-backlog`, `prds-proposed`) on purpose: a concurrent `promote` may have
  * just `git mv`'d the item from staging into the pool between an apply's CAPTURE
  * and WRITE, and the apply must resolve to the post-move path — the whole point of
- * folder-agnostic apply (F3a of prd `staging-surface-and-apply-promote-safety`).
+ * folder-agnostic apply (F3a of spec `staging-surface-and-apply-promote-safety`).
  * Terminal-only folders (`cancelled`, `prds-dropped`, `needs-attention`) are NOT
  * here — once an item has reached a terminal, the apply is OVER, and a re-resolve
  * into a terminal would mean the item has effectively vanished from the active
@@ -55,7 +55,7 @@ export const APPLY_LIFECYCLE_FOLDERS: Record<
  * move) — the apply rung then exits CLEAN (no commit, no ghost file), routed as the
  * `vanished` outcome.
  *
- * This is the F3a fix from prd `staging-surface-and-apply-promote-safety`: the
+ * This is the F3a fix from spec `staging-surface-and-apply-promote-safety`: the
  * sidecar is already identity-keyed and folder-agnostic; the item path is now the
  * same. A concurrent `promote` that `git mv`'d the item out from under a captured
  * path can no longer cause a stale-path write.

package/src/ledger-lint.ts

@@ -12,7 +12,7 @@ import {
 } from './work-layout.js';
 
 /**
- * The **one-slug-one-folder LINT** over the `work/` lifecycle ledger (prd
+ * The **one-slug-one-folder LINT** over the `work/` lifecycle ledger (spec
  * `ledger-integrity`, story 3 — the READ-side belt-and-suspenders for defect 1).
  *
  * `work/` IS the ledger: a task's STATUS is the FOLDER its single `.md` lives in
@@ -40,14 +40,14 @@ import {
  * The `work/` STATUS folders a task's ledger file can rest in — the
  * one-slug-one-folder set this lint is asserted over (WORK-CONTRACT.md
  * "status = the folder"). After the capstone cut-over (task
- * `cutover-retire-slicing-advancing-markers-and-trim-folder-sets`, prd
+ * `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 ONLY `work/` moves on `main` are the DURABLE RESTING transitions, so a
  * task's ledger file can rest only in the DURABLE set: the pool `backlog/`, the
  * terminal `done/`, and the task regime's PER-REGIME "won't-proceed" terminal
- * `tasks/cancelled/` (the per-regime split of the previous shared `dropped/`, prd
+ * `tasks/cancelled/` (the per-regime split of the previous shared `dropped/`, spec
  * `folder-taxonomy-reorg-and-rename` US #10; the specific REASON lives in the item
- * BODY as a `reason:` value). The prd regime's terminal `prds/dropped/` is a
+ * BODY as a `reason:` value). The spec regime's terminal `specs/dropped/` is a
  * SEPARATE namespace and is NOT a task-status folder. The transient
  * `in-progress`/`needs-attention`/`tasking`/
  * `advancing` are GONE from `main`'s tree — they are per-item lock-ref state
@@ -58,11 +58,11 @@ import {
  * `cancelled`). A read-side lint surfaces a slug that ends up in `tasks/cancelled/`
  * AND another status folder, so the lint covers all three.
  *
- * The capture buckets (`ideas`/`observations`/`findings`) and the prd-flow folders
- * (`prds/ready`/`prds/tasked`) are NOT task-status folders (WORK-CONTRACT.md: the buckets
- * are "exempt from status = folder"; the prd folders carry prds, a separate
+ * The capture buckets (`ideas`/`observations`/`findings`) and the spec-flow folders
+ * (`specs/ready`/`specs/tasked`) are NOT task-status folders (WORK-CONTRACT.md: the buckets
+ * are "exempt from status = folder"; the spec folders carry prds, a separate
  * namespace) — they are deliberately EXCLUDED so a slug that legitimately has both
- * a task and a same-named note/prd is never a false positive.
+ * a task and a same-named note/spec is never a false positive.
  */
 export {LEDGER_STATUS_FOLDERS, type LedgerStatusFolder} from './work-layout.js';
 
@@ -279,7 +279,7 @@ export interface LedgerSweepResult {
 }
 
 /**
- * The `gc`-STYLE ledger SWEEP (prd story 3's belt-and-suspenders): on demand,
+ * The `gc`-STYLE ledger SWEEP (spec story 3's belt-and-suspenders): on demand,
  * REPORT every slug present in more than one status folder of a LOCAL `work/`
  * ledger, naming the folders and the CANDIDATE canonical folder — and NEVER
  * auto-delete. A human confirms the cleanup (keep the canonical copy, delete the