dorfl 0.1.1 → 0.2.0

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
@@ -280,8 +280,8 @@ export function scoreSpecs(
  * re-enumeration — a pure shape map over the already-gated pools.
  *
  * 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
+ * construction only carries `'task'`/`'spec'` (an observation with no sidecar is a
+ * `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,13 +543,22 @@ export function scanRepoPaths(
 	repoPaths: string[],
 	config: Config,
 	/**
-	 * The HELD-SLUG set to SUBTRACT from each repo's pool (`tasks/ready/`) (prd
-	 * `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
-	 * (which knows its arbiter) and DEFAULTS to empty: with the body still moving to
-	 * `in-progress/` on claim the subtraction is redundant-but-harmless, so omitting
-	 * it preserves the offline read while keeping the seam in place for task #9.
+	 * The HELD-SLUG set to SUBTRACT from each repo's pool (`tasks/ready/`) AND from
+	 * the in-place lifecycle triage/surface/apply pools (spec
+	 * `ledger-status-per-item-lock-refs` US #15; task
+	 * `in-place-scan-subtracts-held-locked-slugs-from-propose-matrix`). Passed
+	 * BOTH to {@link scoreItems} AND to {@link gatherLifecycleInPlace}, so a slug
+	 * whose per-item lock is currently held (state `active`/`stuck`) never leaks
+	 * into the propose matrix via EITHER the eligible-task pool OR a lifecycle
+	 * leg — CI would otherwise enumerate a `task:<slug>` surface/apply leg that
+	 * always loses the claim CAS.
+	 *
+	 * 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 (which knows its arbiter, e.g.
+	 * `resolveCwdSection` reads it fail-CLOSED via `heldTaskSlugsStrict`) and
+	 * DEFAULTS to empty. An empty default preserves the offline read while keeping
+	 * the seam in place.
 	 */
 	heldSlugs: Set<string> = new Set(),
 	/**
@@ -569,7 +578,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
@@ -590,6 +599,11 @@ export function scanRepoPaths(
 					surfaceBlockers: resolved.surfaceBlockers,
 					surfaceStaging: resolved.surfaceStaging,
 				}),
+				// Held-slug subtraction on the LIFECYCLE side (task
+				// `in-place-scan-subtracts-held-locked-slugs-from-propose-matrix`):
+				// symmetric to the `scoreItems` subtraction above, so a held task never
+				// leaks into a surface/apply leg either.
+				heldSlugs,
 			}),
 		);
 		// The one-slug-one-folder LINT over THIS working tree's `work/` ledger.

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
@@ -49,7 +49,7 @@ import {
 
 /**
  * Which namespace a selected item names (mirrors the slug-namespace split). The
- * `do` selection only ever produces `task`/`prd`; the `advance` selection ALSO
+ * `do` selection only ever produces `task`/`spec`; the `advance` selection ALSO
  * produces `observation` (the lifecycle triage pool, task
  * `advance-autopick-lifecycle-pools`), so a selected lifecycle item carries which
  * rung the driver dispatches to. The widening is BACKWARD-COMPATIBLE: `do` never
@@ -76,13 +76,13 @@ export interface SelectedItem {
 /**
  * A lifecycle-pool selected item (task `advance-autopick-lifecycle-pools`). It is
  * a {@link SelectedItem} — the same shape — carrying the lifecycle namespace
- * (`observation` for triage; `task`/`prd` for a `needsAnswers`-blocked item the
+ * (`observation` for triage; `task`/`spec` for a `needsAnswers`-blocked item the
  * tick will surface/apply). A distinct alias names the lifecycle pools at the
  * call sites WITHOUT a structural difference (the discriminator is `namespace`).
  */
 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 `spec`) — the action names, not the
 	// item namespaces (task `advance-selection-order-config`).
 	const byPool: Record<SelectionPool, SelectedItem[]> = {
 		build: buildItems,

package/src/sidecar-apply.ts

@@ -174,7 +174,7 @@ export function applyAtomic(options: ApplyAtomicOptions): ApplyAtomicResult {
 			writeFileSync(itemAbs, setNeedsAnswersMarker(itemBody, true));
 		}
 		mkdirSync(dirname(sidecarAbs), {recursive: true});
-		writeFileSync(sidecarAbs, serialiseSidecar(sidecar));
+		writeFileSync(sidecarAbs, serialiseSidecar(sidecar, {repoRoot: cwd}));
 		touched.push(sidecarPath);
 	}
 

package/src/sidecar.ts

@@ -1,8 +1,10 @@
+import {existsSync} from 'node:fs';
+import {join} from 'node:path';
 import {parseSlugArg, type SlugNamespace} from './slug-namespace.js';
-import {workItemRel} from './work-layout.js';
+import {workItemRel, type WorkFolderKey} 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
@@ -72,7 +74,7 @@ import {workItemRel} from './work-layout.js';
  * The item-types a sidecar can key onto (the slug-namespace + obs).
  *
  * HARD CUTOVER (spec `prd-to-spec-vocabulary-cutover-and-migration-command`,
- * contract step): the legacy `'prd'` type member is GONE — the parent-spec type
+ * contract step): the legacy ''prd'' type member is GONE — the parent-spec type
  * is `'spec'` only. A `spec:<slug>` identity keys onto the `spec-<slug>`
  * lock/sidecar entry. The on-disk `prd-<slug>.md` sidecar FILE (dorfl's
  * not-yet-converted data) is still probed by {@link sidecarPathCandidates} as a
@@ -88,13 +90,19 @@ export type SidecarType = 'spec' | 'task' | 'observation';
  * sniffing the shape of another field. Absent ⇒ the existing binary content
  * entry (every pre-`kind` sidecar parses + renders byte-identically).
  *
- * INTERIM PRIMITIVE — REMOVE when question sidecars move to KIND-BASED
- * SUBFOLDERS (`work/questions/merge/`, …), where the folder ENCODES the kind
- * and this per-entry field is redundant. See the observation
- * `questions-folder-rename-and-kind-axis-prefix-vs-subfolder-2026-06-21` + idea
- * `folder-taxonomy-and-prd-edit-handshake`. Built deliberately as a single
- * typed field read in exactly ONE place (the apply dispatch, a later task) so
- * the folder-cutover can DELETE it in one move.
+ * A TYPED FIELD is the PERMANENT home for the kind axis (not an interim step
+ * toward kind subfolders). Encoding kind in the PATH — either a filename prefix
+ * (`merge-<type>-<slug>.md`) or a subfolder (`work/questions/merge/…`) — was
+ * deliberately REJECTED: kind is a MUTABLE axis (one item can carry a `spec`
+ * question pre-build, then a `merge` question at land time), but `sidecarPathFor`
+ * is a pure function of item IDENTITY alone and does not know the kind, so a
+ * path that encodes kind would make identity-only lookups SILENTLY miss a
+ * sidecar filed under a different kind. So kind lives INSIDE the file (this
+ * field), the path stays identity-keyed, and per-kind queues are RENDERED by the
+ * tool (`status`/`scan`) rather than by the directory tree. See the observation
+ * `questions-folder-rename-and-kind-axis-prefix-vs-subfolder-2026-06-21` (its
+ * round-2 conclusion + the recorded answers) and `SURFACE-PROTOCOL.md`. The
+ * field is read in exactly ONE place (the apply dispatch).
  *
  * A mistyped/unknown `kind=` token parses to `undefined` (silent-on-malformed,
  * mirroring the retired `disposition` precedent), never a throw, never a
@@ -208,7 +216,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,14 +275,14 @@ 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
  * `spec`-typed identity ALSO probes the legacy `prd-<slug>.md` as a fallback, and
  * a reader takes the FIRST candidate that exists. This is a FILE-PATH DATA alias
  * the migration command removes (it converts `prd-<slug>.md → spec-<slug>.md` on
- * disk); it is NOT the `SlugNamespace`/`SidecarType` `'prd'` type member. Every
+ * disk); it is NOT the `SlugNamespace`/`SidecarType` ''prd'' type member. Every
  * non-`spec` type has a single candidate (its canonical path), unchanged.
  */
 export function sidecarPathCandidates(identity: string): string[] {
@@ -291,6 +299,77 @@ export function sidecarPathCandidates(identity: string): string[] {
 /** The fixed answer marker the human types prose under. */
 const ANSWER_MARKER = '**Your answer** (write below this line):';
 
+/**
+ * The lifecycle folders a given item type may currently reside in — the
+ * search set the {@link serialiseSidecar} human-visible link line scans to
+ * locate the item at write-time. Deliberately INCLUSIVE of the terminal
+ * folders (`done`, `cancelled`, `prds-dropped`) so a sidecar still-being-
+ * serialised for a finished item still emits a clickable link. Kept LOCAL to
+ * this module (rather than reused from `advance.ts`) because this set is the
+ * "where might the item CURRENTLY be on disk?" question, which is broader
+ * than advance's rung-classifier reach.
+ *
+ * DECISION (sidecar-visible-item-link): the task set is the four DURABLE
+ * folders `tasks-ready` / `done` / `cancelled` / `tasks-backlog` and
+ * deliberately EXCLUDES `in-progress` / `needs-attention`. Those two are NOT
+ * durable folders — they are retired transient lock-ref state (ADR
+ * `needs-attention-folder-cutover-followup-nits`, see the `TASK_LIFECYCLE_FOLDERS`
+ * JSDoc in `work-layout.ts`): a stuck task's BODY rests in `tasks/ready/`
+ * while the lock carries `state: stuck`, so no task body ever lives under
+ * `work/in-progress/` or `work/needs-attention/` for this scan to find. An
+ * earlier WIP of this task listed both; narrowing to the durable set matches
+ * the current on-disk reality and avoids scanning phantom folders.
+ * ALTERNATIVE considered: reuse `TASK_LIFECYCLE_FOLDERS` directly — rejected
+ * because it still carries the legacy `in-progress` entry and omits the
+ * `cancelled` / `tasks-backlog` folders a sidecar link may need to reach.
+ */
+const LINK_LIFECYCLE_FOLDERS: Record<SidecarType, readonly WorkFolderKey[]> = {
+	task: ['tasks-ready', 'done', 'cancelled', 'tasks-backlog'],
+	spec: ['specs-ready', 'specs-tasked', 'specs-proposed', 'specs-dropped'],
+	observation: ['observations'],
+};
+
+/**
+ * Look up the item's CURRENT on-disk repo-relative path by scanning the
+ * lifecycle folders its type may reside in, in a documented precedence order.
+ * Returns `undefined` when the item is not found in ANY folder — the
+ * serialiser's "harmless fallback" (omit the link) branch.
+ *
+ * PURE lookup: no throws, no side effects. Every call is a fresh scan — the
+ * link SELF-HEALS on the next `serialise` after a `git mv` between folders
+ * (identity-keyed sidecar; NO lock-step move).
+ */
+function findItemRelPath(
+	repoRoot: string,
+	type: SidecarType,
+	slug: string,
+): string | undefined {
+	for (const folder of LINK_LIFECYCLE_FOLDERS[type]) {
+		const rel = workItemRel(folder, `${slug}.md`);
+		if (existsSync(join(repoRoot, rel))) {
+			return rel;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Render the human-visible Markdown link line, from the sidecar's fixed path
+ * (`work/questions/<type>-<slug>.md`) to the item's current `work/<folder>/
+ * <slug>.md`. Since both live under `work/`, the sidecar-relative link is
+ * `../<folder-name>/<slug>.md` — the `..` climbs out of `questions/` and the
+ * `<folder-name>` (which may contain a `/`, e.g. `tasks/ready`) drops back in.
+ */
+function renderItemLinkLine(item: string, itemRel: string): string {
+	// itemRel is `work/<folder-name>/<slug>.md`; strip the leading `work/` and
+	// prefix with `../` so the link is relative to `work/questions/<file>.md`.
+	const prefix = 'work/';
+	const target = itemRel.startsWith(prefix)
+		? `../${itemRel.slice(prefix.length)}`
+		: itemRel;
+	return `Item: [\`${item}\`](${target})`;
+}
+
 // --- Parse ----------------------------------------------------------------
 
 /** Pull the next monotonic id given the highest existing id number. */
@@ -582,7 +661,10 @@ function blockquote(value: string): string[] {
  * `parseSidecar(serialiseSidecar(m))` recovers an equal MODEL; re-serialising
  * canonicalises the text.
  */
-export function serialiseSidecar(model: SidecarModel): string {
+export function serialiseSidecar(
+	model: SidecarModel,
+	options: SerialiseSidecarOptions = {},
+): string {
 	const out: string[] = [];
 	const identityParts = [
 		`item=${model.item}`,
@@ -592,6 +674,21 @@ export function serialiseSidecar(model: SidecarModel): string {
 	];
 	out.push(`<!-- dorfl-sidecar: ${identityParts.join(' ')} -->`);
 
+	// Human-visible Markdown link line — placed AFTER the identity comment and
+	// BEFORE the first `## ` heading, i.e. in the parser's ignored preamble
+	// region. Regenerated on every serialise from the item's CURRENT on-disk
+	// location; NEVER round-tripped through the parsed model (the link line is
+	// write-only cosmetic output, per the source observation). If the item is
+	// not resolvable on disk, we simply OMIT the line (harmless fallback) — a
+	// broken link would be more confusing than no link.
+	if (options.repoRoot !== undefined) {
+		const itemRel = findItemRelPath(options.repoRoot, model.type, model.slug);
+		if (itemRel !== undefined) {
+			out.push('');
+			out.push(renderItemLinkLine(model.item, itemRel));
+		}
+	}
+
 	model.entries.forEach((entry) => {
 		out.push('');
 		const heading = entry.id.replace(/^q/, 'Q');
@@ -634,6 +731,36 @@ export function serialiseSidecar(model: SidecarModel): string {
 	return out.join('\n');
 }
 
+/**
+ * Options for {@link serialiseSidecar}. The optional `repoRoot` opts the
+ * caller into emitting the human-visible Markdown link line at the top of
+ * the sidecar (pointing at the item's current `work/<folder>/<slug>.md`).
+ * Callers that don't have a repo root (e.g. pure format tests) simply omit
+ * it and the serialiser emits no link — the parse is unaffected either way.
+ *
+ * DECISION (sidecar-visible-item-link): `repoRoot` is OPTIONAL and defaults
+ * to NO link, rather than being a required argument threaded through every
+ * caller. Only the two WRITING call sites (`applyAtomic` in
+ * `sidecar-apply.ts`, `persistSurfacedQuestions` in `surface-persist.ts`)
+ * pass `cwd`; any other current/future caller of `serialiseSidecar` silently
+ * emits no link line. This keeps the many pure-format / round-trip tests
+ * trivial (they need no on-disk repo) and keeps the link a write-only
+ * cosmetic concern of the persist paths. TRADE-OFF: a new writing caller must
+ * remember to pass `repoRoot` to get the link; ALTERNATIVE considered — make
+ * it required — rejected because it would force every format-only caller and
+ * test to fabricate a repo root purely to reach the same no-link output.
+ */
+export interface SerialiseSidecarOptions {
+	/**
+	 * Absolute or relative path to the repository root, so the serialiser can
+	 * scan `work/<lifecycle-folder>/<slug>.md` for the item and render a
+	 * clickable relative link line. When omitted (or when the item cannot be
+	 * located), the link line is omitted — a harmless fallback, never a
+	 * broken link.
+	 */
+	repoRoot?: string;
+}
+
 // --- Append ---------------------------------------------------------------
 
 /** A new question to append (no id — the appender mints the next monotonic id). */

package/src/slug-namespace.ts

@@ -43,8 +43,8 @@ import {ledgerRead, type LedgerReadStrategy} from './ledger-read.js';
  * {@link resolveAdvanceArg}).
  *
  * HARD CUTOVER (spec `prd-to-spec-vocabulary-cutover-and-migration-command`,
- * contract step): the legacy `'prd'` member is GONE — the parent-spec namespace
- * is `'spec'` only. A `prd:<slug>` arg no longer parses to a namespace (it falls
+ * contract step): the legacy ''prd'' member is GONE — the parent-spec namespace
+ * is `'spec'` only. A ''prd:<slug>'' arg no longer parses to a namespace (it falls
  * through to a bare literal slug), and a `work/prd-<slug>` branch ref no longer
  * parses. No back-compat alias (the clean-break stance).
  */
@@ -102,7 +102,7 @@ export function workBranchRef(
  * anchors the optional producer prefix BEFORE the type alternation, so
  * `work/intake-task-foo` resolves to
  * `{producer:'intake', namespace:'task', slug:'foo'}` (the `slug` never
- * swallows the `intake-`/`task-` prefixes). The old `slice`/`brief`/`prd` types
+ * swallows the `intake-`/`task-` prefixes). The old ''slice''/''brief''/''prd'' types
  * are NOT in the alternation, so a pre-rename `work/prd-foo` ref returns
  * `undefined` (the clean-break stance: no migration-window alias).
  */
@@ -112,7 +112,7 @@ export function parseWorkBranchRef(
 	| {producer?: BranchProducer; namespace: SlugNamespace; slug: string}
 	| undefined {
 	// HARD CUTOVER (spec `prd-to-spec-vocabulary-cutover-and-migration-command`,
-	// contract step): the type alternation is `task|spec` ONLY — the legacy `prd`
+	// contract step): the type alternation is `task|spec` ONLY — the legacy ''prd''
 	// token is GONE, so a pre-rename `work/prd-<slug>` ref returns `undefined` (no
 	// migration-window alias; the clean-break stance).
 	const match = /^work\/(?:(intake)-)?(task|spec)-(.+)$/.exec(branch);
@@ -155,7 +155,7 @@ const TASK_PREFIX = 'task:';
 /**
  * The parent-spec namespace prefix: `spec:<slug>` → `{explicit: 'spec'}`. HARD
  * CUTOVER (spec `prd-to-spec-vocabulary-cutover-and-migration-command`): the
- * legacy `prd:` prefix is GONE — a `prd:<slug>` arg falls through to a bare
+ * legacy ''prd:'' prefix is GONE — a ''prd:<slug>'' arg falls through to a bare
  * literal slug (no namespace), the clean-break stance.
  */
 const SPEC_PREFIX = 'spec:';
@@ -184,8 +184,8 @@ export class SlugResolutionError extends Error {
  * slug. PURE string work, no existence check: `task:foo` → explicit task,
  * `spec:foo` → explicit spec, `foo` → bare (`explicit: undefined`). The prefix
  * match is case-sensitive and exact (`task:`/`spec:`); a slug like `tasked` is
- * NOT a prefix and stays bare. HARD CUTOVER: the legacy `prd:` prefix is not a
- * namespace prefix anymore — `prd:foo` stays a bare literal slug.
+ * NOT a prefix and stays bare. HARD CUTOVER: the legacy ''prd:'' prefix is not a
+ * namespace prefix anymore — ''prd:foo'' stays a bare literal slug.
  */
 export function parseSlugArg(arg: string): ParsedSlugArg {
 	if (arg.startsWith(TASK_PREFIX)) {
@@ -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.
@@ -27,12 +27,11 @@ import {
  * claim ledger (`ledger-read.ts` resolves claim-STATE, a different concern). It
  * reuses {@link parseFrontmatter} (the `spec:` field) rather than hand-rolling a YAML
  * parse, and scans the task lifecycle folders directly: `work/tasks/ready/`,
- * `work/in-progress/`, `work/needs-attention/`, and `work/done/`. A task that has
- * NOT yet landed in `work/done/` (still in backlog / in-progress / needs-attention)
- * means the spec is not yet complete.
+ * `work/in-progress/`, and `work/done/`. A task that has NOT yet landed in
+ * `work/done/` (still in backlog / in-progress) 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/`. */