@gajae-code/coding-agent 0.12.0 → 0.12.2

package/src/gjc-runtime/launch-worktree.ts

@@ -1,6 +1,7 @@
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { shortenPath } from "../tools/render-utils";
 
 export type GjcLaunchWorktreeMode =
 	| { enabled: false }
@@ -138,6 +139,107 @@ function hasBranchInUse(entries: GitWorktreeEntry[], branchName: string, worktre
 	return entries.some(entry => entry.branchRef === expectedRef && path.resolve(entry.path) !== resolvedPath);
 }
 
+function fileSystemErrorCode(error: unknown): string | null {
+	return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
+		? error.code
+		: null;
+}
+
+function formatBucketPath(bucketPath: string): string {
+	return JSON.stringify(shortenPath(bucketPath));
+}
+
+function brokenBucketSymlinkError(bucketPath: string): Error {
+	return new Error(
+		[
+			"worktree_bucket_broken_symlink",
+			"The GJC launch worktree bucket is a symbolic link whose target cannot be resolved; it may be unmounted or offloaded cold storage.",
+			`Path: ${formatBucketPath(bucketPath)}`,
+			"Safe remediation: restore or remount the link target, or inspect and remove the dangling link with platform-appropriate filesystem tools, then relaunch. GJC did not delete or replace the entry.",
+		].join("\n"),
+	);
+}
+
+function bucketNotDirectoryError(bucketPath: string, symlinkTarget = false): Error {
+	return new Error(
+		[
+			"worktree_bucket_not_directory",
+			symlinkTarget
+				? "The GJC launch worktree bucket is a symbolic link whose target is not a directory."
+				: "The GJC launch worktree bucket path exists but is not a directory.",
+			`Path: ${formatBucketPath(bucketPath)}`,
+			"Safe remediation: inspect the obstructing entry and move or remove it with platform-appropriate filesystem tools, then relaunch. GJC did not delete or replace the entry.",
+		].join("\n"),
+	);
+}
+
+function inspectBucketDir(bucketPath: string): "missing" | "usable" {
+	let entry: fs.Stats;
+	try {
+		entry = fs.lstatSync(bucketPath);
+	} catch (error) {
+		if (fileSystemErrorCode(error) === "ENOENT") return "missing";
+		throw new Error(
+			[
+				"worktree_bucket_inspection_failed",
+				`GJC could not inspect the launch worktree bucket${fileSystemErrorCode(error) ? ` (${fileSystemErrorCode(error)})` : ""}.`,
+				`Path: ${formatBucketPath(bucketPath)}`,
+				"Safe remediation: verify that the bucket parent is accessible, then relaunch. GJC did not modify the entry.",
+			].join("\n"),
+		);
+	}
+	if (entry.isDirectory()) return "usable";
+	if (!entry.isSymbolicLink()) throw bucketNotDirectoryError(bucketPath);
+
+	let target: fs.Stats;
+	try {
+		target = fs.statSync(bucketPath);
+	} catch (error) {
+		const code = fileSystemErrorCode(error);
+		if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP") throw brokenBucketSymlinkError(bucketPath);
+		throw new Error(
+			[
+				"worktree_bucket_target_inspection_failed",
+				`GJC could not inspect the launch worktree bucket link target${code ? ` (${code})` : ""}.`,
+				`Path: ${formatBucketPath(bucketPath)}`,
+				"Safe remediation: verify that the link target is accessible, then relaunch. GJC did not modify the link.",
+			].join("\n"),
+		);
+	}
+	if (target.isDirectory()) return "usable";
+	throw bucketNotDirectoryError(bucketPath, true);
+}
+
+function ensureBucketDirUsable(bucketPath: string): void {
+	inspectBucketDir(bucketPath);
+	try {
+		fs.mkdirSync(bucketPath, { recursive: true });
+	} catch (error) {
+		// The entry can change between lstat/stat and mkdir. Re-inspect so a
+		// racing broken link or non-directory is still reported actionably.
+		inspectBucketDir(bucketPath);
+		const code = fileSystemErrorCode(error);
+		throw new Error(
+			[
+				"worktree_bucket_create_failed",
+				`GJC could not create or reuse the launch worktree bucket${code ? ` (${code})` : ""}.`,
+				`Path: ${formatBucketPath(bucketPath)}`,
+				"Safe remediation: verify parent permissions and bucket accessibility, then relaunch. GJC did not delete or replace any entry.",
+			].join("\n"),
+		);
+	}
+	if (inspectBucketDir(bucketPath) === "missing") {
+		throw new Error(
+			[
+				"worktree_bucket_changed_during_preflight",
+				"The GJC launch worktree bucket disappeared while launch was preparing it.",
+				`Path: ${formatBucketPath(bucketPath)}`,
+				"Safe remediation: stabilize the bucket mount or parent directory, then relaunch. GJC did not delete or replace any entry.",
+			].join("\n"),
+		);
+	}
+}
+
 function pruneStaleWorktreePath(repoRoot: string): void {
 	runGit(repoRoot, ["worktree", "prune"]);
 }
@@ -267,7 +369,7 @@ export function ensureLaunchWorktree(
 		throw new Error(`branch_in_use:${plan.branchName}`);
 	}
 
-	fs.mkdirSync(path.dirname(plan.worktreePath), { recursive: true });
+	ensureBucketDirUsable(path.dirname(plan.worktreePath));
 	const branchAlreadyExisted = plan.branchName ? branchExists(plan.repoRoot, plan.branchName) : false;
 	const args = ["worktree", "add"];
 	if (plan.detached) args.push("--detach", plan.worktreePath, plan.baseRef);

package/src/gjc-runtime/ledger-event-renderer.ts

@@ -92,6 +92,7 @@ const RALPLAN_STAGE_CODES: Record<string, string> = {
 	revision: "R",
 	architect: "A",
 	critic: "C",
+	disposition: "X",
 	adr: "D",
 	"post-interview": "I",
 	final: "F",

package/src/gjc-runtime/managed-owner-admission.ts

@@ -51,7 +51,7 @@ function ownerEnvironment(): {
 	const generation = process.env[MANAGED_OWNER_GENERATION_ENV]?.trim();
 	const runId = process.env[MANAGED_OWNER_RUN_ID_ENV]?.trim();
 	const incarnation = process.env[MANAGED_OWNER_INCARNATION_ENV]?.trim();
-	if (!stateDir && !sessionId && !generation && !runId && !incarnation) return null;
+	if (!stateDir && !generation && !runId && !incarnation) return null;
 	if (!stateDir || !sessionId || !generation || !runId || !incarnation || !path.isAbsolute(stateDir))
 		throw new Error("managed_owner_admission_metadata_invalid");
 	for (const [value, label] of [

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`;
+}