dorfl 0.11.3 → 0.13.0

package/src/advance.ts

@@ -32,10 +32,13 @@ import type {ObservationTriage} from './config.js';
 import {
 	autoDispositionObservation,
 	promoteObservation,
+	stampTriagedMarker,
 	type AutoDispositionOptions,
 	type AutoDispositionResult,
 	type PromoteObservationOptions,
 	type PromoteObservationResult,
+	type StampTriagedMarkerOptions,
+	type StampTriagedMarkerResult,
 } from './triage-persist.js';
 import {mintAdr, type MintAdrOptions, type MintAdrResult} from './mint-adr.js';
 import {LIFECYCLE_CAS_CONTENTION} from './advancing-lock.js';
@@ -57,6 +60,8 @@ import {
 } from './surface-persist.js';
 import {
 	applyAnsweredQuestions,
+	hasAppliedAnswersRecord,
+	TRIAGED_RESOLVE,
 	type ApplyAnsweredQuestionsOptions,
 	type ApplyAnsweredQuestionsResult,
 } from './apply-persist.js';
@@ -324,6 +329,15 @@ export interface AdvanceContext {
 	 * commit). Tests inject a spy; production uses {@link autoDispositionObservation}.
 	 */
 	autoDisposition?: (options: AutoDispositionOptions) => AutoDispositionResult;
+	/**
+	 * Back-stamp the `triaged:` settled marker on a note that was ALREADY
+	 * resolved-and-kept before the apply rung learned to stamp it (the legacy arm of
+	 * the triage rung's settled guard). Tests inject a spy; production uses
+	 * {@link stampTriagedMarker}.
+	 */
+	stampTriaged?: (
+		options: StampTriagedMarkerOptions,
+	) => StampTriagedMarkerResult;
 	/**
 	 * Promote an answered observation: CAS-create a new backlog stub keyed on the
 	 * NEW item's identity, then record + resolve the observation. Tests inject a
@@ -910,10 +924,20 @@ async function triageRung(input: RungExecInput): Promise<RungExecResult> {
 	// note. (Replaces the old `detectObservationLimbo` special-case: there is no
 	// limbo any more — an UNtriaged observation always surfaces the deterministic
 	// question below; a SETTLED one is a calm no-op here.)
+	//
+	// SECOND ARM — the LEGACY back-fill (ADR
+	// `resolve-settles-the-question-loop-not-the-note`): a note the apply rung
+	// resolved-and-KEPT before it learned to stamp the marker carries the
+	// ENGINE-WRITTEN `## Applied answers` record but NO marker, which is the exact
+	// shape this rung would re-ask forever. That record is PROOF the engine already
+	// applied a human's answers to this note, so we stamp what the apply rung would
+	// have written and no-op. Self-healing and one-shot: the stamped note drops out
+	// of the pool, so this arm can never fire twice for the same note.
 	{
 		const itemRel = findItemPath(cwd, input.namespace, input.slug);
 		if (itemRel !== undefined) {
-			const fm = parseFrontmatter(readFileSync(join(cwd, itemRel), 'utf8'));
+			const body = readFileSync(join(cwd, itemRel), 'utf8');
+			const fm = parseFrontmatter(body);
 			if (fm.triaged !== undefined && fm.triaged !== '') {
 				return {
 					exitCode: 0,
@@ -921,6 +945,21 @@ async function triageRung(input: RungExecInput): Promise<RungExecResult> {
 					message: `triage ${item}: already triaged (triaged:${fm.triaged}) — nothing to do.`,
 				};
 			}
+			if (hasAppliedAnswersRecord(body)) {
+				const stamp = context.stampTriaged ?? stampTriagedMarker;
+				const result = stamp({
+					cwd,
+					item,
+					itemPath: itemRel,
+					value: TRIAGED_RESOLVE,
+					reason:
+						'Back-filled: the note carries an engine-written applied-answers ' +
+						'record, so its triage question-loop was already settled by a human ' +
+						'answer before the apply rung stamped the marker.',
+					note,
+				});
+				return {exitCode: 0, outcome: 'no-op', message: result.message};
+			}
 		}
 	}
 
@@ -951,9 +990,10 @@ async function triageRung(input: RungExecInput): Promise<RungExecResult> {
 		if (decision.auto === true) {
 			// A no-question case (duplicate / map) — auto-disposition WITHOUT a
 			// question. BOTH discharge the redundant note BY DELETION (a duplicate is a
-			// redundant copy; a map is already covered by the item it maps onto). There
-			// is no resting `triaged:keep` state any more. NEVER auto-deletes a
-			// NON-redundant signal; NEVER auto-promotes.
+			// redundant copy; a map is already covered by the item it maps onto), so an
+			// AUTO disposition never RESTS a note — resting a KEPT note is the
+			// human-answered `resolve` verdict's job on the apply rung. NEVER auto-deletes
+			// a NON-redundant signal; NEVER auto-promotes.
 			const dispose = context.autoDisposition ?? autoDispositionObservation;
 			const result = dispose({
 				cwd,
@@ -1654,6 +1694,14 @@ async function applyAgenticDecision(
 		// the sibling of `dispose`, which git-rm's it or moves it to a terminal). `resolveReason` is advisory
 		// context only; the durable disposition record is the harvested `## Applied
 		// answers` block the resolve-fully path writes (NOT a separate convention).
+		//
+		// Because the note is KEPT, that same commit also stamps `triaged: resolve` on
+		// it (ADR `resolve-settles-the-question-loop-not-the-note`): a kept note stays
+		// in the inbox the triage rung scans, and without the marker its two
+		// classifier signals (`needsAnswers:false`, no sidecar) are IDENTICAL to a note
+		// that was never triaged — so the next tick re-surfaced the same engine-built
+		// triage question forever. The stamp is done by the persist, not here, so no
+		// caller of the resolve-fully path can forget it.
 		const apply = context.applyPersist ?? applyAnsweredQuestions;
 		try {
 			const result = apply({cwd, item, itemPath, note});

package/src/apply-decide.ts

@@ -40,7 +40,13 @@ import {
  * by the task `apply-decide-resolve-verdict-mint-nothing` so the decider can
  * honestly handle "the human answered, keep the note on record, mint nothing"
  * (previously it had no valid verdict for that case and looped on `ask`,
- * re-surfacing an already-answered question every tick). `adr` was DEFERRED at the
+ * re-surfacing an already-answered question every tick). Its MEANING was SHARPENED
+ * by ADR `resolve-settles-the-question-loop-not-the-note`: `resolve` settles the
+ * QUESTION-LOOP on a note that REMAINS a live signal (and the persist stamps
+ * `triaged:` so the triage rung stops re-asking it, closing a second re-ask loop
+ * the first fix left open); a note whose SIGNAL is finished is `dispose`, not
+ * `resolve` — a dead note kept and stamped "resolved" is exactly the
+ * backward-artifact-in-a-forward-bucket the work contract forbids. `adr` was DEFERRED at the
  * keystone launch (no
  * ADR-mint path existed yet) and is now WIRED by the follow-on task
  * `agentic-apply-mint-adr-route`, which added the {@link
@@ -201,15 +207,22 @@ export function buildApplyDecisionPrompt(input: ApplyDecisionInput): string {
 		`    \`reason:\` frontmatter); a SPEC is git-mv-ed to \`specs/dropped/\` (RETAINED).`,
 		`    A task can NEVER be hard-deleted by the apply rung \u2014 dispose is the`,
 		`    only path off the board.`,
-		`  - "resolve": the answer SETTLES this item and there is NOTHING to mint (no`,
-		`    task/spec/adr) \u2014 the correct move is to CLOSE the question-loop while`,
-		`    KEEPING the note on record (e.g. an evidence/watch-item observation whose`,
-		`    answer is "acknowledged, keep this on record, no artifact"). The answers are`,
-		`    harvested into the item body and the loop is cleared; the note is RETAINED`,
-		`    (this is the sibling of "dispose", which DROPS the observation-note or`,
-		`    moves a task/spec to its terminal \u2014 pick "resolve" when the observation`,
-		`    should SURVIVE in place, "dispose" when it should not). Emit`,
-		`    {"outcome":"resolve","resolveReason":"\u2026"}.`,
+		`  - "resolve": the answer SETTLES the QUESTION-LOOP and there is NOTHING to`,
+		`    mint (no task/spec/adr), AND the note is STILL A LIVE SIGNAL worth keeping`,
+		`    in the inbox \u2014 e.g. a standing map of a known gap, or accepted residue the`,
+		`    answer explicitly says to keep on record until it is acted on. The answers`,
+		`    are harvested into the item body, the loop is cleared, and the note is`,
+		`    RETAINED and STAMPED as triaged, so it is never re-asked this question.`,
+		`    Emit {"outcome":"resolve","resolveReason":"\u2026"}.`,
+		`    PICK BETWEEN "resolve" AND "dispose" ON LIVENESS, NOT ON POLITENESS: both`,
+		`    close the loop and mint nothing, and the ONLY question is whether the note`,
+		`    is still a live signal AFTER this answer. If the answer means the signal is`,
+		`    FINISHED (the thing was fixed, it was already covered elsewhere, it is`,
+		`    obsolete, or its whole content is now carried by a task/spec/ADR/commit),`,
+		`    that note stops being live \u2014 emit "dispose", NOT "resolve". "resolve" is`,
+		`    only correct when the note still carries a signal nothing else records.`,
+		`    Do NOT use "resolve" as a soft "dispose": a note kept only to show it was`,
+		`    handled is a backward artifact in a forward bucket.`,
 		`  - "ask": you need more from the human before acting. Emit`,
 		`    {"outcome":"ask","question":"\u2026"} \u2014 ask everything you still need as ONE`,
 		`    batch (never a drip); the engine appends it and re-pauses.`,

package/src/apply-persist.ts

@@ -42,17 +42,26 @@ import {workItemRel} from './work-layout.js';
  *     hard-deleted from here — dispose is the only path off the board; OR
  *   - **resolve fully** (the default) — clear `needsAnswers` + DELETE the sidecar
  *     in the SAME atomic commit (the invariant `needsAnswers:false ⟺ no active
- *     sidecar`); the item advances toward build by its normal lifecycle.
+ *     sidecar`); the item advances toward build by its normal lifecycle. For an
+ *     OBSERVATION this ALSO stamps the `triaged:` settled marker (see
+ *     {@link TRIAGED_RESOLVE}) in that same commit — the note is KEPT, so it needs
+ *     a durable record that its triage question-loop is CLOSED or the triage rung
+ *     re-asks it forever (ADR `resolve-settles-the-question-loop-not-the-note`).
  *
  * **The disposition vocabulary is GONE** (task
  * `agentic-apply-retire-disposition-vocabulary`): the apply rung no longer reads a
- * per-entry `disposition=` token, no longer runs a most-decisive picker, and has
- * no `keep`/`triaged:keep` resting state. A sidecar entry is BINARY (no-answer |
- * answered); what to DO with a fully-answered OBSERVATION is decided by the
- * AGENTIC apply decision in the advance tick (`advance.ts` `applyRung` over the
- * shared `decide` engine), which then routes here (re-pause / dispose / via
- * `promoteObservation` for a mint). A signal is still-open, acted-on, or deleted
- * — there is no \"retain as resolved\" state.
+ * per-entry `disposition=` token and no longer runs a most-decisive picker. A
+ * sidecar entry is BINARY (no-answer | answered); what to DO with a fully-answered
+ * OBSERVATION is decided by the AGENTIC apply decision in the advance tick
+ * (`advance.ts` `applyRung` over the shared `decide` engine), which then routes
+ * here (re-pause / dispose / resolve / via `promoteObservation` for a mint).
+ *
+ * What the retirement removed was the human-stamped `disposition=`/`promote-*`
+ * TOKEN vocabulary, NOT the settled AXIS: a note that the `resolve` verdict KEEPS
+ * still rests as `triaged: resolve` + `needsAnswers:false` + no sidecar. That is
+ * the one resting state a note has, and it says "the question-loop is settled",
+ * NOT "the signal is finished" (a finished signal is `dispose`d — it leaves the
+ * inbox by deletion).
  *
  * The work-item (task/spec) terminal MOVES (`tasks/cancelled`, `specs/dropped`) and
  * the stuck (lock `state: stuck`) LIFECYCLE state are a SEPARATE lifecycle concern (a
@@ -87,6 +96,32 @@ export {APPLY_LIFECYCLE_FOLDERS, resolveItemPathByIdentity};
 /** Marker that opens the applied-answers record in an item body. */
 const APPLIED_HEADING = '## Applied answers';
 
+/**
+ * The `triaged:` settled-marker VALUE the resolve-fully path stamps on a KEPT
+ * OBSERVATION (ADR `resolve-settles-the-question-loop-not-the-note`).
+ *
+ * The `resolve` verdict is the ONE apply terminal that RETAINS an observation in
+ * the inbox. Every other terminal removes it from the triage pool by MOVING or
+ * DELETING the file (mint → `git rm` + the new artifact; dispose → `git rm` /
+ * terminal folder), so only this one needs an in-file record that the note has
+ * been through triage. Without it the resolved note is byte-indistinguishable, to
+ * the classifier's two signals (`needsAnswers` + sidecar), from a note that was
+ * NEVER triaged: `needsAnswers:false` + no sidecar ⇒ ANALYSE ⇒ `triage-observation`
+ * ⇒ the engine-built triage question is surfaced AGAIN, and the human is asked
+ * something they already answered (observed live in the `rocketh` consumer repo:
+ * surface → answer → resolve → the byte-identical question re-surfaced).
+ *
+ * The marker is the axis the READ side already models end-to-end — `frontmatter.ts`
+ * parses it, `ledger-read.ts` carries it, `lifecycle-pools.ts` drops a marked
+ * observation out of the CREATE-side triage pool, and `advance.ts`'s triage rung
+ * no-ops on it for an explicit `obs:<slug>`. Only the WRITER was missing.
+ *
+ * It does NOT strand a later answer: an ANSWERED sidecar dominates the marker (ADR
+ * `answered-observation-sidecar-dominates-triaged-marker`), so a genuinely NEW
+ * question about a settled note still routes to apply and is still answerable.
+ */
+export const TRIAGED_RESOLVE = 'resolve';
+
 /**
  * The STRUCTURAL fence the templates wrap the transient open-questions block in
  * — an HTML-comment marker pair, mirroring the existing `<!-- dorfl-…
@@ -108,6 +143,21 @@ const APPLIED_HEADING = '## Applied answers';
 export const OPEN_QUESTIONS_MARKER_OPEN = '<!-- open-questions -->';
 export const OPEN_QUESTIONS_MARKER_CLOSE = '<!-- /open-questions -->';
 
+/**
+ * Does this item body carry the ENGINE-WRITTEN applied-answers record?
+ *
+ * Only {@link applyAnsweredQuestions} writes this heading, and only after a human
+ * answered EVERY open question on the item, so its presence is PROOF the engine
+ * has applied a human's answers here — not a prose heuristic. The triage rung uses
+ * it as the legacy back-fill trigger for notes resolved-and-kept before the
+ * `triaged:` stamp existed (ADR `resolve-settles-the-question-loop-not-the-note`).
+ */
+export function hasAppliedAnswersRecord(body: string): boolean {
+	return new RegExp(`^${APPLIED_HEADING}\\b`, 'm').test(
+		body.replace(/\r\n/g, '\n'),
+	);
+}
+
 export interface ApplyAnsweredQuestionsOptions {
 	/** Working clone/worktree the apply commits in. */
 	cwd: string;
@@ -490,7 +540,10 @@ export function applyAnsweredQuestions(
 	// compatible — no marker ⇒ identical bytes. The re-pause path above is
 	// deliberately untouched (D3): its open-questions block is still open.
 	const reconciledBody = stripOpenQuestionsBlocks(baseBody);
-	const resolvedBody = withAppliedAnswers(reconciledBody, model.entries);
+	const resolvedBody = withTriagedMarkerIfKeptNote(
+		withAppliedAnswers(reconciledBody, model.entries),
+		item,
+	);
 	const result = applyAtomic({
 		cwd,
 		itemPath,
@@ -512,6 +565,30 @@ export function applyAnsweredQuestions(
 	};
 }
 
+/**
+ * Stamp the `triaged:` settled marker on a resolve-fully body — but ONLY for an
+ * OBSERVATION (the one item type this path KEEPS in a re-scanned inbox).
+ *
+ * Structural, not caller-supplied, so it cannot be forgotten by a future caller:
+ * every route that reaches the resolve-fully branch with an observation identity
+ * has, by definition, just closed that note's question-loop while retaining the
+ * file. A TASK/SPEC is deliberately EXCLUDED — it rests in a lifecycle FOLDER (its
+ * status), is not enumerated from the observation inbox, and has no triage rung to
+ * re-ask it; stamping a triage marker on one would invent a second status axis for
+ * an item whose status is already the folder.
+ *
+ * Idempotent ({@link setFrontmatterMarker} replaces an existing key) and
+ * fence-creating (observations are routinely born fence-less), so re-resolving a
+ * note after a genuinely new question re-stamps rather than duplicating.
+ */
+function withTriagedMarkerIfKeptNote(body: string, item: string): string {
+	const {type} = resolveSidecarIdentity(item);
+	if (type !== 'observation') {
+		return body;
+	}
+	return setFrontmatterMarker(body, 'triaged', TRIAGED_RESOLVE);
+}
+
 interface DisposeInput {
 	cwd: string;
 	item: string;

package/src/frontmatter.ts

@@ -94,13 +94,20 @@ export interface Frontmatter {
 	 */
 	needsAnswers: boolean | undefined;
 	/**
-	 * The triage SETTLED marker (US #30). A non-empty `triaged:` value (e.g.
-	 * `keep` / `duplicate`) means a human (or the conservative auto-disposition)
-	 * has SETTLED this observation, so it DROPS OUT of the triage candidate pool
-	 * and is never re-asked. `undefined` when omitted (an UNTRIAGED observation,
-	 * still in the pool). Carried so the lifecycle-pool enumeration
-	 * (`advance-autopick-lifecycle-pools`) can exclude settled observations from
-	 * the triage selection.
+	 * The triage SETTLED marker (US #30). A non-empty `triaged:` value means this
+	 * observation's triage QUESTION-LOOP has been settled by a human's answer, so it
+	 * DROPS OUT of the triage candidate pool and is never re-asked. `undefined` when
+	 * omitted (an UNTRIAGED observation, still in the pool). Carried so the
+	 * lifecycle-pool enumeration (`advance-autopick-lifecycle-pools`) can exclude
+	 * settled observations from the triage selection.
+	 *
+	 * The one WRITER today is the apply rung's `resolve` verdict, which stamps
+	 * `triaged: resolve` on a note it settles and KEEPS (ADR
+	 * `resolve-settles-the-question-loop-not-the-note`). It says the question-loop is
+	 * settled, NOT that the signal is finished — a finished signal has no resting
+	 * state at all (it is deleted), and an ANSWERED sidecar still dominates this
+	 * marker (ADR `answered-observation-sidecar-dominates-triaged-marker`), so a
+	 * genuinely new question about a settled note is still asked and answered.
 	 */
 	triaged: string | undefined;
 	/** Slugs this item is blocked by; `[]` when omitted or empty. */
@@ -241,9 +248,9 @@ export function setNeedsAnswersMarker(content: string, value: boolean): string {
 /**
  * Set (or replace) a top-level scalar `<key>: <value>` frontmatter marker on a
  * `work/` markdown document, returning the new content. The generalised form of
- * {@link setNeedsAnswersMarker} the advance APPLY rung uses to stamp a
- * `triaged: keep` marker (US #30) on an item a human answered "keep" — so a
- * settled observation drops out of the candidate pool and is never re-asked. If a
+ * {@link setNeedsAnswersMarker} the advance APPLY rung uses to stamp the
+ * `triaged: resolve` marker (US #30) on a note a human's answer settles but KEEPS
+ * — so a settled observation drops out of the candidate pool and is never re-asked. If a
  * `<key>:` line already exists it is REPLACED (idempotent); otherwise it is
  * appended as the last line inside the frontmatter fence.
  *

package/src/integration-core.ts

@@ -28,6 +28,7 @@ import {
 	reviewRoundsExhaustedReason,
 } from './review-gate.js';
 import {type IntegrateResult, type ReviewProvider} from './integrator.js';
+import {extractDecisionsBlock} from './agent-stop.js';
 import {ledgerWrite} from './ledger-write.js';
 import {selectProvider} from './github.js';
 import type {IntegrationMode} from './config.js';
@@ -1104,6 +1105,20 @@ export async function performIntegration(
 		);
 	}
 
+	// 2b. TRANSCRIBE the agent's `## Decisions` block into the DONE RECORD (the
+	//     builder's rationale channel, WORK-CONTRACT "Where a BUILDER's RATIONALE
+	//     lives"). The builder does NO git and MUST NOT edit the task body, and the
+	//     done-move is ours, so "record your rationale in the done record" is an
+	//     instruction it CANNOT obey directly. It emits a `## Decisions` block on the
+	//     one surface it owns (its final report, reaching us as `input.body`), and we
+	//     append it here: AFTER the move (so we write the record at its DONE path) and
+	//     BEFORE the `git add -A` below (so it rides the SAME atomic completion commit,
+	//     not a second one). Skipped for a TASKING transition (`lifecycle`), which
+	//     lands a spec: no done record, and no building agent.
+	if (!lifecycle) {
+		transcribeDecisionsIntoDoneRecord({cwd, slug, output: input.body, note});
+	}
+
 	// 3. Commit: git add -A (the agent's uncommitted work + the move) into ONE
 	//    atomic commit. Nothing to commit is FATAL (no-op-is-fatal, like claim.sh).
 	await gitHard(['add', '-A'], cwd, env);
@@ -2530,6 +2545,68 @@ const CAPTURE_NOTE_DIRS = [
 	workFolderPrefix('findings'),
 ] as const;
 
+/**
+ * TRANSCRIBE the build agent's `## Decisions` block into the DONE RECORD: the
+ * runner half of the builder's rationale channel (WORK-CONTRACT.md, "Where a
+ * BUILDER's RATIONALE lives").
+ *
+ * The builder MUST surface a non-obvious in-scope decision for ratification, but
+ * every home the contract used to offer it was UNREACHABLE: it does no git, it must
+ * not edit the task body (`CLAIM-PROTOCOL.md`), and the done-move, the completion
+ * commit and the PR body are all the RUNNER's. So an acceptance criterion like
+ * "rationale recorded in the done record" was structurally unsatisfiable, and the
+ * rationale scattered into a JSDoc, a changeset, or an invented
+ * `work/notes/observations/decisions-<slug>.md` note (a BACKWARD artifact in a LIVE,
+ * FORWARD bucket, so it can never be discharged). Reviewers then re-raised the
+ * identical "no Decisions block in the done record" finding on task after task.
+ *
+ * The fix is structural, not exhortative: the builder emits the block on the ONE
+ * surface it owns (its final report, which reaches us as `input.body`), and the
+ * runner, already the owner of the done-move, appends it here. Properties that
+ * matter:
+ *
+ *   - **Same commit.** The caller invokes this AFTER the `git mv` (so the record is
+ *     written at its `tasks/done/` path) and BEFORE `git add -A` (so it rides the
+ *     ONE atomic completion commit, never a second, dangling one).
+ *   - **Verbatim.** The agent's prose is appended unaltered under a `## Decisions`
+ *     heading; we add structure, never interpretation.
+ *   - **Idempotent.** A record that ALREADY carries a `## Decisions` section is left
+ *     untouched, so a `requeue` continue, or a re-run over an already-done-moved
+ *     branch (`source: 'done'`), cannot append the same block twice.
+ *   - **Best-effort.** No block, no record on disk, or an unreadable/unwritable file
+ *     is a silent no-op: a rationale note must NEVER fail an otherwise-green
+ *     completion (the same stance as {@link reportScoopedNotes}).
+ */
+function transcribeDecisionsIntoDoneRecord(params: {
+	cwd: string;
+	slug: string;
+	output: string | undefined;
+	note: (message: string) => void;
+}): void {
+	const {cwd, slug, output, note} = params;
+	const decisions = extractDecisionsBlock(output);
+	if (decisions === undefined) {
+		return; // the common case: the agent recorded no in-scope decision.
+	}
+	const path = workItemPath(cwd, 'done', slug);
+	if (!existsSync(path)) {
+		return; // no done record to annotate (a lifecycle/degenerate shape).
+	}
+	try {
+		const body = readFileSync(path, 'utf8');
+		if (/^##\s+Decisions\s*$/m.test(body)) {
+			return; // already transcribed (a continue/re-run): never duplicate.
+		}
+		const separator = body.endsWith('\n') ? '\n' : '\n\n';
+		writeFileSync(path, `${body}${separator}## Decisions\n\n${decisions}\n`);
+		note(
+			`Recorded the agent's "## Decisions" block in ${workItemRel('done', `${slug}.md`)}.`,
+		);
+	} catch {
+		// Best-effort: never fail a green completion over a rationale note.
+	}
+}
+
 /**
  * SCOOP + REPORT the agent-authored CAPTURED NOTES this run's atomic commit is
  * landing (task `runner-scoops-captured-notes`). A rung's agent writes

package/src/review-gate.ts

@@ -126,12 +126,18 @@ export function buildReviewPrompt(slug: string): string {
 		`design choice the agent made on its own while building: a CROSS-TASK`,
 		`INTERACTION (a choice affecting another command/flag/task's behaviour), a new`,
 		`ERROR/REFUSAL, or a user-visible DEFAULT. The agent SHOULD have recorded these`,
-		`in a "## Decisions" block in its PR description — START from that block (ratify`,
+		`in a "## Decisions" block in its report, which the runner transcribes into the`,
+		`done record (work/tasks/done/<slug>.md) and which also rides the PR description.`,
+		`START from that block (ratify`,
 		`each entry) AND hunt for any it MISSED. Flag EACH such decision as a finding`,
-		`for the human to RATIFY — "non-blocking" by DEFAULT (the build proceeds; the`,
+		`for the human to RATIFY: "non-blocking" by DEFAULT (the build proceeds; the`,
 		`human ratifies or reverses), escalating to "blocking" ONLY if the decision looks`,
 		`WRONG or is genuinely load-bearing-and-hard-to-reverse. An un-recorded in-scope`,
-		`decision is NOT itself a block — it is a ratification finding.`,
+		`decision is NOT itself a block, it is a ratification finding. Do NOT raise a`,
+		`finding about WHERE the rationale was written (the done record, the commit body`,
+		`and the PR body are the RUNNER's to author, never the builder's): review the`,
+		`DECISION, not the filing. If rationale is missing entirely, that is the`,
+		`ratification finding above.`,
 		``,
 		`ALSO CHECK CONCEPTUAL COHERENCE — does this diff fit the system's existing`,
 		`LANGUAGE? For each concept / flag / config key / status / verb it introduces or`,

package/src/triage-gate.ts

@@ -26,8 +26,10 @@ import {extractJsonObjectSpan} from './verdict-json.js';
  *   - `map` — an UNAMBIGUOUS map onto an existing item → DISCHARGE the redundant
  *     note BY DELETION too (it is already covered by the item it maps onto, so it
  *     carries no unique signal; the mapping is recorded in the commit message).
- *     There is no resting `triaged:keep` state any more (task
- *     `agentic-apply-retire-disposition-vocabulary`).
+ *     An AUTO disposition never RESTS a note (task
+ *     `agentic-apply-retire-disposition-vocabulary`); the one path that KEEPS a
+ *     note is the human-answered `resolve` verdict on the apply rung (ADR
+ *     `resolve-settles-the-question-loop-not-the-note`).
  *
  * It is the DIRECT mirror of `surface-gate.ts`'s spawn→emit→parse seam, with a
  * narrower emitted payload (`{auto, …}` rather than `{questions}`). Production

package/src/triage-persist.ts

@@ -1,4 +1,4 @@
-import {readFileSync} from 'node:fs';
+import {readFileSync, writeFileSync} from 'node:fs';
 import {join} from 'node:path';
 import {run, type RunResult} from './git.js';
 import {workItemRel} from './work-layout.js';
@@ -25,8 +25,12 @@ import {setFrontmatterMarker} from './frontmatter.js';
  *   1. **the conservative auto-disposition** ({@link autoDispositionObservation},
  *      US #17, `observationTriage: 'auto'`-gated): act on the no-question case on
  *      the UNTRIAGED observation in ONE local commit. BOTH no-question cases now
- *      DISCHARGE the redundant note BY DELETION (there is no resting `triaged:keep`
- *      state any more — task `agentic-apply-retire-disposition-vocabulary`):
+ *      DISCHARGE the redundant note BY DELETION — an AUTO disposition never RESTS a
+ *      note, because both of its cases (duplicate / map) are by definition notes
+ *      that carry no unique signal (task `agentic-apply-retire-disposition-
+ *      vocabulary`; the ONE case that does rest a note is the human-answered
+ *      `resolve` verdict on the APPLY rung, see ADR `resolve-settles-the-question-
+ *      loop-not-the-note`):
  *        - `duplicate` → `git rm` the duplicate in a standalone commit, the
  *          duplicated-of identity + reason in the commit message (git history =
  *          archive). A duplicate is a redundant copy of an already-captured signal,
@@ -34,7 +38,6 @@ import {setFrontmatterMarker} from './frontmatter.js';
  *        - `map` → the note is already covered by the existing item it maps onto, so
  *          it is settled — `git rm` it in a standalone commit, the mapped-onto
  *          identity + reason recorded in the commit message (mirroring `duplicate`).
- *          There is no resting `triaged:keep` note any more.
  *   2. **promote → SELF-CONTAINED new-item creation + DELETE through the CAS**
  *      ({@link promoteObservation}, US #1/#3/#8): an ANSWERED "promote" drafts a
  *      new `work/tasks/ready/<new-slug>.md` whose body is built FROM the
@@ -120,6 +123,102 @@ export class TriagePersistError extends Error {
 	}
 }
 
+// --- Back-stamping a KEPT note that was resolved before the marker existed ---
+
+export interface StampTriagedMarkerOptions {
+	/** Working clone/worktree the stamp commits in. */
+	cwd: string;
+	/** The namespaced observation identity (`observation:<slug>`). */
+	item: string;
+	/** The observation file path RELATIVE to `cwd`. */
+	itemPath: string;
+	/** The `triaged:` value to stamp (the apply rung's settled disposition). */
+	value: string;
+	/** Why the stamp is being back-filled (rides the commit message). */
+	reason: string;
+	/** 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 StampTriagedMarkerResult {
+	/** The commit sha the stamp produced, or `undefined` when the body was already marked. */
+	commit?: string;
+	/** A human-readable summary. */
+	message: string;
+}
+
+/**
+ * Stamp the `triaged:` settled marker onto an observation that was ALREADY
+ * resolved-and-kept, in ONE local commit — the SELF-HEALING back-fill for notes
+ * resolved BEFORE the apply rung learned to stamp it (ADR
+ * `resolve-settles-the-question-loop-not-the-note`).
+ *
+ * Why a back-fill exists at all: the fix that makes `resolve` stamp the marker is
+ * forward-only, so every note a repo resolved under the old code still rests
+ * `needsAnswers:false` + no sidecar + NO marker — the exact shape the triage rung
+ * re-asks. Those notes are not hypothetical (a single `rocketh` cycle re-asked
+ * four, with eleven more queued behind them), and they are un-fixable from the
+ * human's side: answering again just resolves again into the same shape.
+ *
+ * The trigger is PROOF, not a heuristic: the caller fires this only when the body
+ * carries the ENGINE-WRITTEN `## Applied answers` record, which only
+ * `apply-persist.ts` writes and only after a human answered every open question.
+ * A hand-written note cannot accidentally acquire it, and the stamp is exactly
+ * what the apply rung WOULD have written had it known how.
+ *
+ * ONE commit touching ONE file, so the tree-less publish (`pushTreelessResult`)
+ * carries it to the arbiter like any other triage-rung marker write; once landed
+ * the note drops out of the triage pool and this path is never taken again.
+ */
+export function stampTriagedMarker(
+	options: StampTriagedMarkerOptions,
+): StampTriagedMarkerResult {
+	const {cwd, item, itemPath, value, reason, env} = options;
+	const note = options.note ?? (() => {});
+
+	if (gitSoft(['rev-parse', '--git-dir'], cwd, env).status !== 0) {
+		throw new TriagePersistError('not inside a git repository');
+	}
+
+	const abs = join(cwd, itemPath);
+	const before = readFileSync(abs, 'utf8');
+	const after = setFrontmatterMarker(before, 'triaged', value);
+	if (after === before) {
+		// Already marked (or a malformed fence `setFrontmatterMarker` refuses to
+		// rewrite) — nothing to commit; never produce an empty commit.
+		const message = `triage ${item}: already carries triaged:${value} — no stamp needed.`;
+		note(message);
+		return {message};
+	}
+	writeFileSync(abs, after);
+	const by = options.by || resolveBy(cwd, env);
+	gitHard(['add', '--', itemPath], cwd, env);
+	const subject = `advance: triage ${item} → settled (by ${by})`;
+	gitHard(
+		[
+			'commit',
+			'--quiet',
+			'-m',
+			subject,
+			'-m',
+			`triaged: ${value}\n\n${reason}`,
+		],
+		cwd,
+		env,
+	);
+	const commit = gitHard(['rev-parse', 'HEAD'], cwd, env).stdout.trim();
+	const message =
+		`triage ${item}: back-stamped triaged:${value} (the note was already ` +
+		'resolved-and-kept — it carries an engine-written applied-answers record) ' +
+		'so the triage rung stops re-asking its settled question.';
+	note(message);
+	return {commit, message};
+}
+
 // --- The conservative auto-disposition (US #17) ---------------------------
 
 export interface AutoDispositionOptions {
@@ -149,8 +248,10 @@ export interface AutoDispositionResult {
 	 * DELETION (`git rm` in a standalone commit, the reason in the message). A
 	 * `duplicate` is a redundant copy of `existing`; a `map` is already covered by
 	 * `existing` — either way the note carries no unique signal, so it leaves the
-	 * inbox by being gone. There is no resting `triaged:keep` state any more (task
-	 * `agentic-apply-retire-disposition-vocabulary`). NEVER an auto-delete of a
+	 * inbox by being gone. An AUTO disposition never RESTS a note (task
+	 * `agentic-apply-retire-disposition-vocabulary`); resting a KEPT note is the
+	 * human-answered `resolve` verdict's job on the apply rung (ADR
+	 * `resolve-settles-the-question-loop-not-the-note`). NEVER an auto-delete of a
 	 * NON-redundant signal.
 	 */
 	outcome: 'deleted';
@@ -167,9 +268,9 @@ export interface AutoDispositionResult {
  * ONE local commit, no question surfaced. BOTH no-question cases DISCHARGE the
  * redundant note BY DELETION (`git rm` in a STANDALONE commit, the mapped/
  * duplicated-of identity + reason in the commit message; git history = archive).
- * There is no resting `triaged:keep` state any more (task
- * `agentic-apply-retire-disposition-vocabulary` — a signal is still-open,
- * acted-on, or deleted):
+ * An AUTO disposition never RESTS a note (task
+ * `agentic-apply-retire-disposition-vocabulary`): its two cases carry no unique
+ * signal, so they are still-open, acted-on, or deleted — never kept:
  *
  *   - `duplicate` → the note is an EXACT duplicate of `existing` (already
  *     captured); the original carries the signal, so the copy is deleted; or