dorfl 0.0.0 → 0.1.0

package/src/surface-gate.ts

@@ -0,0 +1,337 @@
+import {NullHarness, type Harness} from './harness.js';
+import {launchWithOptionalWatch} from './agent-launch.js';
+import {boundaryLine} from './watch-session.js';
+import {extractJsonObjectSpan} from './verdict-json.js';
+import {parseableJsonContractPrompt} from './review-verdict.js';
+import type {NewQuestion} from './sidecar.js';
+
+/**
+ * The **SURFACE gate** (prd `advance-loop`, task `advance-rung-surface`,
+ * US #32/33) — the surface-question rung's fresh-context spawn, the DIRECT mirror
+ * of the PR/code review gate ({@link import('./review-gate.js')}). On
+ * `classify=surface`, the advance engine spawns a FRESH-CONTEXT agent with the
+ * `surface-questions` SKILL loaded (`skills/surface-questions/SKILL.md`); the
+ * skill GATHERS the item's open-judgement residue and EMITS questions and writes
+ * NOTHING (doc-shaped, like `review`). The ENGINE then ITSELF persists them to
+ * the sidecar CAS-atomically + sets `needsAnswers:true` (task
+ * `advance-rung-surface`'s persist half) — **the skill JUDGES, the engine
+ * PERSISTS.**
+ *
+ * This module is the SEAM (the {@link SurfaceGate} function type) + its
+ * production harness-backed implementation ({@link harnessSurfaceGate}), exactly
+ * as `review-gate.ts` is the seam + `harnessReviewGate`. The seam is injectable:
+ * tests stub a canned emitted-questions list (no real model); production launches
+ * the `surface-questions` agent through the EXISTING harness seam
+ * ({@link Harness}/`LaunchInput`), routing an optional `surfaceModel` override
+ * through `LaunchInput.model` — NOT a new model/launch mechanism (the §13
+ * model-routing intent). It mirrors `harnessReviewGate` byte-for-byte in shape;
+ * only the PROMPT ({@link buildSurfacePrompt}) and the parsed payload
+ * ({@link parseSurfaceEmit}, a `{questions}` list rather than a `{verdict}`)
+ * differ.
+ *
+ * ALWAYS-allowed: there is NO gate check before surfacing — surfacing a question
+ * is never gated, even with every autonomy flag off (the "question loop with zero
+ * autonomy" case, US #23). The expensive (agent/model) work is POST-lock,
+ * winner-only — but that sequencing is the ENGINE's job (`advance.ts`); this
+ * module is only the spawn→emit→parse.
+ */
+
+/**
+ * One question the `surface-questions` skill EMITS — the THREE authoring fields of
+ * the sidecar entry shape (`skills/surface-questions/SKILL.md` → "The emitted
+ * question shape"). It maps 1:1 onto {@link NewQuestion} (what the engine appends
+ * to the sidecar), so the engine persists with ZERO translation. The skill does
+ * NOT assign `id`/`answered`/`answer`/`allAnswered` — those are the sidecar's
+ * machine-owned fields the engine owns. A surfaced question is a PLAIN question:
+ * there is NO `disposition` token any more (task
+ * `agentic-apply-retire-disposition-vocabulary`) — what to DO with the answered
+ * signal is decided by the AGENTIC apply decision, not stamped on the question.
+ */
+export interface SurfaceQuestion {
+	/** The question, verbatim. */
+	question: string;
+	/** Inline context so the human need not open the item. */
+	context?: string;
+	/** Optional suggested default (the humility aid; NEVER a decision). */
+	default?: string;
+}
+
+/**
+ * What the `surface-questions` SKILL emits (and this gate parses): the item's
+ * identity (orientation only) + an ORDERED list of questions. An EMPTY list is a
+ * valid, honest result ("no open judgement") — the engine writes no sidecar.
+ */
+export interface SurfaceEmit {
+	/** The namespaced identity the skill surfaced for (orientation; advisory). */
+	item?: string;
+	/** The ordered emitted questions (possibly empty). */
+	questions: SurfaceQuestion[];
+}
+
+/** What the surface gate needs to launch a fresh-context surface of one item. */
+export interface SurfaceGateInput {
+	/** The namespaced identity the surface is for (`task:foo` / `prd:bar` / `observation:baz`). */
+	item: string;
+	/** The working clone/checkout the gate runs in. */
+	cwd: string;
+	/**
+	 * The model the SURFACE agent runs on. `undefined` ⇒ no forced model (the
+	 * harness's own default). Flows to the launch through `LaunchInput.model`.
+	 */
+	surfaceModel?: string;
+	/** Environment for the surface-agent launch. */
+	env?: NodeJS.ProcessEnv;
+	/** `--watch`: tail the surface agent's pi session live (pure observer). */
+	watch?: boolean;
+	/** Where the tailed surface lines are written (defaults to stderr). */
+	watchSink?: (line: string) => void;
+	/** Emit ANSI colour in the tailed surface lines (the caller's TTY decision). */
+	color?: boolean;
+	/** The HOST-ONLY sessions root the surface session FILE is generated under. */
+	sessionsDir?: string;
+}
+
+/**
+ * The surface-gate SEAM: run a fresh-context surface of the item and return the
+ * parsed emitted questions. Injected by tests (a canned list, no real model);
+ * production uses {@link harnessSurfaceGate}. Mirrors `review-gate.ts`'s
+ * `ReviewGate` seam shape so the engine wiring is testable as pure logic.
+ */
+export type SurfaceGate = (input: SurfaceGateInput) => Promise<SurfaceEmit>;
+
+/** Raised when the surface agent ran but produced no parseable emit. */
+export class SurfaceParseError extends Error {}
+
+/**
+ * Parse the `surface-questions` SKILL's emitted questions out of the surface
+ * agent's textual output. The skill emits a `{item, questions:[…]}` JSON object
+ * (the agent may wrap it in prose / a fenced block), so we extract the first JSON
+ * object carrying a `questions` field and validate its shape. An EMPTY
+ * `questions` list is VALID (the honest "no open judgement" result). Throws
+ * {@link SurfaceParseError} when no valid emit is present (the caller treats an
+ * unparseable emit as an error — never a silent "surfaced nothing").
+ *
+ * The emit MAY also carry a free-prose `note` field (the surface counterpart of
+ * the verdict's `review`): a HOME inside the object for the agent's reasoning /
+ * findings so it never needs to write prose AROUND the JSON (the cause of the
+ * "no parseable {questions}" trailing-chatter failure — observation
+ * `surface-rung-agent-emits-no-parseable-questions`). The engine does not
+ * persist `note`, so it is simply IGNORED here (like every unrecognised field);
+ * the prompt's job is to give the prose a place to go, not the parser's to keep
+ * it.
+ */
+export function parseSurfaceEmit(output: string): SurfaceEmit {
+	const span = extractJsonObjectSpan(output, 'questions');
+	if (span === undefined) {
+		throw new SurfaceParseError(
+			'surface agent produced no parseable {questions} result',
+		);
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(output.slice(span.start, span.end));
+	} catch (err) {
+		throw new SurfaceParseError(
+			`surface emit was not valid JSON: ${(err as Error).message}`,
+		);
+	}
+	return validateEmit(parsed);
+}
+
+/** Validate a parsed object is a `{item?, questions:[…]}` shape; normalise it. */
+function validateEmit(parsed: unknown): SurfaceEmit {
+	if (typeof parsed !== 'object' || parsed === null) {
+		throw new SurfaceParseError('surface emit was not an object');
+	}
+	const obj = parsed as Record<string, unknown>;
+	if (!Array.isArray(obj.questions)) {
+		throw new SurfaceParseError(
+			'surface emit had no `questions` array (an empty array is valid; absence is not)',
+		);
+	}
+	const questions: SurfaceQuestion[] = obj.questions.map((q) => {
+		const item = (typeof q === 'object' && q !== null ? q : {}) as Record<
+			string,
+			unknown
+		>;
+		const question: SurfaceQuestion = {
+			question: typeof item.question === 'string' ? item.question : '',
+		};
+		if (typeof item.context === 'string' && item.context !== '') {
+			question.context = item.context;
+		}
+		if (typeof item.default === 'string' && item.default !== '') {
+			question.default = item.default;
+		}
+		return question;
+	});
+	return {
+		...(typeof obj.item === 'string' ? {item: obj.item} : {}),
+		// A question with an EMPTY `question` string carries no judgement — drop it
+		// (the agent may have emitted a placeholder), so an all-empty list is the
+		// same honest "no open judgement" as an empty array.
+		questions: questions.filter((q) => q.question.trim() !== ''),
+	};
+}
+
+/**
+ * Convert the emitted questions to the {@link NewQuestion} shape the engine
+ * appends to the sidecar — a 1:1 field map (the emit shape IS the sidecar
+ * authoring shape, by design), so the engine persists with ZERO translation.
+ */
+export function toNewQuestions(emit: SurfaceEmit): NewQuestion[] {
+	return emit.questions.map((q) => {
+		const nq: NewQuestion = {question: q.question};
+		if (q.context !== undefined) {
+			nq.context = q.context;
+		}
+		if (q.default !== undefined) {
+			nq.default = q.default;
+		}
+		return nq;
+	});
+}
+
+/**
+ * Render the surface-agent PROMPT: instruct a fresh-context agent to apply the
+ * **surface-questions discipline** (`work/protocol/SURFACE-PROTOCOL.md`) to ONE
+ * `work/` item and to EMIT a single `{item, questions}` JSON object (so
+ * {@link parseSurfaceEmit} can read it). The discipline body (the two laws —
+ * GATHER-only / PERSIST-NEVER — the humility rule, the composed sources, the
+ * emitted-question shape) lives in `SURFACE-PROTOCOL.md` — NOT inlined here
+ * (task `surface-protocol-doc-and-prompt`). The shape's source of truth is
+ * {@link parseSurfaceEmit}; the doc DESCRIBES it (D2).
+ *
+ * This builder owns ONLY the PER-BUILDER framing: who you are (a fresh-context
+ * question-surfacer, the engine's surface-question rung), what you are
+ * surfacing (ONE namespaced item), and the required JSON output shape. It
+ * MIRRORS {@link buildReviewPrompt}: a fresh-context agent that EDITS nothing
+ * and EMITS a single structured object the ENGINE routes/persists.
+ */
+export function buildSurfacePrompt(item: string): string {
+	return [
+		`You are a FRESH-CONTEXT question-surfacer for the work/ item "${item}".`,
+		`Apply the surface-questions discipline defined in`,
+		`\`work/protocol/SURFACE-PROTOCOL.md\` (the in-band, protocol-native`,
+		`surface-questions protocol every set-up repo carries; the human-facing`,
+		`pointer is \`skills/surface-questions/SKILL.md\`) to this ONE item:`,
+		`formulate its open questions and EMIT them. Its two laws, its humility`,
+		`aid, the composed sources you draw from, and the emitted-question shape`,
+		`ALL live in that doc — read them there.`,
+		`The skill JUDGES; the engine PERSISTS.`,
+		``,
+		`Do NOT edit any files, run no git — you EMIT questions only.`,
+		``,
+		`Your investigation may be substantial (you compose review's verdict, you`,
+		`probe an observation against current reality). Put ANY explanation,`,
+		`reasoning, or "here is what I found" prose IN the \`note\` field of the JSON`,
+		`below — that is its home. This MIRRORS Gate-2's verdict, which carries its`,
+		`human-readable prose in a \`review\` field for exactly this reason: with a`,
+		`channel for prose INSIDE the object, you never need to write anything`,
+		`around it.`,
+		``,
+		`The single JSON object below MUST be your FINAL and ONLY output. Do NOT`,
+		`narrate your process ("Let me check…"), do NOT add any remark, summary, or`,
+		`sign-off BEFORE or AFTER it, and do NOT take any further turn once you have`,
+		`emitted it — emitting the object is how you finish. A trailing chatty turn`,
+		`after the object strands the run (the reader sees only your last turn).`,
+		``,
+		`Output ONLY a single JSON object of this exact shape (no prose OUTSIDE it;`,
+		`see \`SURFACE-PROTOCOL.md\` → "The emitted question shape" for the`,
+		`prose-described contract this mirrors). The example below is EXPANDED over`,
+		`several lines for READABILITY, but you MUST emit it MINIFIED — ONE single`,
+		`line, no newlines between the keys:`,
+		``,
+		'```json',
+		`{"item": "${item}",`,
+		` "questions": [`,
+		`   {"question": "…",`,
+		`    "context": "…",`,
+		`    "default": "… (optional; omit if none)"}`,
+		` ],`,
+		` "note": "… (optional; your reasoning / findings prose lives HERE, not outside the object)"}`,
+		'```',
+		``,
+		`An EMPTY \`questions\` array is a VALID, honest result (no open judgement) —`,
+		`emit the object with \`"questions": []\` (put WHY in \`note\`); do NOT replace`,
+		`it with a prose explanation. Absence of the field is NOT valid.`,
+		``,
+		// The SHARED defensive-JSON contract (the same hardening Gate-2's verdict
+		// prompt carries) — the surface rung hit the IDENTICAL unparseable-emit
+		// failure the verdict gate did, so it reuses the one contract rather than
+		// staying the lone un-hardened seam. The longest field is `note` (the free
+		// prose channel, the surface counterpart of the verdict's `review`).
+		parseableJsonContractPrompt('result', 'note'),
+	].join('\n');
+}
+
+/** What a harness-backed surface gate needs to launch the surface agent. */
+export interface HarnessSurfaceGateOptions {
+	/** The harness seam used to launch the fresh-context surface agent. */
+	harness?: Harness;
+	/** The agent command the null/shell adapter shells out to (`{model}`-aware). */
+	agentCmd?: string;
+	/**
+	 * Read the surface agent's textual output for parsing. Production reads
+	 * `launched.output` (the ANSWER channel, distinct from `detail`); tests inject
+	 * `readOutput` to stub a canned emit string.
+	 */
+	readOutput?: (output: string | undefined) => string;
+}
+
+/**
+ * The PRODUCTION surface gate: launch the `surface-questions` SKILL as a
+ * fresh-context agent through the EXISTING harness seam, routing the
+ * `surfaceModel` override via `LaunchInput.model` (the §13 model-routing intent —
+ * NOT a new mechanism), then parse the emitted `{item, questions}`. It is the
+ * DIRECT mirror of `harnessReviewGate`: a SEPARATE harness launch (fresh context
+ * = not the engine's session) in the same checkout `cwd`, fed
+ * {@link buildSurfacePrompt}; the model flows through `LaunchInput.model`, which
+ * each adapter injects natively. The surface uses a DISTINCT session id
+ * (`<item>-surface`) so its session never collides with a build/review session.
+ */
+export function harnessSurfaceGate(
+	options: HarnessSurfaceGateOptions = {},
+): SurfaceGate {
+	const harness = options.harness ?? new NullHarness();
+	const readOutput = options.readOutput ?? ((output) => output ?? '');
+	return async (input: SurfaceGateInput): Promise<SurfaceEmit> => {
+		if (input.watch === true) {
+			const sink =
+				input.watchSink ??
+				((line: string) => process.stderr.write(`${line}\n`));
+			sink(
+				boundaryLine(
+					`surface — gathering questions for ${input.item}…`,
+					input.color ?? false,
+				),
+			);
+		}
+		// A safe session-id stem (the namespaced identity has a `:` that is not a
+		// valid path stem). The same `:`→`-` convention the sidecar/lock identity uses.
+		const sessionId = `${input.item.replace(/:/g, '-')}-surface`;
+		const launched = await launchWithOptionalWatch({
+			harness,
+			dir: input.cwd,
+			slug: input.item,
+			command: options.agentCmd ?? '',
+			prompt: buildSurfacePrompt(input.item),
+			model: input.surfaceModel,
+			sessionId,
+			sessionsDir: input.sessionsDir,
+			watch: input.watch,
+			watchSink: input.watchSink,
+			color: input.color,
+			env: input.env,
+		});
+		if (!launched.ok) {
+			throw new SurfaceParseError(
+				`surface agent launch failed${launched.detail ? `: ${launched.detail}` : ''}`,
+			);
+		}
+		// Read the emit from the agent's ANSWER channel (`output`), NOT `detail`
+		// (empty on success). An empty/absent output → parseSurfaceEmit throws → the
+		// engine surfaces nothing and reports it (never a silent success).
+		return parseSurfaceEmit(readOutput(launched.output));
+	};
+}

package/src/surface-persist.ts

@@ -0,0 +1,241 @@
+import {existsSync, mkdirSync, readFileSync, writeFileSync} from 'node:fs';
+import {dirname, join} from 'node:path';
+import {run, type RunResult} from './git.js';
+import {parseFrontmatter, setNeedsAnswersMarker} from './frontmatter.js';
+import {
+	appendQuestions,
+	newSidecar,
+	parseSidecar,
+	serialiseSidecar,
+	sidecarPathFor,
+	type NewQuestion,
+	type SidecarModel,
+} from './sidecar.js';
+
+/**
+ * The engine-owned SURFACE PERSIST (prd `advance-loop`, task
+ * `advance-rung-surface`, US #15/33) — the half of the surface rung the ENGINE
+ * owns (the skill JUDGES, the engine PERSISTS). Given the questions the
+ * `surface-questions` skill EMITTED (gathered by `surface-gate.ts`'s spawn), the
+ * engine writes them to the sidecar `work/questions/<type>-<slug>.md` and sets
+ * `needsAnswers:true` on the item body — in ONE commit, exactly as the review
+ * gate persists a verdict and `applyAtomic` resolves an answer batch in one
+ * commit.
+ *
+ * It is the SIBLING of {@link import('./sidecar-apply.js').applyAtomic}: that is
+ * the APPLY rung's one-commit primitive (resolve/re-pause); this is the SURFACE
+ * rung's one-commit primitive (append-or-create + set `needsAnswers`). Kept in a
+ * SEPARATE module so the surface rung's persist and the apply rung's persist stay
+ * file-orthogonal (the rung bodies land in different tasks).
+ *
+ * The load-bearing rules (the task's acceptance criteria):
+ *
+ *   - **Append-never-overwrite (US #15).** When a sidecar ALREADY exists, the new
+ *     questions are APPENDED ({@link appendQuestions} mints `qN+1…`), NEVER
+ *     overwriting an existing (answered or unanswered) entry. A re-surface that
+ *     adds questions to a previously-all-answered sidecar FLIPS it back to
+ *     not-all-answered (the appended entries are pending).
+ *   - **Set `needsAnswers:true` atomically (invariant 1).** The item body's
+ *     `needsAnswers` flag is set to `true` in the SAME commit the sidecar is
+ *     written, so the `needsAnswers:true ⟺ active sidecar` invariant holds the
+ *     instant the commit lands.
+ *   - **Identity-keyed sidecar path.** The sidecar path derives PURELY from the
+ *     item's namespaced identity ({@link sidecarPathFor}) — it survives the item's
+ *     `git mv`s with no lock-step move.
+ *
+ * This is the LOCAL one-commit primitive over a working tree (the
+ * throwaway-git-repo test pattern the apply/lock tests use). The `advancing` CAS
+ * lock that makes this WINNER-ONLY is held by `performAdvance` BEFORE this is
+ * called — so the expensive spawn + this persist are both POST-lock. This module
+ * does NOT race the arbiter; that is the lock's job.
+ */
+
+export interface SurfacePersistOptions {
+	/** Working clone/worktree the persist commits in. */
+	cwd: string;
+	/** The namespaced item identity (`task:foo` / `prd:bar` / `observation:baz`). */
+	item: string;
+	/**
+	 * The item file path RELATIVE to `cwd` (e.g. `work/backlog/foo.md`). The
+	 * `needsAnswers:true` flag is set on THIS file; the sidecar path is derived
+	 * from the identity, NOT from this path.
+	 */
+	itemPath: string;
+	/** The questions the `surface-questions` skill emitted (engine appends them). */
+	questions: NewQuestion[];
+	/** Advisory committer id for the commit subject. Defaults to git user.name. */
+	by?: string;
+	/** Environment for child git processes. */
+	env?: NodeJS.ProcessEnv;
+	/** Sink for human-readable progress notes. */
+	note?: (message: string) => void;
+}
+
+export interface SurfacePersistResult {
+	/** `surfaced` (questions written + needsAnswers set) or `nothing` (empty emit). */
+	outcome: 'surfaced' | 'nothing';
+	/** The commit sha the persist produced (`undefined` on a `nothing` no-op). */
+	commit?: string;
+	/** The sidecar path (relative to `cwd`) the persist touched. */
+	sidecarPath: string;
+	/** How many entries the sidecar carries after this persist. */
+	entryCount: number;
+}
+
+/** Raised for usage errors (a missing repo, an unreadable item). */
+export class SurfacePersistError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'SurfacePersistError';
+	}
+}
+
+function gitSoft(
+	args: string[],
+	cwd: string,
+	env: NodeJS.ProcessEnv | undefined,
+): RunResult {
+	return run('git', args, cwd, {env});
+}
+
+function gitHard(
+	args: string[],
+	cwd: string,
+	env: NodeJS.ProcessEnv | undefined,
+): RunResult {
+	const result = run('git', args, cwd, {env});
+	if (result.status !== 0) {
+		throw new SurfacePersistError(
+			`git ${args.join(' ')} failed (exit ${result.status}): ${result.stderr.trim()}`,
+		);
+	}
+	return result;
+}
+
+function resolveBy(cwd: string, env: NodeJS.ProcessEnv | undefined): string {
+	const name = gitSoft(['config', 'user.name'], cwd, env);
+	if (name.status === 0 && name.stdout.trim() !== '') {
+		return name.stdout.trim();
+	}
+	const e = env ?? process.env;
+	return e.USER ?? e.USERNAME ?? '';
+}
+
+/**
+ * Persist the SURFACED questions ATOMICALLY: APPEND them to the existing sidecar
+ * (or CREATE it first-pass), and set `needsAnswers:true` on the item body — ONE
+ * commit. An EMPTY question set is a clean NO-OP (no sidecar written, the item
+ * untouched): the honest "no open judgement" result the skill is allowed to
+ * emit; nothing to commit, so `needsAnswers` is NOT set.
+ *
+ * Append-never-overwrite: when a sidecar exists, the new questions are APPENDED
+ * (never mutating an answered entry); a re-surface flips a previously-all-answered
+ * sidecar back to not-all-answered. Returns the produced commit + the resulting
+ * entry count.
+ */
+export function persistSurfacedQuestions(
+	options: SurfacePersistOptions,
+): SurfacePersistResult {
+	const {cwd, item, itemPath, questions, env} = options;
+	const note = options.note ?? (() => {});
+
+	if (gitSoft(['rev-parse', '--git-dir'], cwd, env).status !== 0) {
+		throw new SurfacePersistError('not inside a git repository');
+	}
+
+	const sidecarPath = sidecarPathFor(item);
+	const sidecarAbs = join(cwd, sidecarPath);
+
+	// Build the post-persist sidecar model: APPEND to an existing one (never
+	// overwrite), else CREATE first-pass. Read the current sidecar from the tree
+	// so the append is over the COMMITTED history (identity-keyed, folder-agnostic).
+	let model: SidecarModel;
+	const existing = readExistingSidecar(sidecarAbs);
+	if (existing !== undefined) {
+		model = appendQuestions(existing, questions);
+	} else {
+		model = newSidecar(item, questions);
+	}
+
+	// An empty emit ⇒ the sidecar would carry no entries: surface NOTHING (the
+	// honest result). Do NOT write a sidecar or set `needsAnswers` — a sidecar with
+	// no open questions should not exist (it keeps invariant 1 + the "pending ⇒
+	// NO-OP" classifier honest).
+	if (model.entries.length === 0) {
+		const message = `surface ${item}: no open judgement — nothing surfaced (no sidecar written).`;
+		note(message);
+		return {outcome: 'nothing', sidecarPath, entryCount: 0};
+	}
+
+	// Set `needsAnswers:true` on the item body (the only in-body signal — the
+	// sidecar path is identity-derived, no back-pointer). The item file may not
+	// have a `needsAnswers` line yet (and may be fence-less — observations are born
+	// that way); `setNeedsAnswersMarker` prepends a fence when needed and is
+	// idempotent otherwise.
+	const itemAbs = join(cwd, itemPath);
+	const itemBody = readItem(itemAbs, cwd, itemPath, env);
+	const flagged = setNeedsAnswersMarker(itemBody, true);
+
+	// DEFENSE IN DEPTH (the `sidecar-without-needsAnswers` guard): the surface
+	// commit is only atomic if the flag ACTUALLY landed. If — for any reason — the
+	// flag did not parse back as `true` (e.g. a degenerate body the marker writer
+	// cannot annotate), ABORT BEFORE writing the sidecar, so we never produce the
+	// torn invariant (sidecar present, flag absent) a later tick refuses to advance.
+	if (parseFrontmatter(flagged).needsAnswers !== true) {
+		throw new SurfacePersistError(
+			`surface ${item}: could not set needsAnswers:true on '${itemPath}' ` +
+				`(the item body could not be annotated) — refusing to write the sidecar ` +
+				`without the flag (that would tear the needsAnswers ⟺ sidecar invariant).`,
+		);
+	}
+	writeFileSync(itemAbs, flagged);
+
+	// Write the appended/created sidecar.
+	mkdirSync(dirname(sidecarAbs), {recursive: true});
+	writeFileSync(sidecarAbs, serialiseSidecar(model));
+
+	// Stage exactly the two paths and commit them TOGETHER (one atomic commit) —
+	// the sidecar write + the `needsAnswers:true` flip land in the SAME commit, so
+	// `needsAnswers:true ⟺ active sidecar` holds the instant it lands.
+	const by = options.by || resolveBy(cwd, env);
+	gitHard(['add', '--', itemPath, sidecarPath], cwd, env);
+	const subject = `advance: surface ${item} (${model.entries.length} question(s), by ${by})`;
+	gitHard(['commit', '--quiet', '-m', subject], cwd, env);
+	const commit = gitHard(['rev-parse', 'HEAD'], cwd, env).stdout.trim();
+	note(subject);
+
+	return {
+		outcome: 'surfaced',
+		commit,
+		sidecarPath,
+		entryCount: model.entries.length,
+	};
+}
+
+/** Read + parse the existing sidecar (from the tree, then the working file). */
+function readExistingSidecar(sidecarAbs: string): SidecarModel | undefined {
+	if (!existsSync(sidecarAbs)) {
+		return undefined;
+	}
+	return parseSidecar(readFileSync(sidecarAbs, 'utf8'));
+}
+
+/** Read the item body from the tree (committed) then the working-tree file. */
+function readItem(
+	itemAbs: string,
+	cwd: string,
+	itemPath: string,
+	env: NodeJS.ProcessEnv | undefined,
+): string {
+	const show = gitSoft(['show', `:${itemPath}`], cwd, env);
+	if (show.status === 0) {
+		return show.stdout;
+	}
+	try {
+		return readFileSync(itemAbs, 'utf8');
+	} catch {
+		throw new SurfacePersistError(
+			`cannot read item body for '${itemPath}' (the surface rung needs the item file)`,
+		);
+	}
+}