dorfl 0.1.1 → 0.1.2

package/src/ledger-read.ts

@@ -72,47 +72,47 @@ export interface LedgerReadyItem {
 }
 
 /**
- * The result of a prd-existence read (ADR §3a): does a prd named `<slug>` exist,
- * and where. A prd lives at `work/prds/ready/<slug>.md`; once TASKED it rests at
- * `work/prds/tasked/<slug>.md` (the tasked resting state, the source of truth for
+ * The result of a spec-existence read (ADR §3a): does a spec named `<slug>` exist,
+ * and where. A spec lives at `work/specs/ready/<slug>.md`; once TASKED it rests at
+ * `work/specs/tasked/<slug>.md` (the tasked resting state, the source of truth for
  * tasked-ness — task `prd-sliced-folder-step-a`). BOTH folders are consulted (any
- * is enough): a prd that is up-for-tasking OR already tasked still occupies its
- * slug, so collision detection must see it. While a prd IS being tasked its body
- * STAYS in `work/prds/ready/` (the tasking lock no longer moves it — task
+ * is enough): a spec that is up-for-tasking OR already tasked still occupies its
+ * slug, so collision detection must see it. While a spec IS being tasked its body
+ * STAYS in `work/specs/ready/` (the tasking lock no longer moves it — task
  * `cutover-retire-slicing-advancing-markers-and-trim-folder-sets`; the transient
  * `tasking/` folder is retired, the in-flight state is the per-item lock ref), so a
- * mid-tasking prd is detected via its `work/prds/ready/` residence. The slug is resolved
+ * mid-tasking spec is detected via its `work/specs/ready/` residence. The slug is resolved
  * from frontmatter `slug:`, falling back to the filename — the SAME shape the task
  * readers use.
  */
 export interface SpecExistence {
 	/**
-	 * Whether a prd named `<slug>` exists in `work/prds/ready/` and/or `work/prds/tasked/`
+	 * Whether a spec named `<slug>` exists in `work/specs/ready/` and/or `work/specs/tasked/`
 	 * (up-for-tasking OR already tasked — either still claims the slug).
 	 */
 	exists: boolean;
-	/** The spec source file, when present (`work/prds/ready/<slug>.md`). */
+	/** The spec source file, when present (`work/specs/ready/<slug>.md`). */
 	specFile: string | undefined;
 	/**
-	 * The tasked resting file, when present (`work/prds/tasked/<slug>.md`) — i.e. the
+	 * The tasked resting file, when present (`work/specs/tasked/<slug>.md`) — i.e. the
 	 * spec HAS BEEN tasked (the source of truth for tasked-ness, task
-	 * `prd-sliced-folder-step-a`). A re-task moves it back `prds/tasked/ -> prds/ready/`.
+	 * `prd-sliced-folder-step-a`). A re-task moves it back `specs/tasked/ -> specs/ready/`.
 	 */
 	specTaskedFile: string | undefined;
 }
 
 /**
- * One prd enumerated for the AUTO-TASK selection pool (ADR §3 — the
- * "tasks-first then specs to task" priority). A prd is NOT in the task
- * scan/candidate model, so the auto-pick pool is built HERE from `work/prds/ready/`
- * through this single shared prd read path (the same path
+ * One spec enumerated for the AUTO-TASK selection pool (ADR §3 — the
+ * "tasks-first then specs to task" priority). A spec is NOT in the task
+ * scan/candidate model, so the auto-pick pool is built HERE from `work/specs/ready/`
+ * through this single shared spec read path (the same path
  * {@link SpecExistence} uses, widened from existence to the gate axes the tasking
  * predicate needs). The tasking-eligibility predicate (`autoslice-gate`'s
  * `resolveTaskingEligibility`) is applied to these by the selection layer; this
  * reader does NOT itself decide eligibility (it just surfaces the inputs).
  */
 export interface LedgerSpecItem {
-	/** Filename within `work/prds/ready/` (e.g. `auto-slice.md`). */
+	/** Filename within `work/specs/ready/` (e.g. `auto-slice.md`). */
 	file: string;
 	/** Resolved slug (frontmatter `slug:`, falling back to the filename). */
 	slug: string;
@@ -120,25 +120,25 @@ export interface LedgerSpecItem {
 	humanOnly: boolean | undefined;
 	/** Autonomy axis 2 (DISCOVERED): `true` (open questions) | `undefined`. */
 	needsAnswers: boolean | undefined;
-	/** Spec-only cross-prd order: prd slugs that must already be TASKED first. */
+	/** Spec-only cross-spec order: spec slugs that must already be TASKED first. */
 	taskedAfter: string[];
 }
 
 /**
- * The prd pool of ONE repo, resolved from `work/prds/ready/` (the auto-task candidate
- * source). Carries every prd's gate axes PLUS the set of already-TASKED slugs so
- * the selection layer can resolve each prd's `taskedAfter` against `work/prds/tasked/`
- * RESIDENCE (task `prd-sliced-folder-step-a` / prd `slicing-coherence` US #9): the
+ * The spec pool of ONE repo, resolved from `work/specs/ready/` (the auto-task candidate
+ * source). Carries every spec's gate axes PLUS the set of already-TASKED slugs so
+ * the selection layer can resolve each spec's `taskedAfter` against `work/specs/tasked/`
+ * RESIDENCE (task `prd-sliced-folder-step-a` / spec `slicing-coherence` US #9): the
  * FOLDER is the source of truth, like `done/` for tasks (the auto-tasker reads
  * folder-residence; the `tasked:` marker was removed in
  * `remove-sliced-marker-step-b`). Built
- * through the SAME prd read path as {@link SpecExistence}; there is no second prd
+ * through the SAME spec read path as {@link SpecExistence}; there is no second spec
  * reader.
  */
 export interface LedgerSpecPool {
-	/** Every prd in `work/prds/ready/`, sorted by slug. */
+	/** Every spec in `work/specs/ready/`, sorted by slug. */
 	specs: LedgerSpecItem[];
-	/** Slugs whose spec resides in `work/prds/tasked/` (resolves `taskedAfter`). */
+	/** Slugs whose spec resides in `work/specs/tasked/` (resolves `taskedAfter`). */
 	taskedSlugs: Set<string>;
 }
 
@@ -201,17 +201,17 @@ export interface ResolveLocalStateInput {
 	repoPath: string;
 }
 
-/** What the prd-existence resolve method needs: which repo + which slug. */
+/** What the spec-existence resolve method needs: which repo + which slug. */
 export interface ResolveSpecExistenceInput {
-	/** The repo root whose `work/prds/ready/`+`work/prds/tasked/` to read. */
+	/** The repo root whose `work/specs/ready/`+`work/specs/tasked/` to read. */
 	repoPath: string;
 	/** The slug to look up (matched against frontmatter `slug:`, then filename). */
 	slug: string;
 }
 
-/** What the prd-pool resolve method needs: which repo's `work/prds/ready/` to enumerate. */
+/** What the spec-pool resolve method needs: which repo's `work/specs/ready/` to enumerate. */
 export interface ResolveSpecPoolInput {
-	/** The repo working-tree root whose `work/prds/ready/` to read. */
+	/** The repo working-tree root whose `work/specs/ready/` to read. */
 	repoPath: string;
 }
 
@@ -233,13 +233,13 @@ export interface ResolveMirrorStateInput {
 }
 
 /**
- * What the MIRROR-ref prd-pool method needs: which bare hub mirror's committed
- * `work/prds/ready/`+`work/prds/tasked/` tree to enumerate.
+ * What the MIRROR-ref spec-pool method needs: which bare hub mirror's committed
+ * `work/specs/ready/`+`work/specs/tasked/` tree to enumerate.
  */
 export interface ResolveMirrorSpecPoolInput {
 	/** The bare hub mirror directory (`<workspacesDir>/repos/<key>.git`). */
 	mirrorPath: string;
-	/** The mirror-LOCAL ref whose `work/prds*` tree to read (default `main`). */
+	/** The mirror-LOCAL ref whose `work/specs*` tree to read (default `main`). */
 	ref?: string;
 	/** Environment for child git processes. */
 	env?: NodeJS.ProcessEnv;
@@ -279,8 +279,8 @@ export interface LedgerReadStrategy {
 	 */
 	resolveMirrorState(input: ResolveMirrorStateInput): Promise<LocalLedgerState>;
 	/**
-	 * Enumerate the repo's prd pool from a BARE hub mirror's committed `work/prds/ready/`
-	 * tree (+ already-TASKED slugs from `work/prds/tasked/` residence) — the
+	 * Enumerate the repo's spec pool from a BARE hub mirror's committed `work/specs/ready/`
+	 * tree (+ already-TASKED slugs from `work/specs/tasked/` residence) — the
 	 * mirror-ref counterpart of {@link LedgerReadStrategy.resolveSpecPool}, for the
 	 * NO-CHECKOUT mirror-side auto-pick (`run`'s isolated loop + the one-shot/CI
 	 * `advance --remote -n`). A mirror is bare, so this reads the committed tree via
@@ -293,36 +293,36 @@ export interface LedgerReadStrategy {
 		input: ResolveMirrorSpecPoolInput,
 	): Promise<LedgerSpecPool>;
 	/**
-	 * Resolve whether a prd named `<slug>` exists in the LOCAL working tree's
-	 * `work/prds/ready/` (the prd source — where a mid-tasking prd ALSO rests now that the
-	 * `tasking/` folder is retired) and/or `work/prds/tasked/` (the tasked resting
+	 * Resolve whether a spec named `<slug>` exists in the LOCAL working tree's
+	 * `work/specs/ready/` (the spec source — where a mid-tasking spec ALSO rests now that the
+	 * `tasking/` folder is retired) and/or `work/specs/tasked/` (the tasked resting
 	 * state). The slug is resolved from each candidate file's frontmatter `slug:`,
 	 * falling back to the filename — the SAME shape the task readers use.
 	 *
-	 * This is the FIRST prd read path in the seam: `ledger-read.ts`/`scan.ts` read
-	 * only `backlog`/`done`, NEVER `work/prds/ready/`. It is added here
-	 * so the §3a slug-namespace resolver, and later the auto-tasking / `do prd:` work,
-	 * share ONE prd read path rather than each growing a bespoke scan. Synchronous
+	 * This is the FIRST spec read path in the seam: `ledger-read.ts`/`scan.ts` read
+	 * only `backlog`/`done`, NEVER `work/specs/ready/`. It is added here
+	 * so the §3a slug-namespace resolver, and later the auto-tasking / `do spec:` work,
+	 * share ONE spec read path rather than each growing a bespoke scan. Synchronous
 	 * and OFFLINE (a working-tree read), like {@link resolveLocalState}.
 	 */
 	resolveSpecExistence(input: ResolveSpecExistenceInput): SpecExistence;
 	/**
-	 * Enumerate the repo's prd pool from `work/prds/ready/` (the auto-task candidate
+	 * Enumerate the repo's spec pool from `work/specs/ready/` (the auto-task candidate
 	 * source for the `do`/`run` "tasks-first then specs to task" priority, ADR
-	 * §3). Returns every prd's gate axes (`humanOnly`/`needsAnswers`/`taskedAfter`)
+	 * §3). Returns every spec's gate axes (`humanOnly`/`needsAnswers`/`taskedAfter`)
 	 * PLUS the set of already-TASKED slugs so the selection layer can resolve
-	 * `taskedAfter` against `work/prds/tasked/` residence (the FOLDER is the source of
+	 * `taskedAfter` against `work/specs/tasked/` residence (the FOLDER is the source of
 	 * truth) and apply `autoslice-gate`'s
-	 * predicate. This is the SAME prd read path {@link resolveSpecExistence} uses,
+	 * predicate. This is the SAME spec read path {@link resolveSpecExistence} uses,
 	 * widened from a single-slug existence check to a full enumeration — NOT a
-	 * second prd reader. Synchronous and OFFLINE (a working-tree read), like
+	 * second spec reader. Synchronous and OFFLINE (a working-tree read), like
 	 * {@link resolveLocalState}.
 	 */
 	resolveSpecPool(input: ResolveSpecPoolInput): LedgerSpecPool;
 	/**
 	 * Enumerate `work/tasks/backlog/*.md` (the TASK STAGING folder) into the SAME
 	 * {@link LedgerReadyItem} shape `resolveLocalState().ready` returns for the pool
-	 * — the SURFACE-on-staging widening (prd
+	 * — the SURFACE-on-staging widening (spec
 	 * `staging-surface-and-apply-promote-safety` F2). Synchronous + OFFLINE
 	 * (working-tree read), like {@link resolveLocalState}. The pool / staging
 	 * folders are distinct durable status folders (one-slug-one-folder — a slug
@@ -333,19 +333,19 @@ export interface LedgerReadStrategy {
 	 */
 	resolveLocalTaskStaging(input: ResolveLocalStateInput): LedgerReadyItem[];
 	/**
-	 * Enumerate `work/prds/proposed/*.md` (the PRD STAGING folder) into the
+	 * Enumerate `work/specs/proposed/*.md` (the SPEC STAGING folder) into the
 	 * SAME {@link LedgerSpecItem} shape `resolveSpecPool().specs` returns for the
-	 * pool — the PRD-symmetric `surfaceStaging` widening (prd
-	 * `staging-surface-and-apply-promote-safety` F2, prd q4 answer). Sync + OFFLINE.
+	 * pool — the SPEC-symmetric `surfaceStaging` widening (spec
+	 * `staging-surface-and-apply-promote-safety` F2, spec q4 answer). Sync + OFFLINE.
 	 */
 	resolveLocalSpecStaging(input: ResolveSpecPoolInput): LedgerSpecItem[];
 	/**
-	 * Enumerate `work/prds/tasked/*.md` (the TASKED resting folder) into the SAME
+	 * Enumerate `work/specs/tasked/*.md` (the TASKED resting folder) into the SAME
 	 * {@link LedgerSpecItem} shape `resolveSpecPool().specs` returns. UNLIKE the pool
-	 * (`prds/ready/`) and staging (`prds/proposed/`) readers, this exists so the
-	 * lifecycle GATHER can surface/apply a `needsAnswers:true` prd that drifted
-	 * AFTER it was tasked and rests IN PLACE in `prds/tasked/` (WORK-CONTRACT
-	 * "A PRD that has drifted AFTER it was TASKED"). Without it, such a prd's
+	 * (`specs/ready/`) and staging (`specs/proposed/`) readers, this exists so the
+	 * lifecycle GATHER can surface/apply a `needsAnswers:true` spec that drifted
+	 * AFTER it was tasked and rests IN PLACE in `specs/tasked/` (WORK-CONTRACT
+	 * "A SPEC that has drifted AFTER it was TASKED"). Without it, such a spec's
 	 * ANSWERED sidecar is enumerated by no pool and the human's answer is STRANDED
 	 * (observation `tasked-prd-needsanswers-sidecar-stranded-no-apply-pool`).
 	 * `resolveSpecPool` deliberately returns tasked specs only as `taskedSlugs`
@@ -363,15 +363,15 @@ export interface LedgerReadStrategy {
 	): Promise<LedgerReadyItem[]>;
 	/**
 	 * Mirror-ref counterpart of {@link resolveLocalSpecStaging}: read
-	 * `<ref>:work/prds/proposed/*.md` from a bare mirror.
+	 * `<ref>:work/specs/proposed/*.md` from a bare mirror.
 	 */
 	resolveMirrorSpecStaging(
 		input: ResolveMirrorSpecPoolInput,
 	): Promise<LedgerSpecItem[]>;
 	/**
 	 * Mirror-ref counterpart of {@link resolveLocalSpecTasked}: read
-	 * `<ref>:work/prds/tasked/*.md` from a bare mirror, so a `needsAnswers` tasked
-	 * prd's answered sidecar is never stranded on the mirror-side advance path
+	 * `<ref>:work/specs/tasked/*.md` from a bare mirror, so a `needsAnswers` tasked
+	 * spec's answered sidecar is never stranded on the mirror-side advance path
 	 * either.
 	 */
 	resolveMirrorSpecTasked(
@@ -430,7 +430,7 @@ function readLocalReady(repoPath: string): LedgerReadyItem[] {
 }
 
 /**
- * Read `work/tasks/backlog/*.md` (the TASK STAGING folder, prd
+ * Read `work/tasks/backlog/*.md` (the TASK STAGING folder, spec
  * `staging-surface-and-apply-promote-safety` F2) from the local tree. Same
  * {@link LedgerReadyItem} shape as the pool reader — the SURFACE-on-staging
  * widening only enumerates items; it does NOT promote them.
@@ -440,8 +440,8 @@ function readLocalTaskStaging(repoPath: string): LedgerReadyItem[] {
 }
 
 /**
- * Read `work/prds/proposed/*.md` (the PRD STAGING folder, the prd twin
- * of {@link readLocalTaskStaging}, prd q4 answer) from the local tree. Returns
+ * Read `work/specs/proposed/*.md` (the SPEC STAGING folder, the spec twin
+ * of {@link readLocalTaskStaging}, spec q4 answer) from the local tree. Returns
  * the SAME {@link LedgerSpecItem} shape `resolveSpecPool().specs` returns.
  */
 function readLocalSpecStaging(repoPath: string): LedgerSpecItem[] {
@@ -449,16 +449,16 @@ function readLocalSpecStaging(repoPath: string): LedgerSpecItem[] {
 }
 
 /**
- * Read `work/prds/tasked/*.md` (the TASKED resting folder) into the SAME
+ * Read `work/specs/tasked/*.md` (the TASKED resting folder) into the SAME
  * {@link LedgerSpecItem} shape. Used by the lifecycle gather to surface/apply a
- * `needsAnswers` prd that drifted after tasking and rests in place in
- * `prds/tasked/` — so its answered sidecar is never stranded.
+ * `needsAnswers` spec that drifted after tasking and rests in place in
+ * `specs/tasked/` — so its answered sidecar is never stranded.
  */
 function readLocalSpecTasked(repoPath: string): LedgerSpecItem[] {
 	return readLocalSpecFolder(repoPath, 'specs-tasked');
 }
 
-/** Shared body for the local prd-FOLDER readers (proposed/tasked) — same item shape. */
+/** Shared body for the local spec-FOLDER readers (proposed/tasked) — same item shape. */
 function readLocalSpecFolder(
 	repoPath: string,
 	folder: 'specs-proposed' | 'specs-tasked',
@@ -518,9 +518,9 @@ function readLocalObservations(repoPath: string): LedgerObservationItem[] {
 }
 
 /**
- * Does a prd named `slug` exist in `<repoPath>/work/<folder>/`? A prd source file
- * is `work/prds/ready/*.md` (where a mid-tasking prd also rests — the `tasking/` folder is
- * retired); a tasked prd rests at `work/prds/tasked/*.md` (the source of truth for
+ * Does a spec named `slug` exist in `<repoPath>/work/<folder>/`? A spec source file
+ * is `work/specs/ready/*.md` (where a mid-tasking spec also rests — the `tasking/` folder is
+ * retired); a tasked spec rests at `work/specs/tasked/*.md` (the source of truth for
  * tasked-ness). We match the slug against each file's
  * frontmatter `slug:` (falling back to the filename) — the SAME shape the task
  * readers use — so a renamed file whose frontmatter slug matches still resolves.
@@ -541,15 +541,15 @@ function findSpecFileBySlug(
 }
 
 /**
- * Enumerate `work/prds/ready/*.md` into the auto-task prd pool (the tasks-first/prd
- * priority's prd source) — the SAME prd read path {@link findSpecFileBySlug} uses,
- * widened from a single-slug existence check to a full enumeration. Each prd's
+ * Enumerate `work/specs/ready/*.md` into the auto-task spec pool (the tasks-first/spec
+ * priority's spec source) — the SAME spec read path {@link findSpecFileBySlug} uses,
+ * widened from a single-slug existence check to a full enumeration. Each spec's
  * slug is resolved from frontmatter `slug:` (falling back to the filename) and
  * its gate axes (`humanOnly`/`needsAnswers`/`taskedAfter`) parsed. The
- * already-TASKED set is RESIDENCE in `work/prds/tasked/` (task
- * `prd-sliced-folder-step-a` / prd `slicing-coherence` US #9): the FOLDER is the
+ * already-TASKED set is RESIDENCE in `work/specs/tasked/` (task
+ * `prd-sliced-folder-step-a` / spec `slicing-coherence` US #9): the FOLDER is the
  * source of truth (the build-machine `done/` analogue), so `taskedAfter` resolves
- * against `prds/tasked/` residence (mirroring `blockedBy` -> `done/`). The `tasked:`
+ * against `specs/tasked/` residence (mirroring `blockedBy` -> `done/`). The `tasked:`
  * frontmatter marker was removed entirely in `remove-sliced-marker-step-b`. This
  * matches `tasking.ts`'s `readTaskedSlugs`. Missing folders read as empty.
  */
@@ -569,7 +569,7 @@ function readLocalSpecPool(repoPath: string): LocalSpecPool {
 	}
 	specs.sort((a, b) => a.slug.localeCompare(b.slug));
 
-	// Tasked-ness is RESIDENCE in `work/prds/tasked/` — the FOLDER is the source of
+	// Tasked-ness is RESIDENCE in `work/specs/tasked/` — the FOLDER is the source of
 	// truth, like `done/` for tasks (the `tasked:` marker was removed in
 	// `remove-sliced-marker-step-b`), mirroring tasking.ts's readTaskedSlugs. Missing
 	// folder reads as empty.
@@ -731,7 +731,7 @@ async function readTaskStagingFromTree(
 	return readTaskFolderFromTree('tasks-backlog', ref, cwd, env);
 }
 
-/** Parse `<ref>:work/prds/proposed/*.md` (PRD STAGING) into prd items, sorted by slug. */
+/** Parse `<ref>:work/specs/proposed/*.md` (SPEC STAGING) into spec items, sorted by slug. */
 async function readSpecStagingFromTree(
 	ref: string,
 	cwd: string,
@@ -740,7 +740,7 @@ async function readSpecStagingFromTree(
 	return readSpecFolderFromTree('specs-proposed', ref, cwd, env);
 }
 
-/** Parse `<ref>:work/prds/tasked/*.md` (TASKED resting) into prd items, sorted by slug. */
+/** Parse `<ref>:work/specs/tasked/*.md` (TASKED resting) into spec items, sorted by slug. */
 async function readSpecTaskedFromTree(
 	ref: string,
 	cwd: string,
@@ -749,7 +749,7 @@ async function readSpecTaskedFromTree(
 	return readSpecFolderFromTree('specs-tasked', ref, cwd, env);
 }
 
-/** Shared body for the mirror-ref prd-FOLDER readers (proposed/tasked) — same item shape. */
+/** Shared body for the mirror-ref spec-FOLDER readers (proposed/tasked) — same item shape. */
 async function readSpecFolderFromTree(
 	folder: 'specs-proposed' | 'specs-tasked',
 	ref: string,
@@ -776,8 +776,8 @@ async function readSpecFolderFromTree(
 }
 
 /**
- * Parse `<ref>:work/prds/ready/*.md` into the auto-task prd pool, sorted by slug, plus
- * the already-TASKED slugs from `<ref>:work/prds/tasked/` RESIDENCE (the folder is
+ * Parse `<ref>:work/specs/ready/*.md` into the auto-task spec pool, sorted by slug, plus
+ * the already-TASKED slugs from `<ref>:work/specs/tasked/` RESIDENCE (the folder is
  * the source of truth, mirroring the working-tree {@link readLocalSpecPool}). Reads
  * a committed tree (bare-mirror or any ref) via `ls-tree`/`show`. Missing folders
  * read as empty.
@@ -805,7 +805,7 @@ async function readSpecPoolFromTree(
 	}
 	specs.sort((a, b) => a.slug.localeCompare(b.slug));
 
-	// Tasked-ness is RESIDENCE in `work/prds/tasked/` — the FOLDER is the source of
+	// Tasked-ness is RESIDENCE in `work/specs/tasked/` — the FOLDER is the source of
 	// truth (the `tasked:` marker was removed in `remove-sliced-marker-step-b`),
 	// exactly as the working-tree reader resolves it.
 	const taskedBase = `${ref}:${workFolderRel('specs-tasked')}`;
@@ -910,7 +910,7 @@ export const currentLedgerRead: LedgerReadStrategy = {
 		return {ready, doneSlugs, observations};
 	},
 	async resolveMirrorSpecPool({mirrorPath, ref = 'main', env}) {
-		// The prd pool from the bare mirror's committed `<ref>:work/prds*` tree — the
+		// The spec pool from the bare mirror's committed `<ref>:work/specs*` tree — the
 		// mirror-ref counterpart of `resolveSpecPool` (a working-tree read). Same shape,
 		// so `taskableSpecs` applies identically to either source.
 		return readSpecPoolFromTree(ref, mirrorPath, env);

package/src/ledger-write.ts

@@ -89,7 +89,7 @@ export type LedgerTransitionKind =
 	| 'tasking'
 	| 'advancing'
 	/**
-	 * The **promote** transition (prd `staging-pool-position-gate-and-trust-model`,
+	 * The **promote** transition (spec `staging-pool-position-gate-and-trust-model`,
 	 * task `pre-backlog-staging-folder-and-promote-step-a`): move a STAGED task
 	 * `work/pre-backlog/<slug>.md → work/backlog/<slug>.md` to enter the
 	 * agent-eligible pool. A durable `main` move, the same category as `requeue`
@@ -174,7 +174,7 @@ export type ApplyNeedsAttentionTransitionInput = RouteToNeedsAttentionOptions;
  * move result the folder-native mechanism produces. The RECOVERABLE branch push
  * outcome rides on `branchPush` (the caller reads it rather than assuming
  * "pushed" off the local move). The OBSERVABLE half is now the per-item lock
- * `state: stuck` amend (prd `ledger-status-per-item-lock-refs`); there is no
+ * `state: stuck` amend (spec `ledger-status-per-item-lock-refs`); there is no
  * separate on-`main` surface outcome to report.
  */
 export type ApplyNeedsAttentionTransitionResult = RouteToNeedsAttentionResult;
@@ -773,7 +773,7 @@ export const currentLedgerWrite: LedgerWriteStrategy = {
  * The SOLE stuck-state RECORD: amend the item's HELD per-item lock
  * `active → stuck` + the FULL reason prose + any agent-surfaced questions, via the
  * state machine's mark-stuck CAS amend ({@link markStuckItemLock}) — task
- * `cutover-needs-attention-becomes-lock-stuck-recovery-surface` (decision i+; prd
+ * `cutover-needs-attention-becomes-lock-stuck-recovery-surface` (decision i+; spec
  * `ledger-status-per-item-lock-refs` US #5/#8; ADR
  * `ledger-status-on-per-item-lock-refs`). This REPLACES the `git mv →
  * needs-attention/` folder bounce + its on-`main` surface + branch push: the

package/src/lifecycle-gather.ts

@@ -65,8 +65,8 @@ function readSidecarInPlace(
 }
 
 /**
- * Collect every `needsAnswers:true` task (from `work/backlog`) + prd (from
- * `work/prds`) for the in-place repo, through the read seam (the SAME readers the
+ * Collect every `needsAnswers:true` task (from `work/backlog`) + spec (from
+ * `work/specs`) for the in-place repo, through the read seam (the SAME readers the
  * build-pool scan uses). These are the SURFACE/APPLY candidates this task draws
  * into the selection (today they are build/task-INELIGIBLE, so nothing else
  * surfaces them).
@@ -89,25 +89,25 @@ function blockedItemsInPlace(
 			out.push({namespace: 'spec', slug: spec.slug});
 		}
 	}
-	// TASKED resting prds (`prds/tasked/`) — enumerated UNCONDITIONALLY (NOT behind
-	// `surfaceStaging`), because a prd may legitimately carry `needsAnswers:true`
-	// while resting in `prds/tasked/` (WORK-CONTRACT "A PRD that has drifted AFTER
-	// it was TASKED"). This is NOT a staging widening: a tasked prd is a durable
+	// TASKED resting prds (`specs/tasked/`) — enumerated UNCONDITIONALLY (NOT behind
+	// `surfaceStaging`), because a spec may legitimately carry `needsAnswers:true`
+	// while resting in `specs/tasked/` (WORK-CONTRACT "A SPEC that has drifted AFTER
+	// it was TASKED"). This is NOT a staging widening: a tasked spec is a durable
 	// resting state, like the pool, so it is enumerated like the pool. Routing
 	// still respects the gates in `buildLifecyclePools` (an ANSWERED sidecar -> the
 	// always-on APPLY pool so the human's answer is never STRANDED; a NO-sidecar
-	// tasked prd -> SURFACE, still gated by `surfaceBlockers`). Without this, a
-	// tasked prd's answered sidecar is enumerated by no pool and apply never runs
+	// tasked spec -> SURFACE, still gated by `surfaceBlockers`). Without this, a
+	// tasked spec's answered sidecar is enumerated by no pool and apply never runs
 	// on it (observation `tasked-prd-needsanswers-sidecar-stranded-no-apply-pool`).
 	for (const spec of read.resolveLocalSpecTasked({repoPath})) {
 		if (spec.needsAnswers === true) {
 			out.push({namespace: 'spec', slug: spec.slug});
 		}
 	}
-	// SURFACE-on-STAGING widening (prd
+	// SURFACE-on-STAGING widening (spec
 	// `staging-surface-and-apply-promote-safety` F2): when `surfaceStaging` is
 	// ON, the candidate set ADDITIONALLY enumerates `needsAnswers` items resting
-	// in STAGING (`tasks/backlog/` + `prds/proposed/`), so a tasked item
+	// in STAGING (`tasks/backlog/` + `specs/proposed/`), so a tasked item
 	// surfaces its questions BEFORE the human promotes it. BUILD/claim still
 	// reads POOL-only (`scoreItems` over `state.ready`); only the surface polarity
 	// widens here.
@@ -195,7 +195,7 @@ async function readSidecarMirror(
  * Gather + build the lifecycle pools for a MIRROR-SIDE bare hub mirror (async).
  * Reads the SAME logical inputs as {@link gatherLifecycleInPlace} \u2014 observations +
  * the `needsAnswers` pool from the mirror's committed `main` (via
- * `resolveMirrorState`), the prd pool via `resolveMirrorSpecPool`, and each item's
+ * `resolveMirrorState`), the spec pool via `resolveMirrorSpecPool`, and each item's
  * sidecar via `git show` \u2014 then hands them to the SAME shared
  * {@link buildLifecyclePools}, so the in-place + mirror enumerations AGREE.
  */
@@ -232,9 +232,9 @@ export async function gatherLifecycleMirror(input: {
 			blocked.push({namespace: 'spec', slug: spec.slug});
 		}
 	}
-	// TASKED resting prds (`<ref>:work/prds/tasked/`) — enumerated UNCONDITIONALLY,
-	// the mirror-side counterpart of the in-place tasked-prd enumeration above
-	// (so a `needsAnswers` tasked prd's answered sidecar is never stranded on the
+	// TASKED resting prds (`<ref>:work/specs/tasked/`) — enumerated UNCONDITIONALLY,
+	// the mirror-side counterpart of the in-place tasked-spec enumeration above
+	// (so a `needsAnswers` tasked spec's answered sidecar is never stranded on the
 	// mirror/CI advance path either). Routing still respects the gates.
 	const specTasked = await read.resolveMirrorSpecTasked({mirrorPath, ref, env});
 	for (const spec of specTasked) {
@@ -242,10 +242,10 @@ export async function gatherLifecycleMirror(input: {
 			blocked.push({namespace: 'spec', slug: spec.slug});
 		}
 	}
-	// SURFACE-on-STAGING widening (prd
+	// SURFACE-on-STAGING widening (spec
 	// `staging-surface-and-apply-promote-safety` F2): mirror-side counterpart of
 	// the in-place widening above — enumerate `needsAnswers` items in
-	// STAGING (`tasks/backlog/` + `prds/proposed/`) from the bare mirror's
+	// STAGING (`tasks/backlog/` + `specs/proposed/`) from the bare mirror's
 	// committed `<ref>` tree, so the in-place + mirror surfaces AGREE. The
 	// staging reads are skipped entirely when the gate is OFF (no extra git
 	// ls-tree work in the legacy mode).

package/src/lifecycle-pools.ts

@@ -70,7 +70,7 @@ export interface LifecyclePoolGates {
 	surface?: boolean;
 	/**
 	 * Does the SURFACE candidate set widen to include STAGING (`tasks/backlog/` +
-	 * `prds/proposed/`), or stay POOL-ONLY? This field is CONSUMED BY THE
+	 * `specs/proposed/`), or stay POOL-ONLY? This field is CONSUMED BY THE
 	 * GATHER (`lifecycle-gather.ts`), NOT by {@link buildLifecyclePools} — the
 	 * builder is pure and only routes already-resolved candidates between surface
 	 * / apply by sidecar-answered-state. The gather decides WHICH items become
@@ -112,7 +112,7 @@ export interface NeedsAnswersCandidate {
  * to the always-on APPLY pool (a CONSUME act — the human's answer is never
  * stranded), while a NO/PENDING sidecar UNTRIAGED observation stays a TRIAGE
  * candidate (gated) as today. PURE: the caller resolves the active sidecar (via
- * {@link sidecarPathFor} — the SAME resolver the task/prd `needsAnswers`
+ * {@link sidecarPathFor} — the SAME resolver the task/spec `needsAnswers`
  * candidates use); this unit only routes.
  */
 export interface ObservationCandidate {
@@ -142,7 +142,7 @@ export interface LifecyclePoolsInput {
 	 */
 	observations: ObservationCandidate[];
 	/**
-	 * Every `needsAnswers:true` task/prd (the create-side blocked items), each
+	 * Every `needsAnswers:true` task/spec (the create-side blocked items), each
 	 * with its resolved active sidecar. This unit routes each to SURFACE or APPLY.
 	 */
 	needsAnswers: NeedsAnswersCandidate[];
@@ -172,7 +172,7 @@ export interface LifecyclePools {
  * Build the three lifecycle sub-pools from the raw candidates + the gates, PURE.
  * Each selected item carries the lifecycle `namespace` discriminator so the
  * driver's per-item dispatch can map it to the right TICK arg (observation \u2192
- * `obs:<slug>`; a blocked task/prd \u2192 `task:`/`prd:<slug>`, which the tick then
+ * `obs:<slug>`; a blocked task/spec \u2192 `task:`/`spec:<slug>`, which the tick then
  * classifies into surface/apply/no-op). This unit decides WHICH sub-pool each item
  * belongs to (and whether its gate lets it through); the TICK re-classifies and
  * runs the actual rung (the classifier + rung bodies are unchanged).

package/src/merge-question-surfacer.ts

@@ -16,7 +16,7 @@ import {
 import {workItemRel, type WorkFolderKey} from './work-layout.js';
 
 /**
- * The **MERGE-QUESTION SURFACER** (prd `land-time-reverify-and-parallel-merge-ceiling`,
+ * The **MERGE-QUESTION SURFACER** (spec `land-time-reverify-and-parallel-merge-ceiling`,
  * task `merge-question-surfacer`, US #14) — the SECOND, STATE-sourced surfacer
  * in the advance loop. It is a clean SIBLING to the existing
  * `surface-questions` JUDGEMENT surfacer (`surface-gate.ts` +
@@ -41,7 +41,7 @@ import {workItemRel, type WorkFolderKey} from './work-layout.js';
  * layered on top when a GitHub host is configured; the surfacer functions
  * identically without it.
  *
- * OUT OF SCOPE for this task (covered by sibling tasks of the same prd):
+ * OUT OF SCOPE for this task (covered by sibling tasks of the same spec):
  *
  *   - The APPLY rung dispatch that lands an answered `kind: merge` through the
  *     land primitive (rebase → re-verify → advance). Task
@@ -185,7 +185,7 @@ const TASK_FOLDERS: readonly WorkFolderKey[] = [
  * Idempotency: a branch whose sidecar ALREADY carries a PENDING `kind: merge`
  * entry is SKIPPED (with `already-pending-merge-question`). A branch with no
  * item body on `main` is SKIPPED (with `no-item-body`) — the cross-cutting
- * branch-keyed sidecar identity (PRD sidecar Q5-i) is OOS for this task; an
+ * branch-keyed sidecar identity (SPEC sidecar Q5-i) is OOS for this task; an
  * unmerged-branch-with-no-body lands on the same skip path until that
  * generalisation arrives.
  */
@@ -248,7 +248,7 @@ export function surfaceMergeQuestions(
 
 		const itemPath = findTaskItemPath(cwd, branch.slug);
 		if (itemPath === undefined) {
-			// The `branch:`/`ref:`-keyed sidecar identity (PRD sidecar Q5-i, the
+			// The `branch:`/`ref:`-keyed sidecar identity (SPEC sidecar Q5-i, the
 			// cross-cutting open question SHARED with the stuck-lock surfacer) is
 			// OUT OF SCOPE for this task — without a body to flip `needsAnswers`
 			// on, persist would tear the invariant. Skip with the reason so the

package/src/mint-adr.ts

@@ -9,7 +9,7 @@ import {
 import {resolveSidecarIdentity, sidecarPathFor} from './sidecar.js';
 
 /**
- * The **ADR-MINT route** (prd
+ * The **ADR-MINT route** (spec
  * `agentic-question-resolution-retire-disposition-vocabulary` US #2, task
  * `agentic-apply-mint-adr-route`) — the SIBLING of {@link
  * import('./triage-persist.js').promoteObservation}, for the agentic apply
@@ -17,8 +17,8 @@ import {resolveSidecarIdentity, sidecarPathFor} from './sidecar.js';
  *
  * Why a SIBLING and not an `adr` artifact type on `promoteObservation`
  * (recorded `## Decisions`): `promoteObservation` is `work/`-folder-SHAPED — it
- * targets `work/tasks/ready` / `work/prds/proposed` via `workItemRel`, and builds
- * a task/prd body (a `## What to build` / `## Problem Statement` lead + an
+ * targets `work/tasks/ready` / `work/specs/proposed` via `workItemRel`, and builds
+ * a task/spec body (a `## What to build` / `## Problem Statement` lead + an
  * `## Open questions` block, with `needsAnswers` carried). An ADR is DIFFERENT in
  * EVERY one of those: it lives in `docs/adr/` (OUTSIDE the work board, so the
  * `work/`-layout path builder does not fit), it carries NO `needsAnswers`/open-
@@ -331,7 +331,7 @@ function renderAdrFile(slug: string, title: string, body: string): string {
  * The observation's mechanism PROSE: everything before its first
  * `## Open questions` heading, with the frontmatter fence dropped. An ADR records
  * a SETTLED decision, so an observation's open-questions scoping is deliberately
- * NOT carried into the ADR body (unlike a promoted task/prd, which keeps the
+ * NOT carried into the ADR body (unlike a promoted task/spec, which keeps the
  * open questions live) — the answered question(s) ARE the decision.
  */
 function mechanismOf(observation: string): string {

package/src/mirror-pool-scan.ts

@@ -24,7 +24,7 @@ import {heldTaskSlugs} from './item-lock.js';
  * SAME two pools (eligible TASKS + taskable PRDS) but reads a BARE hub mirror's
  * committed `main` ref (`git ls-tree`/`git show`), NOT a working checkout.
  *
- * This is the ONE reusable enumeration unit the prd's FOLD-IN note demands: BOTH
+ * This is the ONE reusable enumeration unit the spec's FOLD-IN note demands: BOTH
  * the `run` loop driver's isolated+parallel auto-pick AND the one-shot/CI
  * `advance --remote -n` / the CI matrix consume it, so the `-n`/auto-pick rungs
  * (both `do` and `advance`, both `run`-loop and one-shot) all call the SAME scan.
@@ -44,7 +44,7 @@ import {heldTaskSlugs} from './item-lock.js';
  *     `scanRepoPaths`/registry `scan` use) over the mirror's `work/backlog` +
  *     `work/done` read via {@link LedgerReadStrategy.resolveMirrorState}.
  *   - **taskable prds** — {@link taskableSpecs} (`autoslice-gate`'s predicate)
- *     over the mirror's `work/prds/ready` + `work/prds/tasked` read via the mirror-ref
+ *     over the mirror's `work/specs/ready` + `work/specs/tasked` read via the mirror-ref
  *     {@link LedgerReadStrategy.resolveMirrorSpecPool}.
  *
  * Per-repo policy parity: a bare mirror has no checked-out `.dorfl.json`,
@@ -170,7 +170,7 @@ export async function scanMirrorPool(
 	// scored through the EXACT same `scoreItems` the in-place/registry scans use.
 	const state = await read.resolveMirrorState({mirrorPath, ref, env});
 	const counts = {totalItems: 0, totalEligible: 0};
-	// HELD-SLUG SUBTRACTION (prd `ledger-status-per-item-lock-refs` US #15): a bare
+	// HELD-SLUG SUBTRACTION (spec `ledger-status-per-item-lock-refs` US #15): a bare
 	// hub mirror's arbiter is its `origin`; read the held lock refs from there and
 	// exclude those slugs from the enumerated `backlog/` pool. Non-fatal (empty set
 	// on any fault) and redundant-but-harmless while the body still moves — wired now
@@ -179,7 +179,7 @@ export async function scanMirrorPool(
 	// its own lock-ref fetch.
 	const heldSlugs = await heldTaskSlugs(mirrorPath, 'origin', env);
 	const items = scoreItems(state, repoConfig.autoBuild, counts, heldSlugs);
-	// Pool 2 — TASKABLE PRDS from the bare mirror's `work/prds/ready`+`work/prds/tasked`,
+	// Pool 2 — TASKABLE PRDS from the bare mirror's `work/specs/ready`+`work/specs/tasked`,
 	// filtered through `autoslice-gate`'s predicate (NOT reinvented). Read FIRST so
 	// we can populate the `specs[]` companion of `items[]` on the RepoReport below.
 	const pool = await read.resolveMirrorSpecPool({mirrorPath, ref, env});
@@ -195,7 +195,7 @@ export async function scanMirrorPool(
 		autoTask: repoConfig.autoTask,
 	});
 	// The one-slug-one-folder LINT is a HUMAN-FACING surface (`scan`/`status`); this
-	// mirror-side pool scan exists only to SCORE the task/prd candidate pools for
+	// mirror-side pool scan exists only to SCORE the task/spec candidate pools for
 	// autonomous selection, never to render a dashboard, so it carries an empty lint
 	// (the duplicate surface is the user-facing `scan`/`status`, per the task). The
 	// `specs[]` companion of `items[]` is filled via the SAME `scoreSpecs` helper