dorfl 0.0.0 → 0.1.0

package/src/arbiter.ts

@@ -0,0 +1,372 @@
+import {existsSync, mkdirSync, readdirSync} from 'node:fs';
+import {dirname, join} from 'node:path';
+import {git, run} from './git.js';
+import {encodeRepoKey} from './repo-mirror.js';
+
+/**
+ * The **arbiter management** primitive (ADR §7 in
+ * `docs/adr/execution-substrate-decisions.md`): provision and inspect a local
+ * `--bare` arbiter — the offline source of truth the claim/integration
+ * protocols serialize on (`scripts/CLAIM-PROTOCOL.md`).
+ *
+ * An arbiter is **precious DATA**, not state or cache: it is the very thing the
+ * deletion-safety predicate (ADR §4) proves everything else safe *against*. So:
+ *
+ *   - It is provisioned under a visible `~/git/` (config `arbitersDir`),
+ *     hierarchical (`<host>/<org>/<name>.git`), reusing the workspace repo→key
+ *     encoding (`.`→`-` per segment) — NEVER under `~/.dorfl/`, whose
+ *     `gc`/cleanup could nuke the only copy.
+ *   - It is created `git clone --bare`. A non-bare repo with `main` checked out
+ *     CANNOT be an arbiter: it rejects pushes to `main` (CLAIM-PROTOCOL), which
+ *     would silently break every claim. `init` refuses that unsafe case; `status`
+ *     flags it.
+ *
+ * This module only **provisions/locates** the arbiter (`arbiterInit` from an
+ * existing working repo, `arbiterStatus`). It does NOT claim, run, or fetch —
+ * those consume what this provides. It reuses the `repo-mirror` repo→key
+ * encoding (it does NOT duplicate it).
+ */
+
+/** The conventional default name for the arbiter remote in a working repo. */
+export const DEFAULT_ARBITER_REMOTE = 'arbiter';
+
+/**
+ * The on-disk location of the local bare arbiter for `url`:
+ * `<arbitersDir>/<host>/<org>/<name>.git` (hierarchical, reusing the
+ * `repo-mirror` repo→key encoding, with a `.git` suffix). Lives under
+ * `arbitersDir` (default `~/git`), NEVER `~/.dorfl` (ADR §7).
+ */
+export function arbiterPath(arbitersDir: string, url: string): string {
+	return join(arbitersDir, `${encodeRepoKey(url)}.git`);
+}
+
+export interface ArbiterInitOptions {
+	/**
+	 * The working repo to derive the arbiter FROM (its current contents seed the
+	 * bare clone, and its `<remote>` is wired to point at it). Defaults to `cwd`.
+	 */
+	repo?: string;
+	/** Working directory `repo` defaults to when omitted. Defaults to `process.cwd()`. */
+	cwd?: string;
+	/**
+	 * Override the resolved default path (`<arbitersDir>/<key>.git`) with an
+	 * explicit location (`--at`). Still created `--bare`.
+	 */
+	at?: string;
+	/** Where to provision the arbiter (config `arbitersDir`, default `~/git`). */
+	arbitersDir?: string;
+	/** Name of the remote to wire in `repo` (`--remote`). Default `arbiter`. */
+	remote?: string;
+	env?: NodeJS.ProcessEnv;
+	/** Sink for human-readable progress notes. */
+	note?: (message: string) => void;
+}
+
+export interface ArbiterInitResult {
+	/** Absolute path to the (existing or just-created) bare arbiter. */
+	path: string;
+	/** The `file://` URL the repo's remote was wired to. */
+	url: string;
+	/** The remote name wired in the working repo. */
+	remote: string;
+	/** True iff the arbiter did not exist and was just `clone --bare`d. */
+	created: boolean;
+	/** True iff an arbiter already existed at the path (idempotent no-clobber). */
+	alreadyExisted: boolean;
+	/** True iff the arbiter is bare (always true on success — invariant). */
+	bare: boolean;
+}
+
+/** Raised when `init` cannot safely provision/locate an arbiter. */
+export class ArbiterError extends Error {}
+
+/**
+ * Provision (or locate) a local bare arbiter from a working repo and wire the
+ * repo's `<remote>` to it. Idempotent: an existing arbiter is detected and NOT
+ * clobbered (it is only re-pointed by the remote, never re-cloned). Refuses the
+ * unsafe case where the target is a non-bare repo with `main` checked out (which
+ * would reject claim pushes — CLAIM-PROTOCOL).
+ *
+ * The default path is hierarchical under `arbitersDir` (`~/git`), NEVER under
+ * `~/.dorfl` (ADR §7) — overridable via `at`.
+ */
+export function arbiterInit(options: ArbiterInitOptions): ArbiterInitResult {
+	const env = options.env;
+	const note = options.note ?? (() => {});
+	const repo = options.repo ?? options.cwd ?? process.cwd();
+	const remote = options.remote ?? DEFAULT_ARBITER_REMOTE;
+
+	if (run('git', ['rev-parse', '--git-dir'], repo, {env}).status !== 0) {
+		throw new ArbiterError(`not inside a git repository: ${repo}`);
+	}
+
+	// Resolve the destination path: explicit --at, else the hierarchical default
+	// under arbitersDir keyed off the repo's canonical file:// URL.
+	const repoUrl = `file://${repo}`;
+	const path = options.at ?? arbiterPath(arbitersDir(options), repoUrl);
+	const url = `file://${path}`;
+
+	// Idempotent: an existing git repo at the path is detected, validated as bare,
+	// and NEVER clobbered (no re-clone). We only ensure the remote is wired.
+	if (pathHoldsGitRepo(path)) {
+		assertBare(path, env);
+		note(
+			`arbiter already exists at ${path} (not re-cloning) — ensuring remote.`,
+		);
+		wireRemote(repo, remote, url, env);
+		return {
+			path,
+			url,
+			remote,
+			created: false,
+			alreadyExisted: true,
+			bare: true,
+		};
+	}
+
+	// Refuse the unsafe case: --at points at an EXISTING non-bare repo (e.g. one
+	// with main checked out). Using it as the arbiter rejects claim pushes to
+	// main (CLAIM-PROTOCOL) — a silent, claim-breaking footgun.
+	if (existsSync(path) && pathLooksLikeWorkingTree(path)) {
+		assertBare(path, env); // throws with the clear non-bare message
+	}
+
+	// Provision: a bare clone of the working repo (its objects + main seed it).
+	mkdirSync(dirname(path), {recursive: true});
+	git(['clone', '--quiet', '--bare', repo, path], dirname(path), {env});
+	note(`provisioned bare arbiter at ${path}`);
+
+	// Wire the repo's <remote> to the new arbiter.
+	wireRemote(repo, remote, url, env);
+
+	return {path, url, remote, created: true, alreadyExisted: false, bare: true};
+}
+
+export interface ArbiterStatusOptions {
+	/** The working repo to inspect. Defaults to `process.cwd()`. */
+	cwd?: string;
+	/** The arbiter remote name to report on. Default `arbiter`. */
+	remote?: string;
+	env?: NodeJS.ProcessEnv;
+}
+
+export interface ArbiterStatusReport {
+	/** The remote name inspected. */
+	remote: string;
+	/** True iff the working repo has a remote with that name. */
+	configured: boolean;
+	/** The remote's URL, if configured. */
+	url?: string;
+	/** The local filesystem path the URL resolves to (for `file://` / local URLs). */
+	path?: string;
+	/** True iff a git repo exists at `path` (or the URL is reachable locally). */
+	exists: boolean;
+	/** True iff the arbiter is a bare repo (the safe shape). */
+	bare: boolean;
+	/** True iff `main` is reachable on the arbiter. */
+	mainReachable: boolean;
+	/**
+	 * True iff the arbiter is in the unsafe non-bare-with-main shape: it EXISTS
+	 * but is not bare (CLAIM-PROTOCOL warns this rejects claim pushes).
+	 */
+	unsafe: boolean;
+}
+
+/**
+ * Read-only report of the current repo's arbiter: which remote it is, its
+ * URL/path, whether it exists and is bare, and whether `main` is reachable. It
+ * MUTATES NOTHING (no fetch, no checkout) — it reads the local remote config and
+ * inspects the arbiter repo in place. Flags the unsafe non-bare-with-main case
+ * (ADR §7 / CLAIM-PROTOCOL).
+ */
+export function arbiterStatus(
+	options: ArbiterStatusOptions,
+): ArbiterStatusReport {
+	const env = options.env;
+	const cwd = options.cwd ?? process.cwd();
+	const remote = options.remote ?? DEFAULT_ARBITER_REMOTE;
+
+	const urlResult = run('git', ['remote', 'get-url', remote], cwd, {env});
+	if (urlResult.status !== 0) {
+		return {
+			remote,
+			configured: false,
+			exists: false,
+			bare: false,
+			mainReachable: false,
+			unsafe: false,
+		};
+	}
+	const url = urlResult.stdout.trim();
+	const path = localPathFromUrl(url);
+
+	// Only a local path can be inspected in place; a remote URL (github, ssh) is
+	// reported as configured but its bare-ness/reachability is not probed here.
+	if (path === undefined) {
+		return {
+			remote,
+			configured: true,
+			url,
+			exists: false,
+			bare: false,
+			mainReachable: false,
+			unsafe: false,
+		};
+	}
+
+	const exists = pathHoldsGitRepo(path);
+	if (!exists) {
+		return {
+			remote,
+			configured: true,
+			url,
+			path,
+			exists: false,
+			bare: false,
+			mainReachable: false,
+			unsafe: false,
+		};
+	}
+
+	const bare = isBareRepo(path, env);
+	const mainReachable =
+		run('git', ['rev-parse', '--verify', 'main'], path, {
+			env,
+		}).status === 0;
+
+	return {
+		remote,
+		configured: true,
+		url,
+		path,
+		exists: true,
+		bare,
+		mainReachable,
+		// Unsafe = it exists but is NOT bare (a working tree with main checked out
+		// rejects claim pushes to main — CLAIM-PROTOCOL).
+		unsafe: !bare,
+	};
+}
+
+/** Render an `arbiter status` report for the terminal. */
+export function formatArbiterStatus(report: ArbiterStatusReport): string {
+	const lines: string[] = [];
+	if (!report.configured) {
+		lines.push(
+			`Arbiter: no '${report.remote}' remote configured in this repo.`,
+		);
+		lines.push(
+			`  Run \`dorfl arbiter init --remote ${report.remote}\` to provision one,`,
+		);
+		lines.push('  or set it manually with `git remote add`.');
+		return lines.join('\n');
+	}
+
+	lines.push(`Arbiter remote: ${report.remote}`);
+	lines.push(`  URL:    ${report.url ?? '(unknown)'}`);
+	if (report.path !== undefined) {
+		lines.push(`  path:   ${report.path}`);
+	}
+	lines.push(`  exists: ${report.exists ? 'yes' : 'no'}`);
+	if (report.exists) {
+		lines.push(`  bare:   ${report.bare ? 'yes' : 'no'}`);
+		lines.push(
+			`  main:   ${report.mainReachable ? 'reachable' : 'NOT reachable'}`,
+		);
+	}
+	if (report.unsafe) {
+		lines.push('');
+		lines.push(
+			'  !! UNSAFE: the arbiter is a non-bare repo (a working tree). A non-bare',
+		);
+		lines.push(
+			'     repo with `main` checked out REJECTS claim pushes to main',
+		);
+		lines.push(
+			'     (CLAIM-PROTOCOL). Re-provision a bare arbiter with `arbiter init`.',
+		);
+	} else if (report.exists && !report.mainReachable) {
+		lines.push('');
+		lines.push(
+			'  !! main is not reachable on the arbiter (empty or wrong repo?).',
+		);
+	}
+	return lines.join('\n');
+}
+
+/** Resolve the arbiters dir from options, defaulting to `~/git`. */
+function arbitersDir(options: ArbiterInitOptions): string {
+	if (options.arbitersDir && options.arbitersDir.trim() !== '') {
+		return options.arbitersDir;
+	}
+	throw new ArbiterError(
+		'arbiterInit requires `at` or `arbitersDir` (the CLI passes the resolved config).',
+	);
+}
+
+/** Add the remote if absent, else set its URL (idempotent wiring). */
+function wireRemote(
+	repo: string,
+	remote: string,
+	url: string,
+	env: NodeJS.ProcessEnv | undefined,
+): void {
+	const existing = run('git', ['remote', 'get-url', remote], repo, {env});
+	if (existing.status === 0) {
+		git(['remote', 'set-url', remote, url], repo, {env});
+	} else {
+		git(['remote', 'add', remote, url], repo, {env});
+	}
+}
+
+/** Throw a clear error if the repo at `path` is not bare (the unsafe case). */
+function assertBare(path: string, env: NodeJS.ProcessEnv | undefined): void {
+	if (!isBareRepo(path, env)) {
+		throw new ArbiterError(
+			`refusing: the arbiter at ${path} is a NON-BARE repo (a working tree). ` +
+				'A non-bare repo with `main` checked out rejects claim pushes to main ' +
+				'(CLAIM-PROTOCOL) — it cannot serve as an arbiter. Provision a bare ' +
+				'arbiter (git clone --bare) at a clean location instead.',
+		);
+	}
+}
+
+/** True iff `path` is (or contains) an initialised git repository. */
+function pathHoldsGitRepo(path: string): boolean {
+	if (!existsSync(path)) {
+		return false;
+	}
+	// A bare repo IS a git dir; a non-bare repo has a `.git` entry. Either way,
+	// `git rev-parse --git-dir` succeeds when run inside it.
+	return run('git', ['rev-parse', '--git-dir'], path).status === 0;
+}
+
+/** True iff `path` exists and looks like a non-empty directory (a candidate repo). */
+function pathLooksLikeWorkingTree(path: string): boolean {
+	try {
+		return readdirSync(path).length > 0;
+	} catch {
+		return false;
+	}
+}
+
+/** True iff the git repo at `path` is bare. */
+function isBareRepo(path: string, env: NodeJS.ProcessEnv | undefined): boolean {
+	const result = run('git', ['rev-parse', '--is-bare-repository'], path, {env});
+	return result.status === 0 && result.stdout.trim() === 'true';
+}
+
+/**
+ * The local filesystem path a remote URL refers to, or `undefined` for a true
+ * remote (github/ssh/https). Handles `file://...` and a plain absolute path.
+ */
+function localPathFromUrl(url: string): string | undefined {
+	const trimmed = url.trim();
+	if (trimmed.startsWith('file://')) {
+		return trimmed.slice('file://'.length);
+	}
+	if (trimmed.startsWith('/')) {
+		return trimmed;
+	}
+	return undefined;
+}

package/src/brand.ts

@@ -0,0 +1,111 @@
+/**
+ * The **brand / protocol identity** single source of truth (ADR-class load-
+ * bearing strings).
+ *
+ * dorfl's name leaks into a handful of strings that are a CONTRACT with
+ * the user, the filesystem, and CI — and that BREAK SILENTLY if they drift out
+ * of sync on a rename:
+ *
+ *   - the `DORFL_` env-var prefix (a missed one is read as "unset" — the
+ *     worst kind of failure: silent);
+ *   - the `.dorfl.json` per-repo config filename;
+ *   - the `~/.dorfl/` workspaces-dir default + the `dorfl` config
+ *     dir name;
+ *   - the `.dorfl-job.json` per-job record filename;
+ *   - the `dorfl` binary / package name where referenced FROM CODE.
+ *
+ * This module derives EVERY one of those from a SINGLE base string ({@link BASE})
+ * using the same case transforms the `change-name` tool understands
+ * (https://github.com/wighawag/change-name — camelCase/constantCase/paramCase/…).
+ * Renaming the project later is then ONE edit here, not a scattered (and
+ * silently-breakable) find/replace across the codebase.
+ *
+ * SCOPE: only the PROTOCOL surface (where a miss BREAKS things). The ~600
+ * cosmetic doc/prose mentions of "dorfl" (ADRs, prds, CONTEXT.md, tasks,
+ * comments) are NOT indirected through this module — they should read as the real
+ * name and are handled at actual rebrand time by `change-name` (multi-case-aware
+ * recursive rename of file names + contents). The two are complementary: this
+ * centralizes the breakable protocol surface; `change-name` covers the cosmetic
+ * bulk. Likewise `package.json`'s `name`/`bin` are NOT indirected through a
+ * runtime constant (that is also `change-name`'s job) — {@link Brand.bin} merely
+ * exposes the SAME derived value for the code sites that reference the binary.
+ */
+
+/**
+ * The ONE base identity string, in `paramCase` (the natural form of the binary
+ * name). Change THIS and every derived protocol form below flips in lockstep.
+ */
+export const BASE = 'dorfl';
+
+// --- Case transforms (the subset of `change-name`'s vocabulary we derive from).
+//
+// Implemented locally (no runtime dependency) but NAMED for the `change-name`
+// conventions so the mapping is obvious at rebrand time. Each splits the input
+// into lowercase words, then re-joins per the target case. The base is already
+// `paramCase`, but we go through `words()` so a future base in any case still
+// derives correctly.
+
+/** Split an identifier (any case) into its lowercase words. */
+function words(input: string): string[] {
+	return input
+		.replace(/([a-z0-9])([A-Z])/g, '$1 $2') // camelCase / PascalCase boundary
+		.replace(/[-_\s.]+/g, ' ') // param/snake/dot/space separators
+		.trim()
+		.toLowerCase()
+		.split(/\s+/)
+		.filter((w) => w !== '');
+}
+
+/** `dorfl` (lowercase words joined by `-`). */
+export function paramCase(input: string): string {
+	return words(input).join('-');
+}
+
+/** `DORFL` (uppercase words joined by `_`). */
+export function constantCase(input: string): string {
+	return words(input)
+		.map((w) => w.toUpperCase())
+		.join('_');
+}
+
+/**
+ * The derived brand surface. Every field is computed from {@link BASE}; none is
+ * an independent literal, so they can never drift apart.
+ */
+export interface Brand {
+	/** The base identity string (paramCase): `dorfl`. */
+	readonly base: string;
+	/** The shared env-var prefix: `constantCase(base) + '_'` ⇒ `DORFL_`. */
+	readonly envPrefix: string;
+	/** The per-repo config filename: `.{paramCase(base)}.json` ⇒ `.dorfl.json`. */
+	readonly repoConfigFilename: string;
+	/** The workspaces-dir name (a dotfile dir): `.{paramCase(base)}` ⇒ `.dorfl`. */
+	readonly workdirName: string;
+	/** The per-job record filename: `.{paramCase(base)}-job.json` ⇒ `.dorfl-job.json`. */
+	readonly jobRecordFilename: string;
+	/** The config-dir name (under `~/.config/`): `paramCase(base)` ⇒ `dorfl`. */
+	readonly configDirName: string;
+	/** The binary / package name (paramCase): `dorfl`. */
+	readonly bin: string;
+}
+
+/** Derive the full {@link Brand} surface from one base string. */
+export function deriveBrand(base: string): Brand {
+	const param = paramCase(base);
+	return {
+		base,
+		envPrefix: constantCase(base) + '_',
+		repoConfigFilename: `.${param}.json`,
+		workdirName: `.${param}`,
+		jobRecordFilename: `.${param}-job.json`,
+		configDirName: param,
+		bin: param,
+	};
+}
+
+/**
+ * The live brand surface for THIS project, derived from {@link BASE}. Import the
+ * fields you need (e.g. `brand.envPrefix`, `brand.workdirName`) instead of
+ * hardcoding the literal — that is the whole point of this module.
+ */
+export const brand: Brand = deriveBrand(BASE);

package/src/buildable-body.ts

@@ -0,0 +1,196 @@
+/**
+ * The SINGLE owner of the buildable-task (and PRD-body) markdown SECTION SCHEMA
+ * (prd `centralize-buildable-task-renderer-shared-by-intake-and-promotion`, US
+ * #1/#4/#7). dorfl has TWO independent producers of a buildable task/PRD body —
+ * `intake.ts` (`renderBacklogTask`/`renderSpec`, a wrapper+fallback) and
+ * `triage-persist.ts` (`buildPromotedBody`, a structured renderer) — and until
+ * this module they each HAND-ROLLED the `## What to build` / `## Acceptance
+ * criteria` / `## Open questions` / `## Prompt` skeleton, so the schema could (and
+ * did) DRIFT apart silently (the promptless-promotion stuck-lock bug, see the
+ * origin observation
+ * `advance-promotion-builds-promptless-task-that-self-claims-stuck-2026-06-25`).
+ *
+ * This module renders only the BODY (the markdown AFTER the frontmatter fence) —
+ * the part both producers actually share. Each producer keeps its OWN frontmatter
+ * writer (intake stamps `issue:`/`originTrust:`; promotion stamps `needsAnswers:`/
+ * `blockedBy:`) and its OWN writer/integration mode (intake's branch+PR front
+ * door; promotion's triage-local CAS create) — only the section skeleton is
+ * centralized here.
+ *
+ * The two producers are ASYMMETRIC, and that asymmetry is expressed by the
+ * renderer's inputs rather than by two divergent bodies:
+ *
+ *   - intake's DEFAULT-SCAFFOLD skeleton (used ONLY when the intake agent drafted
+ *     no body) is `## What to build` + `## Acceptance criteria` + a thin default
+ *     `## Prompt`. Reproduced by passing all three.
+ *   - promotion's structured body is `## What to build` (the mechanism prose) +
+ *     optional `## Open questions` + a `## Prompt` seeded (blockquoted) from the
+ *     mechanism prose, and NO `## Acceptance criteria`. Reproduced by omitting
+ *     `acceptanceCriteria` and passing the open-questions block + the seed prose.
+ *
+ * Symmetrically, {@link renderSpecBody} owns the FULL PRD section schema both PRD
+ * producers need: intake's default PRD scaffold is `## Problem Statement` +
+ * `## Solution` + `## User Stories` (reproduced by passing all three), while
+ * promotion's structured PRD body is `## Problem Statement` + optional
+ * `## Open questions` (reproduced by omitting `solution`/`userStories`). Each
+ * optional section is emitted only when its input is non-empty.
+ *
+ * `## Prompt` is TASK-ONLY: a PRD is not dispatched by `do`/`run`, so a PRD body
+ * carries none (the symmetric reason the task body MUST carry one — the consumer
+ * `extractPromptSection`/`resolveTask` in `prompt.ts` throws "has no '## Prompt'
+ * section" at dispatch time without it). {@link renderTaskBody} always emits a
+ * `## Prompt`; {@link renderSpecBody} never does.
+ *
+ * NOTE (extract-only): this module is a PURE ADDITION. Neither producer is rewired
+ * here — that is the two follow-on tasks (kept file-orthogonal so each proves its
+ * own output is byte-for-byte preserved). This task lands the renderer + its
+ * golden-shape test ONLY.
+ */
+
+/** Blockquote a prompt SEED: each line gets a `> ` prefix (blank lines → `>`). */
+function blockquote(seed: string): string {
+	return seed
+		.split('\n')
+		.map((line) => (line === '' ? '>' : `> ${line}`))
+		.join('\n');
+}
+
+export interface RenderTaskBodyInput {
+	/**
+	 * The `## What to build` prose. For intake's default scaffold this is the task
+	 * title; for promotion it is the observation's mechanism/fix prose. When empty,
+	 * a placeholder keeps the section non-empty.
+	 */
+	whatToBuild: string;
+	/**
+	 * The `## Acceptance criteria` block (markdown, e.g. a `- [ ]` checklist).
+	 * OMIT it (or pass empty) to drop the section entirely — promotion's structured
+	 * body carries no acceptance section, intake's default scaffold does.
+	 */
+	acceptanceCriteria?: string;
+	/**
+	 * The `## Open questions` block (markdown). OMIT it (or pass empty) to drop the
+	 * section — intake's default scaffold has none, a promoted observation carries
+	 * its transcribed open questions here.
+	 */
+	openQuestions?: string;
+	/**
+	 * The `## Prompt` body, supplied UNQUOTED — the renderer blockquotes it (the
+	 * `> `-prefixed shape `extractPromptSection` strips back off). This is the
+	 * task-only dispatchability section; it is ALWAYS emitted (a placeholder seeds
+	 * it when empty) so a rendered task never fails the missing-`## Prompt` guard.
+	 */
+	prompt: string;
+}
+
+/**
+ * Render a buildable TASK body (the markdown AFTER the frontmatter fence). Emits,
+ * in order: `## What to build`, `## Acceptance criteria` (only when given),
+ * `## Open questions` (only when given), and ALWAYS `## Prompt` (blockquoted).
+ *
+ * The output passes `extractPromptSection`/`resolveTask` without the
+ * "has no '## Prompt' section" throw, because `## Prompt` is unconditional and
+ * never empty. The caller wraps this body with its own frontmatter.
+ *
+ * FENCE↔HEADING BOUNDARY: this renderer starts at its first heading with NO
+ * leading blank line — the caller's frontmatter serializer owns the single blank
+ * line between the closing `---` fence and this first heading (ratified in
+ * `docs/adr/frontmatter-owns-fence-to-heading-blank-line.md`). Do NOT add a
+ * leading blank here; that would reintroduce the fence-spacing drift class.
+ */
+export function renderTaskBody(input: RenderTaskBodyInput): string {
+	const lines: string[] = [
+		'## What to build',
+		'',
+		input.whatToBuild.trim() === ''
+			? '(no `## What to build` prose was supplied.)'
+			: input.whatToBuild.trim(),
+		'',
+	];
+
+	const acceptance = (input.acceptanceCriteria ?? '').trim();
+	if (acceptance !== '') {
+		lines.push('## Acceptance criteria', '', acceptance, '');
+	}
+
+	const openQuestions = (input.openQuestions ?? '').trim();
+	if (openQuestions !== '') {
+		lines.push('## Open questions', '', openQuestions, '');
+	}
+
+	const seed =
+		input.prompt.trim() === ''
+			? 'Build the task described above.'
+			: input.prompt.trim();
+	lines.push('## Prompt', '', blockquote(seed), '');
+
+	return lines.join('\n');
+}
+
+export interface RenderSpecBodyInput {
+	/**
+	 * The `## Problem Statement` prose. For intake's default scaffold this is the
+	 * issue-transform line; for promotion it is the observation's mechanism prose.
+	 * When empty, a placeholder keeps the section non-empty.
+	 */
+	problemStatement: string;
+	/**
+	 * The `## Solution` prose (markdown). OMIT it (or pass empty) to drop the
+	 * section — promotion's structured PRD body carries no Solution section, intake's
+	 * default PRD scaffold does.
+	 */
+	solution?: string;
+	/**
+	 * The `## User Stories` block (markdown, e.g. a numbered list). OMIT it (or pass
+	 * empty) to drop the section — promotion's structured PRD body carries no User
+	 * Stories section, intake's default PRD scaffold does.
+	 */
+	userStories?: string;
+	/**
+	 * The `## Open questions` block (markdown). OMIT it (or pass empty) to drop the
+	 * section. A PRD carries NO `## Prompt` (it is not dispatched).
+	 */
+	openQuestions?: string;
+}
+
+/**
+ * Render a PRD body (the markdown AFTER the frontmatter fence). Emits, in the
+ * canonical order, `## Problem Statement`, then `## Solution`, `## User Stories`,
+ * and `## Open questions` (each only when its input is given), and NEVER a
+ * `## Prompt` — a PRD is a north-star doc, not a dispatchable task. The symmetric twin of
+ * {@link renderTaskBody}, owning the FULL SPEC section schema both producers need
+ * (intake's default scaffold supplies Problem Statement + Solution + User Stories;
+ * promotion's structured body supplies Problem Statement + optional Open
+ * questions) so the two artifact shapes cannot drift apart.
+ *
+ * FENCE↔HEADING BOUNDARY: same convention as {@link renderTaskBody} — no leading
+ * blank; the frontmatter serializer owns the `\n\n` after the closing `---` fence
+ * (see `docs/adr/frontmatter-owns-fence-to-heading-blank-line.md`).
+ */
+export function renderSpecBody(input: RenderSpecBodyInput): string {
+	const lines: string[] = [
+		'## Problem Statement',
+		'',
+		input.problemStatement.trim() === ''
+			? '(no `## Problem Statement` prose was supplied.)'
+			: input.problemStatement.trim(),
+		'',
+	];
+
+	const solution = (input.solution ?? '').trim();
+	if (solution !== '') {
+		lines.push('## Solution', '', solution, '');
+	}
+
+	const userStories = (input.userStories ?? '').trim();
+	if (userStories !== '') {
+		lines.push('## User Stories', '', userStories, '');
+	}
+
+	const openQuestions = (input.openQuestions ?? '').trim();
+	if (openQuestions !== '') {
+		lines.push('## Open questions', '', openQuestions, '');
+	}
+
+	return lines.join('\n');
+}