@gajae-code/coding-agent 0.12.1 → 0.12.2

package/src/gjc-runtime/ralplan-review-conflicts.ts

@@ -0,0 +1,472 @@
+/**
+ * Typed ralplan review conflicts and dispositions (#2902).
+ *
+ * Architect and Critic findings remain free-form in their stage markdown, but
+ * the join/revision path can record machine-checkable findings against stable
+ * plan targets. Incompatible actions on the same target produce open conflicts
+ * that block a clean join until an explicit disposition is recorded.
+ */
+
+export const RALPLAN_REVIEW_CONFLICTS_SCHEMA = "ralplan.review_conflicts.v1" as const;
+
+export type ReviewAction = "add" | "remove" | "change" | "clarify";
+export type ReviewRole = "architect" | "critic";
+export type ReviewSeverity = "info" | "watch" | "block";
+export type DispositionChoice = "accept_architect" | "accept_critic" | "synthesize" | "defer_user" | "reject_both";
+
+export interface ReviewSourceReceipt {
+	stage: "architect" | "critic";
+	stageN: number;
+	path: string;
+	sha256: string;
+}
+
+export interface ReviewFinding {
+	findingId: string;
+	targetId: string;
+	action: ReviewAction;
+	severity: ReviewSeverity;
+	evidence: string;
+	sourceRole: ReviewRole;
+	sourceReceipt: ReviewSourceReceipt;
+	proposedOwner?: string;
+}
+
+export interface ReviewConflict {
+	conflictId: string;
+	targetId: string;
+	findingIds: [string, string];
+	actions: [ReviewAction, ReviewAction];
+	sourceRoles: [ReviewRole, ReviewRole];
+	status: "open" | "dispositioned";
+}
+
+export interface ConflictDisposition {
+	conflictId: string;
+	choice: DispositionChoice;
+	rationale: string;
+	decisionOwner: string;
+	affectedSections: string[];
+	dispositionedAt?: string;
+}
+
+export interface ReviewConflictDocument {
+	schema: typeof RALPLAN_REVIEW_CONFLICTS_SCHEMA;
+	plannerStageN: number;
+	findings: ReviewFinding[];
+	conflicts: ReviewConflict[];
+	dispositions: ConflictDisposition[];
+}
+
+export interface JoinGateResult {
+	ok: boolean;
+	openConflictIds: string[];
+	missingDispositionIds: string[];
+	orphanDispositionIds: string[];
+	message: string;
+}
+
+const ACTIONS = new Set<ReviewAction>(["add", "remove", "change", "clarify"]);
+const ROLES = new Set<ReviewRole>(["architect", "critic"]);
+const SEVERITIES = new Set<ReviewSeverity>(["info", "watch", "block"]);
+const DISPOSITIONS = new Set<DispositionChoice>([
+	"accept_architect",
+	"accept_critic",
+	"synthesize",
+	"defer_user",
+	"reject_both",
+]);
+
+/** Pairs of actions that cannot both stand for the same plan target. */
+const INCOMPATIBLE_ACTION_PAIRS = new Set<string>([
+	pairKey("add", "remove"),
+	pairKey("remove", "add"),
+	pairKey("remove", "change"),
+	pairKey("change", "remove"),
+]);
+
+function pairKey(left: ReviewAction, right: ReviewAction): string {
+	return `${left}\u0000${right}`;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonEmptyString(value: unknown, field: string): string {
+	if (typeof value !== "string" || value.trim() === "") {
+		throw new Error(`${field} must be a non-empty string`);
+	}
+	return value.trim();
+}
+
+function positiveInt(value: unknown, field: string): number {
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+		throw new Error(`${field} must be an integer >= 1`);
+	}
+	return value;
+}
+
+function parseAction(value: unknown, field: string): ReviewAction {
+	const action = nonEmptyString(value, field);
+	if (!ACTIONS.has(action as ReviewAction)) {
+		throw new Error(`${field} must be one of: ${[...ACTIONS].join(", ")}`);
+	}
+	return action as ReviewAction;
+}
+
+function parseRole(value: unknown, field: string): ReviewRole {
+	const role = nonEmptyString(value, field);
+	if (!ROLES.has(role as ReviewRole)) {
+		throw new Error(`${field} must be one of: ${[...ROLES].join(", ")}`);
+	}
+	return role as ReviewRole;
+}
+
+function parseSeverity(value: unknown, field: string): ReviewSeverity {
+	const severity = nonEmptyString(value, field);
+	if (!SEVERITIES.has(severity as ReviewSeverity)) {
+		throw new Error(`${field} must be one of: ${[...SEVERITIES].join(", ")}`);
+	}
+	return severity as ReviewSeverity;
+}
+
+function parseDispositionChoice(value: unknown, field: string): DispositionChoice {
+	const choice = nonEmptyString(value, field);
+	if (!DISPOSITIONS.has(choice as DispositionChoice)) {
+		throw new Error(`${field} must be one of: ${[...DISPOSITIONS].join(", ")}`);
+	}
+	return choice as DispositionChoice;
+}
+
+function parseSourceReceipt(value: unknown, field: string): ReviewSourceReceipt {
+	if (!isObject(value)) throw new Error(`${field} must be an object`);
+	const stage = nonEmptyString(value.stage, `${field}.stage`);
+	if (stage !== "architect" && stage !== "critic") {
+		throw new Error(`${field}.stage must be architect or critic`);
+	}
+	return {
+		stage,
+		stageN: positiveInt(value.stageN ?? value.stage_n, `${field}.stageN`),
+		path: nonEmptyString(value.path, `${field}.path`),
+		sha256: nonEmptyString(value.sha256, `${field}.sha256`),
+	};
+}
+
+function parseFinding(value: unknown, index: number): ReviewFinding {
+	if (!isObject(value)) throw new Error(`findings[${index}] must be an object`);
+	const finding: ReviewFinding = {
+		findingId: nonEmptyString(value.findingId ?? value.finding_id, `findings[${index}].findingId`),
+		targetId: nonEmptyString(value.targetId ?? value.target_id, `findings[${index}].targetId`),
+		action: parseAction(value.action, `findings[${index}].action`),
+		severity: parseSeverity(value.severity, `findings[${index}].severity`),
+		evidence: nonEmptyString(value.evidence, `findings[${index}].evidence`),
+		sourceRole: parseRole(value.sourceRole ?? value.source_role, `findings[${index}].sourceRole`),
+		sourceReceipt: parseSourceReceipt(
+			value.sourceReceipt ?? value.source_receipt,
+			`findings[${index}].sourceReceipt`,
+		),
+	};
+	const proposedOwner = value.proposedOwner ?? value.proposed_owner;
+	if (proposedOwner !== undefined) {
+		finding.proposedOwner = nonEmptyString(proposedOwner, `findings[${index}].proposedOwner`);
+	}
+	return finding;
+}
+
+function parseDisposition(value: unknown, index: number): ConflictDisposition {
+	if (!isObject(value)) throw new Error(`dispositions[${index}] must be an object`);
+	const affectedRaw = value.affectedSections ?? value.affected_sections;
+	if (!Array.isArray(affectedRaw) || affectedRaw.length === 0) {
+		throw new Error(`dispositions[${index}].affectedSections must be a non-empty string array`);
+	}
+	const affectedSections = affectedRaw.map((entry, i) =>
+		nonEmptyString(entry, `dispositions[${index}].affectedSections[${i}]`),
+	);
+	const disposition: ConflictDisposition = {
+		conflictId: nonEmptyString(value.conflictId ?? value.conflict_id, `dispositions[${index}].conflictId`),
+		choice: parseDispositionChoice(value.choice, `dispositions[${index}].choice`),
+		rationale: nonEmptyString(value.rationale, `dispositions[${index}].rationale`),
+		decisionOwner: nonEmptyString(
+			value.decisionOwner ?? value.decision_owner,
+			`dispositions[${index}].decisionOwner`,
+		),
+		affectedSections,
+	};
+	const at = value.dispositionedAt ?? value.dispositioned_at;
+	if (at !== undefined) {
+		disposition.dispositionedAt = nonEmptyString(at, `dispositions[${index}].dispositionedAt`);
+	}
+	return disposition;
+}
+
+/** True when two actions on the same target cannot both remain. */
+export function actionsAreIncompatible(left: ReviewAction, right: ReviewAction): boolean {
+	if (left === right) return false;
+	return INCOMPATIBLE_ACTION_PAIRS.has(pairKey(left, right));
+}
+
+/**
+ * Derive open conflicts from typed findings. Only cross-role incompatible pairs
+ * on the same targetId are conflicts (Architect remove vs Critic add, etc.).
+ */
+export function detectReviewConflicts(findings: readonly ReviewFinding[]): ReviewConflict[] {
+	const byTarget = new Map<string, ReviewFinding[]>();
+	for (const finding of findings) {
+		const list = byTarget.get(finding.targetId) ?? [];
+		list.push(finding);
+		byTarget.set(finding.targetId, list);
+	}
+
+	const conflicts: ReviewConflict[] = [];
+	for (const [targetId, group] of byTarget) {
+		for (let i = 0; i < group.length; i++) {
+			for (let j = i + 1; j < group.length; j++) {
+				const a = group[i]!;
+				const b = group[j]!;
+				if (a.sourceRole === b.sourceRole) continue;
+				if (!actionsAreIncompatible(a.action, b.action)) continue;
+				const [left, right] = a.findingId <= b.findingId ? [a, b] : [b, a];
+				conflicts.push({
+					conflictId: `conflict:${targetId}:${left.findingId}:${right.findingId}`,
+					targetId,
+					findingIds: [left.findingId, right.findingId],
+					actions: [left.action, right.action],
+					sourceRoles: [left.sourceRole, right.sourceRole],
+					status: "open",
+				});
+			}
+		}
+	}
+	return conflicts.sort((x, y) => x.conflictId.localeCompare(y.conflictId));
+}
+
+/** Mark conflicts dispositioned when a matching disposition exists. */
+export function applyDispositions(
+	conflicts: readonly ReviewConflict[],
+	dispositions: readonly ConflictDisposition[],
+): ReviewConflict[] {
+	const disposed = new Set(dispositions.map(d => d.conflictId));
+	return conflicts.map(conflict =>
+		disposed.has(conflict.conflictId) ? { ...conflict, status: "dispositioned" } : { ...conflict, status: "open" },
+	);
+}
+
+/**
+ * Join gate: clean only when every derived conflict has an explicit disposition
+ * with rationale and decision owner, and no orphan dispositions reference unknown
+ * conflicts.
+ */
+export function evaluateReviewJoinGate(
+	findings: readonly ReviewFinding[],
+	dispositions: readonly ConflictDisposition[],
+	precomputedConflicts?: readonly ReviewConflict[],
+): JoinGateResult {
+	const derived = precomputedConflicts ? precomputedConflicts.map(c => ({ ...c })) : detectReviewConflicts(findings);
+	const withStatus = applyDispositions(derived, dispositions);
+	const knownIds = new Set(withStatus.map(c => c.conflictId));
+	const openConflictIds = withStatus.filter(c => c.status === "open").map(c => c.conflictId);
+	const disposedIds = new Set(dispositions.map(d => d.conflictId));
+	const missingDispositionIds = openConflictIds.filter(id => !disposedIds.has(id));
+	const orphanDispositionIds = dispositions.map(d => d.conflictId).filter(id => !knownIds.has(id));
+
+	const ok = missingDispositionIds.length === 0 && orphanDispositionIds.length === 0;
+	let message: string;
+	if (ok && withStatus.length === 0) {
+		message = "No typed review conflicts; join is clean.";
+	} else if (ok) {
+		message = `All ${withStatus.length} typed review conflict(s) are dispositioned.`;
+	} else if (missingDispositionIds.length > 0) {
+		message = `Join blocked: ${missingDispositionIds.length} open conflict(s) lack disposition: ${missingDispositionIds.join(", ")}.`;
+	} else {
+		message = `Join blocked: disposition(s) reference unknown conflict id(s): ${orphanDispositionIds.join(", ")}.`;
+	}
+
+	return { ok, openConflictIds, missingDispositionIds, orphanDispositionIds, message };
+}
+
+/** Strip optional markdown fence and parse JSON. */
+export function parseReviewConflictJson(raw: string): unknown {
+	const trimmed = raw.trim();
+	const fenced = trimmed.match(/^```(?:json)?\s*\n([\s\S]*?)\n```\s*$/u);
+	const body = fenced ? fenced[1]!.trim() : trimmed;
+	try {
+		return JSON.parse(body);
+	} catch (error) {
+		throw new Error(`disposition artifact must be JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+/**
+ * Authoritative provenance required by `gjc ralplan --write --stage disposition`.
+ *
+ * Without this, a disposition document can claim arbitrary path/hash strings and
+ * join the wrong Architect/Critic pass (#3013 adversarial review).
+ */
+export interface IndexedReviewArtifact {
+	path: string;
+	sha256: string;
+}
+
+export interface DispositionProvenanceContext {
+	/** CLI `--stage_n` for this disposition write; must equal `plannerStageN`. */
+	expectedStageN: number;
+	/**
+	 * Persisted Architect/Critic (and other) stage artifacts from this run's
+	 * `index.jsonl`, keyed by `${stage}\u0000${stageN}`.
+	 */
+	indexedArtifacts: ReadonlyMap<string, IndexedReviewArtifact>;
+}
+
+/** Stable map key for a staged artifact identity in the run index. */
+export function reviewArtifactIndexKey(stage: string, stageN: number): string {
+	return `${stage}\u0000${stageN}`;
+}
+
+/**
+ * Cross-check every finding's source receipt against the CLI stage number and
+ * the run's persisted Architect/Critic artifact index. Fail closed on mismatch
+ * or spoofed path/hash attestations.
+ */
+export function assertDispositionProvenance(
+	doc: ReviewConflictDocument,
+	provenance: DispositionProvenanceContext,
+): void {
+	if (doc.plannerStageN !== provenance.expectedStageN) {
+		throw new Error(
+			`disposition provenance: plannerStageN=${doc.plannerStageN} does not match CLI --stage_n=${provenance.expectedStageN}`,
+		);
+	}
+
+	for (let i = 0; i < doc.findings.length; i++) {
+		const finding = doc.findings[i]!;
+		const field = `findings[${i}]`;
+		const receipt = finding.sourceReceipt;
+
+		if (receipt.stage !== finding.sourceRole) {
+			throw new Error(`${field}.sourceReceipt.stage=${receipt.stage} must equal sourceRole=${finding.sourceRole}`);
+		}
+		if (receipt.stageN !== doc.plannerStageN) {
+			throw new Error(
+				`${field}.sourceReceipt.stageN=${receipt.stageN} must equal plannerStageN=${doc.plannerStageN} (same-pass join)`,
+			);
+		}
+
+		const indexed = provenance.indexedArtifacts.get(reviewArtifactIndexKey(receipt.stage, receipt.stageN));
+		if (!indexed) {
+			throw new Error(
+				`${field}.sourceReceipt: no persisted ${receipt.stage} stage ${receipt.stageN} artifact in run index`,
+			);
+		}
+		if (indexed.path !== receipt.path) {
+			throw new Error(
+				`${field}.sourceReceipt.path does not match indexed ${receipt.stage} stage ${receipt.stageN} path`,
+			);
+		}
+		if (indexed.sha256 !== receipt.sha256) {
+			throw new Error(
+				`${field}.sourceReceipt.sha256 does not match indexed ${receipt.stage} stage ${receipt.stageN} sha256`,
+			);
+		}
+	}
+}
+
+/**
+ * Parse and validate a disposition-stage document. Re-derives conflicts from
+ * findings when omitted, then fails closed unless every conflict is dispositioned
+ * (or findings produce zero conflicts and dispositions are empty).
+ *
+ * When `provenance` is provided (CLI write path), also enforces authoritative
+ * same-pass receipt checks against the run index.
+ */
+export function parseReviewConflictDocument(
+	raw: string | unknown,
+	provenance?: DispositionProvenanceContext,
+): ReviewConflictDocument {
+	const value = typeof raw === "string" ? parseReviewConflictJson(raw) : raw;
+	if (!isObject(value)) throw new Error("disposition document must be a JSON object");
+
+	const schema = nonEmptyString(value.schema, "schema");
+	if (schema !== RALPLAN_REVIEW_CONFLICTS_SCHEMA) {
+		throw new Error(`schema must be ${RALPLAN_REVIEW_CONFLICTS_SCHEMA}`);
+	}
+
+	const plannerStageN = positiveInt(value.plannerStageN ?? value.planner_stage_n, "plannerStageN");
+	if (!Array.isArray(value.findings)) throw new Error("findings must be an array");
+	const findings = value.findings.map((entry, i) => parseFinding(entry, i));
+	const findingIds = new Set(findings.map(f => f.findingId));
+	if (findingIds.size !== findings.length) throw new Error("findingId values must be unique");
+
+	// Structural role/stage alignment is always required (even without index).
+	for (let i = 0; i < findings.length; i++) {
+		const f = findings[i]!;
+		if (f.sourceReceipt.stage !== f.sourceRole) {
+			throw new Error(
+				`findings[${i}].sourceReceipt.stage=${f.sourceReceipt.stage} must equal sourceRole=${f.sourceRole}`,
+			);
+		}
+		if (f.sourceReceipt.stageN !== plannerStageN) {
+			throw new Error(
+				`findings[${i}].sourceReceipt.stageN=${f.sourceReceipt.stageN} must equal plannerStageN=${plannerStageN}`,
+			);
+		}
+	}
+
+	const dispositions = Array.isArray(value.dispositions)
+		? value.dispositions.map((entry, i) => parseDisposition(entry, i))
+		: [];
+	const dispositionConflictIds = new Set(dispositions.map(d => d.conflictId));
+	if (dispositionConflictIds.size !== dispositions.length) {
+		throw new Error("disposition conflictId values must be unique");
+	}
+
+	const derived = detectReviewConflicts(findings);
+	const provided = Array.isArray(value.conflicts) ? value.conflicts : undefined;
+	let conflicts: ReviewConflict[];
+	if (provided === undefined) {
+		conflicts = applyDispositions(derived, dispositions);
+	} else {
+		// Accept provided conflict ids only when they match derived pairs.
+		const derivedById = new Map(derived.map(c => [c.conflictId, c]));
+		conflicts = provided.map((entry, i) => {
+			if (!isObject(entry)) throw new Error(`conflicts[${i}] must be an object`);
+			const conflictId = nonEmptyString(entry.conflictId ?? entry.conflict_id, `conflicts[${i}].conflictId`);
+			const derivedConflict = derivedById.get(conflictId);
+			if (!derivedConflict) {
+				throw new Error(`conflicts[${i}] ${conflictId} is not derived from findings`);
+			}
+			return derivedConflict;
+		});
+		// Include any derived conflicts omitted from the payload so join cannot skip them.
+		for (const derivedConflict of derived) {
+			if (!conflicts.some(c => c.conflictId === derivedConflict.conflictId)) {
+				conflicts.push(derivedConflict);
+			}
+		}
+		conflicts = applyDispositions(conflicts, dispositions);
+	}
+
+	const gate = evaluateReviewJoinGate(findings, dispositions, conflicts);
+	if (!gate.ok) {
+		throw new Error(gate.message);
+	}
+
+	const doc: ReviewConflictDocument = {
+		schema: RALPLAN_REVIEW_CONFLICTS_SCHEMA,
+		plannerStageN,
+		findings,
+		conflicts,
+		dispositions,
+	};
+
+	if (provenance) {
+		assertDispositionProvenance(doc, provenance);
+	}
+
+	return doc;
+}
+
+/** Canonical JSON serialization for disposition-stage artifacts. */
+export function serializeReviewConflictDocument(doc: ReviewConflictDocument): string {
+	return `${JSON.stringify(doc, null, 2)}\n`;
+}

package/src/gjc-runtime/ralplan-runtime.ts

@@ -13,6 +13,12 @@ import {
 	type RalplanIndexRow,
 	summarizeRalplanIndex,
 } from "./ledger-event-renderer";
+import {
+	type IndexedReviewArtifact,
+	parseReviewConflictDocument,
+	reviewArtifactIndexKey,
+	serializeReviewConflictDocument,
+} from "./ralplan-review-conflicts";
 import {
 	assertCwdMatchesRepositoryBinding,
 	assertPathUnderRepositoryBinding,
@@ -37,7 +43,6 @@ import {
 import { probeGjcTeamAvailability } from "./team-runtime";
 import { assertSafePathComponent, CommandError, flagValue, hasFlag } from "./workflow-cli-common";
 import { getSkillManifest } from "./workflow-manifest";
-
 /**
  * Native implementation of `gjc ralplan`.
  *
@@ -53,9 +58,11 @@ import { getSkillManifest } from "./workflow-manifest";
  * 2. **Artifact write**: `gjc ralplan --write --stage <type> --stage_n <N>
  *    (--artifact <path-or-string> | --artifact-env GJC_RALPLAN_ARTIFACT)
  *    [--run-id <id>] [--session-id <id>] [--lane-verdict <token>] [--json]` persists Planner / Architect
- *    / Critic / revision / post-interview / ADR / final markdown under `.gjc/plans/ralplan/<run-id>/`, maintains
- *    an `index.jsonl` audit log, copies `final` stages to `pending-approval.md`, and advances
- *    the HUD chip to reflect the latest persisted stage.
+ *    / Critic / disposition / revision / post-interview / ADR / final artifacts under
+ *    `.gjc/plans/ralplan/<run-id>/`, maintains an `index.jsonl` audit log, copies `final`
+ *    stages to `pending-approval.md`, and advances the HUD chip to reflect the latest
+ *    persisted stage. Disposition stage artifacts are fail-closed JSON documents that
+ *    record typed review conflicts with authoritative same-pass source receipts (#2902).
  */
 
 export interface RalplanCommandResult {
@@ -64,7 +71,16 @@ export interface RalplanCommandResult {
 	stderr?: string;
 }
 
-const KNOWN_STAGES = ["planner", "architect", "critic", "revision", "post-interview", "adr", "final"] as const;
+const KNOWN_STAGES = [
+	"planner",
+	"architect",
+	"critic",
+	"disposition",
+	"revision",
+	"post-interview",
+	"adr",
+	"final",
+] as const;
 type RalplanStage = (typeof KNOWN_STAGES)[number];
 /** Default consensus iterations (planner + revision openers) per run. Matches SKILL.md re-review cap. */
 export const RALPLAN_DEFAULT_MAX_ITERATIONS = 5;
@@ -1851,6 +1867,54 @@ async function buildRalplanHud(options: {
 	});
 }
 
+/**
+ * Disposition-stage artifacts are machine-checkable JSON. Validate, enforce
+ * authoritative same-pass provenance against the run index, and re-serialize to
+ * canonical form so join gates and re-review share one shape (#2902 / #3013).
+ */
+function normalizeDispositionArtifact(raw: string, expectedStageN: number, indexText: string | undefined): string {
+	try {
+		const indexedArtifacts = buildIndexedReviewArtifacts(indexText);
+		const doc = parseReviewConflictDocument(raw, {
+			expectedStageN,
+			indexedArtifacts,
+		});
+		return serializeReviewConflictDocument(doc);
+	} catch (error) {
+		throw new RalplanCommandError(
+			2,
+			`invalid ralplan disposition artifact: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+}
+
+/** Parse complete path/sha256 rows from a run `index.jsonl` snapshot for provenance. */
+function buildIndexedReviewArtifacts(indexText: string | undefined): Map<string, IndexedReviewArtifact> {
+	const map = new Map<string, IndexedReviewArtifact>();
+	if (indexText === undefined) return map;
+	for (const line of indexText.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		let row: unknown;
+		try {
+			row = JSON.parse(trimmed);
+		} catch {
+			continue;
+		}
+		if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+		const record = row as Record<string, unknown>;
+		if (typeof record.stage !== "string") continue;
+		if (typeof record.stage_n !== "number" || !Number.isInteger(record.stage_n)) continue;
+		if (typeof record.path !== "string" || typeof record.sha256 !== "string") continue;
+		// Last complete row for an identity wins (matches findExistingStageArtifact).
+		map.set(reviewArtifactIndexKey(record.stage, record.stage_n), {
+			path: record.path,
+			sha256: record.sha256,
+		});
+	}
+	return map;
+}
+
 async function handleArtifactWrite(args: readonly string[], cwd: string): Promise<RalplanCommandResult> {
 	const resolved = await resolveArtifactArgs(args, cwd);
 	const persistedRoleState = parsePersistedRoleStateArgs(args, resolved.stage);
@@ -1873,14 +1937,20 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 			// Non-file / missing path is inline content; resolveArtifactContent already handled it.
 		}
 	}
-	const content = resolved.artifact.endsWith("\n") ? resolved.artifact : `${resolved.artifact}\n`;
-	const sha256 = createHash("sha256").update(content).digest("hex");
 
-	// Read the ledger once before persistence. The dedupe guard and both gates
-	// consume this same snapshot so no additional ledger read can slip between gate
-	// evaluation and persistence.
+	// Read the ledger once before persistence. The dedupe guard, both gates, and
+	// disposition provenance consume this same snapshot so no additional ledger
+	// read can slip between gate evaluation and persistence.
 	const indexLoad = await loadRalplanIndexForCap(cwd, resolved.sessionId, resolved.runId);
 
+	// Disposition stage: fail-closed parse/normalize with authoritative receipts (#2902).
+	const normalizedArtifact =
+		resolved.stage === "disposition"
+			? normalizeDispositionArtifact(resolved.artifact, resolved.stageN, indexLoad.rawText)
+			: resolved.artifact;
+	const content = normalizedArtifact.endsWith("\n") ? normalizedArtifact : `${normalizedArtifact}\n`;
+	const sha256 = createHash("sha256").update(content).digest("hex");
+
 	// Duplicate-write guard: a second `--write` for the same (stage, stage_n) must not
 	// silently clobber the artifact or append a duplicate ledger row. Classify before any
 	// state mutation so a conflict never regresses run-state phase.