@gajae-code/coding-agent 0.12.1 → 0.12.4

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

@@ -1,4 +1,5 @@
 import * as crypto from "node:crypto";
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { getConfigRootDir } from "@gajae-code/utils";
 import type { WorkflowHudSummary } from "../skill-state/active-state";
@@ -1794,27 +1795,46 @@ export function hasTypedVerifiedReceipt(value: unknown): boolean {
 	return Boolean(type && id && (status === "verified" || status === "passed"));
 }
 
-export async function hasExistingNonEmptyArtifact(cwd: string, value: unknown): Promise<boolean> {
+async function resolveExistingArtifactPathUnderCwd(
+	cwd: string,
+	value: unknown,
+	fieldName: string,
+): Promise<string | null> {
 	const artifactPath = nonEmptyString(value);
-	if (!artifactPath) return false;
-	const resolved = path.resolve(cwd, artifactPath);
+	if (!artifactPath) return null;
+	const lexicalRoot = path.resolve(cwd);
+	const lexical = path.resolve(lexicalRoot, artifactPath);
+	const lexicalRelative = path.relative(lexicalRoot, lexical);
+	if (lexicalRelative === ".." || lexicalRelative.startsWith(`..${path.sep}`) || path.isAbsolute(lexicalRelative)) {
+		throw new Error(`qualityGate ${fieldName} artifact path must resolve under the repository cwd`);
+	}
 	try {
-		const file = Bun.file(resolved);
-		return (await file.exists()) && file.size > 0;
+		const [root, resolved] = await Promise.all([fs.realpath(lexicalRoot), fs.realpath(lexical)]);
+		const relative = path.relative(root, resolved);
+		if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+			throw new Error(`qualityGate ${fieldName} artifact path must not escape the repository cwd through symlinks`);
+		}
+		if (!(await fs.stat(resolved)).isFile()) {
+			throw new Error(`qualityGate ${fieldName} artifact path must reference a regular file`);
+		}
+		return resolved;
 	} catch (error) {
-		if (isEnoent(error)) return false;
+		if (isEnoent(error)) return null;
 		throw error;
 	}
 }
 
+export async function hasExistingNonEmptyArtifact(cwd: string, value: unknown): Promise<boolean> {
+	const resolved = await resolveExistingArtifactPathUnderCwd(cwd, value, "artifact");
+	if (!resolved) return false;
+	return (await fs.stat(resolved)).size > 0;
+}
+
 export async function readArtifactBytes(cwd: string, row: JsonObject, fieldName: string): Promise<Buffer | null> {
-	const artifactPath = nonEmptyString(row.path);
-	if (!artifactPath) return null;
-	const resolved = path.resolve(cwd, artifactPath);
+	const resolved = await resolveExistingArtifactPathUnderCwd(cwd, row.path, fieldName);
+	if (!resolved) return null;
 	try {
-		const file = Bun.file(resolved);
-		if (!(await file.exists())) return null;
-		return Buffer.from(await file.arrayBuffer());
+		return Buffer.from(await Bun.file(resolved).arrayBuffer());
 	} catch (error) {
 		if (isEnoent(error)) return null;
 		throw new Error(`qualityGate ${fieldName} artifact could not be read: ${String(error)}`);
@@ -1823,6 +1843,7 @@ export async function readArtifactBytes(cwd: string, row: JsonObject, fieldName:
 
 import {
 	readCliReplayRecord,
+	resolveCliReplayCommand,
 	validateArtifactProof,
 	validateCliReplay,
 	validateLiveSurfaceProofPresence,
@@ -1834,6 +1855,7 @@ import {
 
 export type { ReplayProcessHandle } from "./ultragoal-evidence";
 export {
+	resolveCliReplayCommand,
 	validateArtifactProof,
 	validateCliReplay,
 	validateLiveSurfaceProofPresence,
@@ -2230,6 +2252,169 @@ function validateDeferredLaneDeclaration(deferred: JsonObject, fieldName: string
 	}
 }
 
+/**
+ * Agent-friendly deferred-gate hydration: the runtime already stores the durable
+ * batch tuple and computes the cumulative change set itself, so a deferred gate
+ * only has to prove what the runtime cannot know — that targeted verification ran.
+ * Every mechanical field (`kind`, the batch tuple, `deferredLanes`, and the whole
+ * `changeSet` block including `paths` and `changeSetHash`) is auto-filled when
+ * omitted. Explicitly supplied values are never overwritten, so a wrong
+ * declaration still fails closed.
+ */
+function hydrateDeferredGateDefaults(
+	gate: JsonObject,
+	goal: UltragoalGoal,
+	changeSet: UltragoalChangeSet | undefined,
+): JsonObject {
+	const deferred = qualityGateObject(gate.deferredToBatch);
+	if (!deferred) return gate;
+	const metadata = goal.validationBatch;
+	// The final member must carry the full strict gate; never help it defer.
+	if (metadata && goal.id === metadata.finalGoalId) return gate;
+	const hydrated: JsonObject = { ...deferred };
+	if (hydrated.kind === undefined) hydrated.kind = "validation-batch-deferred";
+	if (metadata) {
+		if (hydrated.schemaVersion === undefined) hydrated.schemaVersion = metadata.schemaVersion;
+		if (hydrated.batchId === undefined) hydrated.batchId = metadata.batchId;
+		if (hydrated.memberIds === undefined) hydrated.memberIds = [...metadata.memberIds];
+		if (hydrated.finalGoalId === undefined) hydrated.finalGoalId = metadata.finalGoalId;
+		if (hydrated.metadataHash === undefined) hydrated.metadataHash = metadata.metadataHash;
+	}
+	if (hydrated.deferredLanes === undefined) hydrated.deferredLanes = ["architectReview", "executorQa"];
+	const computedRows = (changeSet?.paths ?? []).map(row => ({
+		path: row.path,
+		status: row.status,
+		...(row.oldPath ? { oldPath: row.oldPath } : {}),
+	}));
+	const computedByPath = new Map(computedRows.map(row => [row.path, row]));
+	const declared = qualityGateObject(hydrated.changeSet);
+	const changeSetRecord: JsonObject = declared ? { ...declared } : {};
+	if (changeSetRecord.memberGoalId === undefined) changeSetRecord.memberGoalId = goal.id;
+	if (changeSetRecord.cumulativeFromBase === undefined) changeSetRecord.cumulativeFromBase = true;
+	if (changeSetRecord.paths === undefined) {
+		changeSetRecord.paths = computedRows;
+	} else if (Array.isArray(changeSetRecord.paths)) {
+		// Accept plain-string rows and rows without a status; resolve the status
+		// from the computed change set instead of demanding git trivia.
+		changeSetRecord.paths = changeSetRecord.paths.map(row => {
+			const record = typeof row === "string" ? { path: row } : qualityGateObject(row);
+			if (!record) return row;
+			const pathValue = nonEmptyString(record.path);
+			if (!pathValue || nonEmptyString(record.status)) return record;
+			const computed = computedByPath.get(normalizeRepoPath(pathValue));
+			return {
+				...record,
+				status: computed?.status ?? "unknown",
+				...(computed?.oldPath && record.oldPath === undefined ? { oldPath: computed.oldPath } : {}),
+			};
+		});
+	}
+	if (changeSetRecord.changeSetHash === undefined) {
+		try {
+			changeSetRecord.changeSetHash = changeSetHashForPaths(
+				canonicalChangeSetRows(changeSetRecord.paths, "deferredToBatch.changeSet.paths"),
+			);
+		} catch {
+			// Malformed rows: leave the hash unset so validation reports the row defect.
+		}
+	}
+	hydrated.changeSet = changeSetRecord;
+	return { ...gate, deferredToBatch: hydrated };
+}
+
+/**
+ * Agent-friendly batch-close hydration, mirroring `hydrateDeferredGateDefaults`:
+ * every `validationBatchClose` field except `coverageEvidence` is derivable from
+ * durable state (batch metadata, member receipts) and the computed cumulative
+ * change set, so it is auto-filled when omitted. Supplied values are never
+ * overwritten and still fail closed when wrong. The minimal close is the full
+ * strict gate plus `{"validationBatchClose":{"coverageEvidence":"..."}}`.
+ */
+function hydrateBatchCloseDefaults(input: {
+	gate: JsonObject;
+	plan: UltragoalPlan;
+	goal: UltragoalGoal;
+	ledger: readonly UltragoalLedgerEvent[];
+	changeSet?: UltragoalChangeSet;
+}): JsonObject {
+	const metadata = input.goal.validationBatch;
+	if (!metadata || input.goal.id !== metadata.finalGoalId) return input.gate;
+	const requested = qualityGateObject(input.gate.validationBatchClose);
+	if (!requested) return input.gate;
+	// The replacement-close kind has its own dedicated hydrator.
+	if (requested.kind === "review-blocker-replacement-close") return input.gate;
+	const close: JsonObject = { ...requested };
+	if (close.schemaVersion === undefined) close.schemaVersion = 1;
+	if (close.kind === undefined) close.kind = "validation-batch-close";
+	if (close.batchId === undefined) close.batchId = metadata.batchId;
+	if (close.finalGoalId === undefined) close.finalGoalId = metadata.finalGoalId;
+	if (close.memberIds === undefined) close.memberIds = [...metadata.memberIds];
+	const derivedMetadataHashes: Record<string, string> = {};
+	const derivedChangeSetHashes: Record<string, string> = {};
+	const derivedReceipts: JsonObject[] = [];
+	for (const memberId of metadata.memberIds) {
+		const member = input.plan.goals.find(goal => goal.id === memberId);
+		if (member?.validationBatch) derivedMetadataHashes[memberId] = member.validationBatch.metadataHash;
+		if (!member || memberId === input.goal.id) continue;
+		try {
+			const receipt = requireDeferredMemberReceiptFresh(
+				input.plan,
+				input.ledger,
+				member,
+				"validationBatchClose hydration",
+			);
+			derivedChangeSetHashes[memberId] = receipt.validationBatch.changeSetHash;
+			derivedReceipts.push({
+				goalId: memberId,
+				receiptId: receipt.receiptId,
+				checkpointLedgerEventId: receipt.checkpointLedgerEventId,
+				qualityGateHash: receipt.qualityGateHash,
+				changeSetHash: receipt.validationBatch.changeSetHash,
+				role: "deferred-member",
+			});
+		} catch {
+			// Member not fresh/complete: omit it so validation reports the real defect.
+		}
+	}
+	const suppliedMetadataHashes = qualityGateObject(close.memberMetadataHashes);
+	if (close.memberMetadataHashes === undefined) close.memberMetadataHashes = derivedMetadataHashes;
+	else if (suppliedMetadataHashes)
+		close.memberMetadataHashes = { ...derivedMetadataHashes, ...suppliedMetadataHashes };
+	if (close.memberReceipts === undefined) close.memberReceipts = derivedReceipts;
+	const requestedUnion = qualityGateObject(close.unionChangeSet);
+	const union: JsonObject = requestedUnion ? { ...requestedUnion } : {};
+	if (union.source === undefined) union.source = "validation-batch";
+	if (union.paths === undefined) {
+		union.paths = (input.changeSet?.paths ?? []).map(row => ({
+			path: row.path,
+			status: row.status,
+			...(row.oldPath ? { oldPath: row.oldPath } : {}),
+		}));
+	}
+	try {
+		const unionRows = canonicalChangeSetRows(union.paths, "validationBatchClose.unionChangeSet.paths");
+		const suppliedChangeSetHashes = qualityGateObject(union.memberChangeSetHashes);
+		const memberChangeSetHashes: Record<string, unknown> = {
+			...derivedChangeSetHashes,
+			[metadata.finalGoalId]: changeSetHashForPaths(unionRows),
+			...suppliedChangeSetHashes,
+		};
+		if (union.memberChangeSetHashes === undefined || suppliedChangeSetHashes) {
+			union.memberChangeSetHashes = memberChangeSetHashes;
+		}
+		if (union.unionHash === undefined) {
+			union.unionHash = hashStructuredValue({
+				memberChangeSetHashes: qualityGateObject(union.memberChangeSetHashes) ?? memberChangeSetHashes,
+				paths: unionRows.map(row => ({ path: row.path, status: row.status, oldPath: row.oldPath })),
+			});
+		}
+	} catch {
+		// Malformed rows: leave derived hashes unset so validation reports the row defect.
+	}
+	close.unionChangeSet = union;
+	return { ...input.gate, validationBatchClose: close };
+}
+
 function validateDeferredCompletionQualityGate(
 	gate: JsonObject,
 	goal: UltragoalGoal,
@@ -2251,7 +2436,9 @@ function validateDeferredCompletionQualityGate(
 	}
 	const deferredLanes = stringArray(deferred.deferredLanes)?.filter(Boolean).sort();
 	if (deferredLanes?.join(",") !== "architectReview,executorQa")
-		throw new Error("deferredToBatch.deferredLanes must be architectReview and executorQa");
+		throw new Error(
+			"deferredToBatch.deferredLanes must be architectReview and executorQa (or omitted; the runtime fills it)",
+		);
 	const targeted = qualityGateObject(deferred.targetedVerification);
 	if (!targeted || targeted.status !== PASSED_STATUS || !nonEmptyStringArray(targeted.commands))
 		throw new Error("deferredToBatch.targetedVerification must pass with non-empty commands");
@@ -2276,13 +2463,17 @@ function validateDeferredCompletionQualityGate(
 	const declaredChangeSet = qualityGateObject(deferred.changeSet);
 	if (!declaredChangeSet) throw new Error("deferredToBatch.changeSet is required");
 	if (declaredChangeSet.memberGoalId !== goal.id)
-		throw new Error("deferredToBatch.changeSet.memberGoalId must label the checkpointed goal");
+		throw new Error(
+			`deferredToBatch.changeSet.memberGoalId must label the checkpointed goal ${goal.id} (or be omitted; the runtime fills it)`,
+		);
 	if (declaredChangeSet.cumulativeFromBase !== true)
-		throw new Error("deferredToBatch.changeSet.cumulativeFromBase must be true");
+		throw new Error("deferredToBatch.changeSet.cumulativeFromBase must be true (or omitted; the runtime fills it)");
 	const paths = canonicalChangeSetRows(declaredChangeSet.paths, "deferredToBatch.changeSet.paths");
 	requireChangeSetCoverage(changeSet, paths, "deferredToBatch.changeSet.paths");
 	if (declaredChangeSet.changeSetHash !== changeSetHashForPaths(paths))
-		throw new Error("deferredToBatch.changeSet.changeSetHash does not match declared paths");
+		throw new Error(
+			"deferredToBatch.changeSet.changeSetHash does not match declared paths; omit changeSetHash and the runtime computes it",
+		);
 }
 const COHORT_LANE_KEYS = ["cleaner", "architect", "qa"] as const;
 
@@ -2775,6 +2966,182 @@ function hydrateReviewedBatchReplacementClose(input: {
 		},
 	};
 }
+/**
+ * Scaffold a schema-shaped quality-gate template for selected surfaces (#3474).
+ * The template is intentionally incomplete for live artifact proofs so `quality-gate
+ * validate` can report remaining evidence gaps in one pass after the author fills paths.
+ */
+export function buildQualityGateInitTemplate(surfaces: readonly string[]): JsonObject {
+	const normalized = surfaces.length > 0 ? surfaces.map(surface => surface.trim()).filter(Boolean) : ["web"];
+	const unique: string[] = [];
+	for (const surface of normalized) {
+		if (!unique.includes(surface)) unique.push(surface);
+	}
+
+	const artifactRefs: JsonObject[] = [
+		{
+			id: "adversarial-report",
+			kind: "failure-mode-test",
+			path: "artifacts/adversarial-report.txt",
+			description: "Adversarial boundary and failure-mode test output",
+			inlineEvidence:
+				"Adversarial boundary cases exercised invalid input, missing state, and repeated submission without violating the contract.",
+		},
+	];
+	const surfaceEvidence: JsonObject[] = [];
+	const contractCoverage: JsonObject[] = [];
+	const adversarialCases: JsonObject[] = [
+		{
+			id: "case-invalid-input",
+			contractRef: "approved-plan:goal",
+			scenario: "Submit invalid or boundary input through the user-facing surface",
+			expectedBehavior: "The implementation rejects or handles the case according to the approved contract",
+			verdict: "passed",
+			artifactRefs: ["adversarial-report"],
+		},
+	];
+
+	unique.forEach((surface, index) => {
+		const surfaceId = `surface-${index + 1}`;
+		const family = surface.toLowerCase();
+		const linked: string[] = [];
+		if (family.includes("web") || family.includes("gui")) {
+			const browserId = `browser-run-${index + 1}`;
+			const shotId = `gui-screenshot-${index + 1}`;
+			linked.push(browserId, shotId);
+			artifactRefs.push(
+				{
+					id: browserId,
+					kind: "browser-automation",
+					path: `artifacts/${browserId}.json`,
+					description: "Browser automation transcript for the approved user-facing flow",
+					inlineEvidence:
+						"Browser automation executed the approved flow, asserted the expected visible result, and captured the final DOM state.",
+				},
+				{
+					id: shotId,
+					kind: "screenshot",
+					path: `artifacts/${shotId}.png`,
+					description: "Screenshot evidence for the GUI/web surface verdict",
+					inlineEvidence:
+						"Screenshot review confirmed the approved screen state, including the success message and absence of regression indicators.",
+				},
+			);
+		} else if (family.includes("cli")) {
+			const replayId = `cli-replay-${index + 1}`;
+			linked.push(replayId);
+			artifactRefs.push({
+				id: replayId,
+				kind: "cli-replay",
+				path: `artifacts/${replayId}.json`,
+				description: "CLI argv replay transcript for the approved command surface",
+				inlineEvidence:
+					"CLI replay executed the allowlisted command and verified recorded stdout against the approved contract.",
+			});
+		} else if (family.includes("api") || family.includes("package")) {
+			const reportId = `api-report-${index + 1}`;
+			linked.push(reportId);
+			artifactRefs.push({
+				id: reportId,
+				kind: "test-report",
+				path: `artifacts/${reportId}.xml`,
+				description: "API/package black-box test report",
+				inlineEvidence:
+					"API/package suite covered happy path, auth failure, and contract-breaking payloads with non-empty report output.",
+			});
+		} else {
+			const evidenceId = `surface-evidence-${index + 1}`;
+			linked.push(evidenceId);
+			artifactRefs.push({
+				id: evidenceId,
+				kind: "transcript",
+				path: `artifacts/${evidenceId}.txt`,
+				description: `Evidence transcript for surface ${surface}`,
+				inlineEvidence: `Surface ${surface} was exercised against the approved contract with recorded transcript evidence.`,
+			});
+		}
+
+		surfaceEvidence.push({
+			id: surfaceId,
+			surface: family.includes("web") || family.includes("gui") ? "gui/web" : surface,
+			contractRef: "approved-plan:goal",
+			invocation: `Exercise surface ${surface} against the approved contract`,
+			verdict: "passed",
+			artifactRefs: linked,
+		});
+		contractCoverage.push({
+			id: `contract-${index + 1}`,
+			contractRef: "approved-plan:goal",
+			obligation: `The completed story satisfies the approved contract on surface ${surface}`,
+			status: "covered",
+			surfaceEvidenceRefs: [surfaceId],
+			adversarialCaseRefs: ["case-invalid-input"],
+		});
+	});
+
+	return {
+		architectReview: {
+			architectureStatus: "CLEAR",
+			productStatus: "CLEAR",
+			codeStatus: "CLEAR",
+			recommendation: "APPROVE",
+			evidence: "architect reviewed architecture, product behavior, and code changes",
+			commands: ["architect-review"],
+			blockers: [],
+		},
+		executorQa: {
+			status: "passed",
+			e2eStatus: "passed",
+			redTeamStatus: "passed",
+			evidence: "executor built and ran e2e plus red-team QA suite",
+			e2eCommands: ["bun test:e2e"],
+			redTeamCommands: ["bun test:red-team"],
+			artifactRefs,
+			contractCoverage,
+			surfaceEvidence,
+			adversarialCases,
+			blockers: [],
+		},
+		criticReview: {
+			verdict: "OKAY",
+			evidence: "critic approved final aggregate",
+			blockers: [],
+		},
+		iteration: {
+			status: "passed",
+			evidence: "no verification findings remain after steering iterations",
+			fullRerun: true,
+			reviewCohort: {
+				reviewGeneration: 1,
+				sourceHash: "sha256:replace-with-frozen-source-hash",
+				joined: true,
+				lanes: {
+					cleaner: {
+						status: "passed",
+						sourceHash: "sha256:replace-with-frozen-source-hash",
+						evidence: "cleaner clean",
+						blockers: [],
+					},
+					architect: {
+						status: "CLEAR",
+						sourceHash: "sha256:replace-with-frozen-source-hash",
+						evidence: "architect clear",
+						blockers: [],
+					},
+					qa: {
+						status: "passed",
+						sourceHash: "sha256:replace-with-frozen-source-hash",
+						evidence: "qa passed",
+						blockers: [],
+					},
+				},
+			},
+			rerunCommands: ["bun test:e2e", "bun test:red-team"],
+			blockers: [],
+		},
+	};
+}
+
 /**
  * Read-only quality-gate validation (#3474). Applies exactly the same rules as
  * `checkpoint --status complete` — including deferred-vs-boundary gate selection and
@@ -2807,8 +3174,17 @@ export async function validateUltragoalQualityGateReadOnly(input: {
 	}
 	const ledger = plan ? await readUltragoalLedger(input.cwd, sessionId) : undefined;
 	const changeSet = await computeCheckpointChangeSet(input.cwd);
+	let hydratedGate = goal ? hydrateDeferredGateDefaults(gate, goal, changeSet) : gate;
+	if (goal && plan && ledger) {
+		hydratedGate = hydrateBatchCloseDefaults({ gate: hydratedGate, plan, goal, ledger, changeSet });
+	}
 	try {
-		await validateCompletionQualityGate(input.cwd, gate, { changeSet, plan: plan ?? undefined, goal, ledger });
+		await validateCompletionQualityGate(input.cwd, hydratedGate, {
+			changeSet,
+			plan: plan ?? undefined,
+			goal,
+			ledger,
+		});
 		return { valid: true, errors: [] };
 	} catch (error) {
 		if (error instanceof UltragoalQualityGateError) return { valid: false, errors: error.diagnostics };
@@ -2855,13 +3231,25 @@ async function readRequiredCompletionQualityGate(
 					changeSet: options.changeSet,
 				})
 			: gateObject;
-	await validateCompletionQualityGate(cwd, hydratedGate, {
+	let completionGate = options.goal
+		? hydrateDeferredGateDefaults(hydratedGate, options.goal, options.changeSet)
+		: hydratedGate;
+	if (options.goal && options.plan && options.ledger) {
+		completionGate = hydrateBatchCloseDefaults({
+			gate: completionGate,
+			plan: options.plan,
+			goal: options.goal,
+			ledger: options.ledger,
+			changeSet: options.changeSet,
+		});
+	}
+	await validateCompletionQualityGate(cwd, completionGate, {
 		changeSet: options.changeSet,
 		plan: options.plan,
 		goal: options.goal,
 		ledger: options.ledger,
 	});
-	return hydratedGate;
+	return completionGate;
 }
 
 function validateCompleteCheckpointTargetGoal(goal: UltragoalGoal): void {
@@ -3957,6 +4345,18 @@ function flagValue(args: readonly string[], flag: string): string | undefined {
 	return args[index + 1];
 }
 
+function flagValues(args: readonly string[], flag: string): string[] {
+	const values: string[] = [];
+	for (let index = 0; index < args.length; index += 1) {
+		if (args[index] !== flag) continue;
+		const value = args[index + 1];
+		if (value === undefined || value.startsWith("-")) continue;
+		values.push(value);
+		index += 1;
+	}
+	return values;
+}
+
 function hasFlag(args: readonly string[], flag: string): boolean {
 	return args.includes(flag);
 }
@@ -3985,6 +4385,8 @@ const FLAGS_WITH_VALUES = new Set([
 	"--order-json",
 	"--classification",
 	"--validation-batch-json",
+	"--out",
+	"--surface",
 ]);
 
 function isHelpArg(arg: string): boolean {
@@ -4114,6 +4516,28 @@ function renderUltragoalHelp(args: readonly string[]): string | null {
 		].join("\n");
 	}
 
+	if (subject === "quality-gate") {
+		return [
+			"Run native GJC Ultragoal workflow commands",
+			"",
+			"USAGE",
+			"  $ gjc ultragoal quality-gate init [--surface <name> ...] --out <path>",
+			"  $ gjc ultragoal quality-gate validate --quality-gate-json <json-or-path> [--goal-id <id>] [--json]",
+			"",
+			"FLAGS",
+			"      --surface=<value>            Surface to scaffold (repeatable; default web)",
+			"      --out=<value>                Output path for quality-gate init",
+			"      --quality-gate-json=<value>  JSON string or path for quality-gate validate",
+			"      --goal-id=<value>            Optional durable goal id for rule-identical validation",
+			"      --json                       Machine-readable output",
+			"",
+			"EXAMPLES",
+			"  $ gjc ultragoal quality-gate init --surface web --surface api --out ./quality-gate.json",
+			"  $ gjc ultragoal quality-gate validate --quality-gate-json ./quality-gate.json --json",
+			"",
+		].join("\n");
+	}
+
 	return [
 		"Run native GJC Ultragoal workflow commands",
 		"",
@@ -4131,10 +4555,11 @@ function renderUltragoalHelp(args: readonly string[]): string | null {
 		"  classify-blocker",
 		"  record-critic-verdict",
 		"  record-critic-gate-override",
+		"  quality-gate init",
 		"  quality-gate validate",
 
 		"",
-		"Run `gjc ultragoal checkpoint --help`, `gjc ultragoal review --help`, `gjc ultragoal classify-blocker --help`, `gjc ultragoal record-critic-verdict --help`, or `gjc ultragoal record-critic-gate-override --help` for command-specific requirements.",
+		"Run `gjc ultragoal checkpoint --help`, `gjc ultragoal review --help`, `gjc ultragoal classify-blocker --help`, `gjc ultragoal record-critic-verdict --help`, or `gjc ultragoal record-critic-gate-override --help`, or `gjc ultragoal quality-gate --help` for command-specific requirements.",
 		"",
 	].join("\n");
 }
@@ -4510,12 +4935,32 @@ async function dispatchUltragoalCommand(args: string[], cwd: string): Promise<Ul
 				};
 			}
 			case "quality-gate": {
-				const positional = args.filter(arg => !arg.startsWith("--"));
+				const positional = args.filter(arg => !arg.startsWith("-"));
 				const subcommand = positional[1];
+				if (subcommand === "init") {
+					const out = flagValue(args, "--out");
+					if (!out?.trim()) {
+						return { status: 1, stderr: "quality-gate init requires --out <path>\n" };
+					}
+					const surfaces = flagValues(args, "--surface");
+					const template = buildQualityGateInitTemplate(surfaces);
+					const resolved = path.resolve(cwd, out);
+					await Bun.write(resolved, `${JSON.stringify(template, null, 2)}\n`);
+					if (json) {
+						return {
+							status: 0,
+							stdout: `${JSON.stringify({ ok: true, out: resolved, surfaces: surfaces.length > 0 ? surfaces : ["web"] }, null, 2)}\n`,
+						};
+					}
+					return {
+						status: 0,
+						stdout: `Wrote quality-gate template to ${resolved}\n`,
+					};
+				}
 				if (subcommand !== "validate") {
 					return {
 						status: 1,
-						stderr: `Unknown gjc ultragoal quality-gate subcommand: ${subcommand ?? "(missing)"}; only validate is supported\n`,
+						stderr: `Unknown gjc ultragoal quality-gate subcommand: ${subcommand ?? "(missing)"}; supported: init, validate\n`,
 					};
 				}
 				const qualityGateJson = flagValue(args, "--quality-gate-json");

package/src/gjc-runtime/workflow-manifest.generated.json

@@ -466,6 +466,9 @@
       {
         "id": "critic"
       },
+      {
+        "id": "disposition"
+      },
       {
         "id": "revision"
       },
@@ -507,6 +510,21 @@
         "to": "critic",
         "verb": "write-artifact"
       },
+      {
+        "from": "critic",
+        "to": "disposition",
+        "verb": "write-artifact"
+      },
+      {
+        "from": "architect",
+        "to": "disposition",
+        "verb": "write-artifact"
+      },
+      {
+        "from": "disposition",
+        "to": "revision",
+        "verb": "write-artifact"
+      },
       {
         "from": "critic",
         "to": "revision",
@@ -522,6 +540,11 @@
         "to": "post-interview",
         "verb": "write-artifact"
       },
+      {
+        "from": "disposition",
+        "to": "post-interview",
+        "verb": "write-artifact"
+      },
       {
         "from": "post-interview",
         "to": "revision",
@@ -557,6 +580,11 @@
         "to": "handoff",
         "verb": "handoff"
       },
+      {
+        "from": "disposition",
+        "to": "handoff",
+        "verb": "handoff"
+      },
       {
         "from": "revision",
         "to": "handoff",
@@ -727,6 +755,7 @@
           "planner",
           "architect",
           "critic",
+          "disposition",
           "revision",
           "post-interview",
           "adr",