dorfl 0.1.2 → 0.2.0

package/src/run.ts

@@ -31,7 +31,11 @@ import {
 	parseStopSentinel,
 	isWorkBranchDiffEmpty,
 	emptyDiffStopReason,
+	emptyDiffDisposeEnvelope,
+	type AgentStopKind,
 } from './agent-stop.js';
+import {surfaceStuckToNeedsAttention} from './needs-attention.js';
+import {resolveItemPathByIdentity} from './item-path.js';
 import {
 	classifyFailureCause,
 	failureCauseLabel,
@@ -190,6 +194,7 @@ export type ItemStatus =
 	| 'surface-unmoved' // the tree-less surface to needs-attention did NOT land on the arbiter (lost the CAS race / no arbiter) — the item is STILL in-progress on the arbiter; retry/resolve
 	| 'agent-failed' // the agent ran but produced bad/empty output (the conservative generic), OR the cause is unknown
 	| 'transient-infra' // a harness-surfaced model/connection outage (post-retry) or a git/provider outage — RETRY the same work (FAILURE-CAUSE axis)
+	| 'needs-reauth' // a credential expired / was revoked (OAuth refresh) — retry cannot help; a human must RE-AUTH (FAILURE-CAUSE axis)
 	| 'config-error' // a thrown CORE wiring/config error (e.g. review on, no reviewGate) — fix the WIRING, not the task (FAILURE-CAUSE axis)
 	| 'agent-stopped'; // the agent DELIBERATELY stopped (task drifted) OR produced no change — gate + Gate-2 skipped
 
@@ -457,6 +462,7 @@ export async function runOnce(options: RunOnceOptions): Promise<RunOnceResult> {
 			// are the same agent/run-failure routed to needs-attention, just labelled
 			// by cause).
 			i.status === 'transient-infra' ||
+			i.status === 'needs-reauth' ||
 			i.status === 'config-error' ||
 			// The surface to needs-attention did NOT land (lost the CAS race); the item
 			// is still in-progress on the arbiter — a genuine FAILURE (not a clean
@@ -709,16 +715,19 @@ async function runOneItem(
 		//     `work/<slug>` tip == the arbiter tip (the kept branch, unchanged,
 		//     after-commit). The DURABLE artifact is that branch on the arbiter + the
 		//     main surface (ADR §14: the job worktree is a disposable cache; recovery
-		//     flows through the branch + folder-native surfaces, NOT by editing the
-		//     worktree). So the surface is purely the one-file `in-progress/ →
-		//     needs-attention/` ledger move + reason — no branch push, no worktree
-		//     mutation. Because the branch is provably on the arbiter, the §4 reap
+		//     flows through the branch + lock surfaces, NOT by editing the
+		//     worktree). So the surface is purely the lock amend to `state: stuck` +
+		//     reason (post lock-cutover — no `in-progress/ → needs-attention/` folder
+		//     move, no branch push, no worktree
+		//     mutation). Because the branch is provably on the arbiter, the §4 reap
 		//     predicate still HOLDS and this worktree is reaped — more §14-aligned.
 		if (tree.continueRebaseConflict) {
 			const reason =
 				`continuing the kept ${tree.branch}: rebase onto the latest main ` +
-				'conflicted (aborted, never auto-resolved) — resolve against the latest ' +
-				'main, or `requeue --reset` to discard and start fresh';
+				'conflicted (aborted, never auto-resolved) — run `requeue --reconcile` ' +
+				'to non-destructively re-sync the mirror and retry the rebase (keeps ' +
+				'the work). Last resort: `requeue --reset` DESTRUCTIVELY discards the ' +
+				'branch and starts fresh.';
 			updateJobRecord(tree.dir, {state: 'needs-attention', reason});
 			const surfaced = await ledgerWrite.applyTreelessNeedsAttentionTransition({
 				cwd: tree.dir,
@@ -747,9 +756,10 @@ async function runOneItem(
 			const reason =
 				`continuing the kept ${tree.branch}: publishing the rebased work branch ` +
 				`to the arbiter failed terminally (${tree.continuePushFailure}) — the ` +
-				'kept branch is left intact on the arbiter (recoverable); `requeue` to ' +
-				'retry once the churn settles, or `requeue --reset` to discard and start ' +
-				'fresh';
+				'kept branch is left intact on the arbiter (recoverable); ' +
+				'`requeue --reconcile` to non-destructively re-sync the mirror and ' +
+				'retry once the churn settles (keeps the work). Last resort: ' +
+				'`requeue --reset` DESTRUCTIVELY discards the branch and starts fresh.';
 			updateJobRecord(tree.dir, {state: 'needs-attention', reason});
 			const surfaced = await ledgerWrite.applyTreelessNeedsAttentionTransition({
 				cwd: tree.dir,
@@ -862,18 +872,25 @@ async function runOneItem(
 		//     the arbiter) and SKIPS the gate + Gate-2 (the whole `performIntegration`
 		//     band) — a clean STOP is NOT "a build that changed nothing".
 		const sentinel = parseStopSentinel(agent.output);
-		const stopReason =
+		const stopReason: {kind: AgentStopKind; reason: string} | undefined =
 			sentinel !== undefined
-				? sentinel.reason
+				? {kind: 'sentinel', reason: sentinel.reason}
 				: (await isWorkBranchDiffEmpty({
 							cwd: tree.dir,
 							arbiter: tree.arbiterRemote,
 							env: gitEnv,
 					  }))
-					? emptyDiffStopReason(slug)
+					? {kind: 'empty-diff', reason: emptyDiffStopReason(slug)}
 					: undefined;
 		if (stopReason !== undefined) {
-			return await saveAgentStop(base, tree, slug, stopReason, ctx);
+			return await saveAgentStop(
+				base,
+				tree,
+				slug,
+				stopReason.reason,
+				stopReason.kind,
+				ctx,
+			);
 		}
 
 		// 5–7 (CONVERGED). The whole gate → review → done-move → commit → rebase →
@@ -1138,9 +1155,10 @@ function runAgent(
  * This mirrors `do.ts`'s `saveAgentFailure`: route the failure through the SAME
  * ledger write seam's needs-attention transition the gate-fail / integrate-
  * conflict bounces use — which (with the arbiter) saves the agent's work as a wip
- * commit, `git mv`s the item to needs-attention/ with the failure detail recorded
- * as the reason, surfaces the move-only commit on the arbiter's `main`
- * (OBSERVABLE), AND pushes the `work/<slug>` branch (RECOVERABLE — the durable
+ * commit, then — post lock-cutover — amends the item's per-item lock to
+ * `state: stuck` with the failure detail as the reason on the lock entry
+ * (OBSERVABLE; the `needs-attention/` folder move is retired), AND pushes the
+ * `work/<slug>` branch (RECOVERABLE — the durable
  * artifact a requeue-continue lands the next agent on; continue-detection reads
  * <arbiter>/work/<slug> ahead of main). The push is best-effort — an unreachable
  * arbiter leaves the retained worktree + the local commits standing (the genuinely
@@ -1194,8 +1212,9 @@ function failureCauseToItemStatus(cause: FailureCause): ItemStatus {
 
 /**
  * Build the HONEST {@link ItemResult} for a CONTINUE-site surface that did NOT
- * land on the arbiter (`{moved: false}`). The tree-less `in-progress/ →
- * needs-attention/` move lost the CAS race against a busy arbiter (its
+ * land on the arbiter (`{moved: false}`). The tree-less stuck-lock amend (post
+ * lock-cutover — `state: stuck` + reason, in place of the retired `in-progress/ →
+ * needs-attention/` move) lost the CAS race against a busy arbiter (its
  * contention-retry cap exhausted) or had no arbiter to publish to, so the item is
  * STILL in-progress on the arbiter — reporting a clean `needs-attention` would
  * mislead (it claims the surface landed, when it did not). The DISTINCT
@@ -1236,9 +1255,36 @@ async function saveAgentStop(
 	tree: IsolatedTree,
 	slug: string,
 	reason: string,
+	kind: AgentStopKind,
 	ctx: OneItemContext,
 ): Promise<ItemResult> {
 	updateJobRecord(tree.dir, {state: 'needs-attention', reason});
+	// EMPTY-DIFF branch (spec resolved decision #2, task
+	// `empty-diff-bounce-surfaces-dispose-defaulted-question`): surface a sidecar
+	// carrying an engine-authored DISPOSE-DEFAULTED envelope question on
+	// `<arbiter>/main` (via the PR-1 tree-less surface primitive) and release the
+	// lock — NOT the general lock-stuck bounce path. "Nothing to do" is a
+	// non-deterministic LLM judgement, so a blind requeue would infinite-loop;
+	// the surfaced sidecar + `needsAnswers:true` on `main` parks the item as a
+	// human-visible question a `dispose` answer settles to `tasks/cancelled/`.
+	if (kind === 'empty-diff') {
+		const item = `task:${slug}`;
+		const itemPath = resolveItemPathByIdentity(tree.dir, item);
+		if (itemPath !== undefined) {
+			await surfaceStuckToNeedsAttention({
+				cwd: tree.dir,
+				slug,
+				item,
+				itemPath,
+				reason,
+				envelope: emptyDiffDisposeEnvelope({item, reason}),
+				arbiter: tree.arbiterRemote,
+				env: ctx.gitEnv ?? ctx.env,
+			});
+			return {...base, status: 'agent-stopped', detail: reason};
+		}
+		// Fallthrough (body missing) — fall through to the lock-stuck bounce below.
+	}
 	await ledgerWrite.applyNeedsAttentionTransition({
 		cwd: tree.dir,
 		slug,

package/src/scan.ts

@@ -280,7 +280,7 @@ 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
+ * 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
@@ -543,13 +543,22 @@ export function scanRepoPaths(
 	repoPaths: string[],
 	config: Config,
 	/**
-	 * The HELD-SLUG set to SUBTRACT from each repo's pool (`tasks/ready/`) (spec
-	 * `ledger-status-per-item-lock-refs` US #15). This is a WORKING-TREE, OFFLINE
-	 * scan (it has no arbiter handle to fetch the lock refs from — that is the
-	 * registry `scan`'s job), so the held set is supplied by the in-place CALLER
-	 * (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(),
 	/**
@@ -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-priority.ts

@@ -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,7 +76,7 @@ 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`).
  */
@@ -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-spec 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,5 +1,7 @@
+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** (spec `advance-loop`, task
@@ -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
@@ -274,7 +282,7 @@ export function sidecarPathFor(identity: string): string {
  * `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)) {

package/src/spec-complete.ts

@@ -27,9 +27,8 @@ 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 `spec:<slug>` task can reside in. */