lazycodex-ai 5.0.0-beta.9 → 5.0.0

package/packages/shared-skills/skills/ulw-research/scripts/repair-tracker.mjs

@@ -0,0 +1,171 @@
+// repair-tracker.mjs - the bounded repair loop as a pure state machine.
+//
+// Every decide() call is one check of the current artifact: the first call is attempt 0 (the
+// initial check), each later call follows one repair already taken. The loop stops on max
+// attempts, a measure plateau, a repeated defect signature (oscillation), or the wall clock.
+// On a stop the artifact is delivered with its residual defects unless a content-integrity
+// code remains, which blocks delivery. Time is always injected; this module never reads a
+// clock. Severities come from contracts.mjs only, so no caller can demote a defect.
+
+import { DEFECT_CODES, INTEGRITY_CODES, REPAIR_DEFAULTS, SCHEMA_VERSION, validateRepairState } from "./contracts.mjs"
+
+/**
+ * @typedef {{ code: string, message?: string }} Defect
+ * @typedef {{ at: string, measure: number[], signature: string, action: string }} Attempt
+ * @typedef {{ schemaVersion: number, startedAt: string, budget: { maxAttempts: number, plateauLimit: number, wallClockMs: number }, integrityCodes: string[], attempts: Attempt[], consecutiveNonProgress: number, seenSignatures: string[] }} RepairState
+ * @typedef {{ action: "repair"|"deliver"|"block", reason: string|null, residual: Defect[], blocking: Defect[] }} Decision
+ */
+
+const SEVERITY_INDEX = Object.freeze({ blocker: 0, major: 1, minor: 2 })
+const MIN_ARTIFACT_BYTES = 512
+const MIN_RENDERS = 1
+
+export class RepairTrackerError extends Error {
+	/** @param {string} code @param {string} message */
+	constructor(code, message) {
+		super(message)
+		this.name = "RepairTrackerError"
+		this.code = code
+	}
+}
+
+function toIso(value, label) {
+	const date = value instanceof Date ? value : typeof value === "string" || typeof value === "number" ? new Date(value) : null
+	if (date === null || !Number.isFinite(date.getTime())) {
+		throw new RepairTrackerError("invalid_time", `${label} must be a Date, an ISO timestamp, or epoch milliseconds`)
+	}
+	return date.toISOString()
+}
+
+function assertKnownCode(code, label) {
+	if (typeof code !== "string" || !Object.hasOwn(DEFECT_CODES, code)) {
+		throw new RepairTrackerError("unknown_defect_code", `${label} ${JSON.stringify(code)} is not a known defect code`)
+	}
+}
+
+/** Callers may add integrity codes; the contract set is always included, so none can be removed. */
+function integritySet(extra) {
+	return new Set([...INTEGRITY_CODES, ...(extra ?? [])])
+}
+
+/**
+ * @param {{ maxAttempts?: number, plateauLimit?: number, wallClockMs?: number, integrityCodes?: Iterable<string>, startedAt: Date|string|number }} options
+ * @returns {RepairState}
+ */
+export function createTracker({ maxAttempts, plateauLimit, wallClockMs, integrityCodes, startedAt }) {
+	if (startedAt === undefined) throw new RepairTrackerError("invalid_time", "startedAt is required (the tracker never reads the clock)")
+	const codes = [...integritySet(integrityCodes)].sort()
+	for (const code of codes) assertKnownCode(code, "integrity code")
+	const state = {
+		schemaVersion: SCHEMA_VERSION,
+		startedAt: toIso(startedAt, "startedAt"),
+		budget: {
+			maxAttempts: maxAttempts ?? REPAIR_DEFAULTS.maxAttempts,
+			plateauLimit: plateauLimit ?? REPAIR_DEFAULTS.plateauLimit,
+			wallClockMs: wallClockMs ?? REPAIR_DEFAULTS.wallClockMs,
+		},
+		integrityCodes: codes,
+		attempts: [],
+		consecutiveNonProgress: 0,
+		seenSignatures: [],
+	}
+	assertValid(state)
+	return state
+}
+
+/** The artifact is worth delivering with residual defects only when it exists and was rendered. */
+export function isArtifactOk({ bytes, renders }) {
+	return Number.isFinite(bytes) && bytes >= MIN_ARTIFACT_BYTES && Number.isFinite(renders) && renders >= MIN_RENDERS
+}
+
+export function measureOf(defects) {
+	const measure = [0, 0, 0]
+	for (const defect of defects) measure[SEVERITY_INDEX[DEFECT_CODES[defect.code].severity]] += 1
+	return measure
+}
+
+export function signatureOf(defects) {
+	return [...new Set(defects.map((defect) => defect.code))].sort().join("|")
+}
+
+function lessThan(a, b) {
+	for (let i = 0; i < a.length; i += 1) {
+		if (a[i] !== b[i]) return a[i] < b[i]
+	}
+	return false
+}
+
+function stopReason(state, { signature, consecutiveNonProgress, repairsTaken, elapsedMs }) {
+	const { maxAttempts, plateauLimit, wallClockMs } = state.budget
+	if (state.seenSignatures.includes(signature)) return "oscillation"
+	if (consecutiveNonProgress >= plateauLimit) return "plateau"
+	if (repairsTaken >= maxAttempts) return "max_attempts"
+	if (elapsedMs >= wallClockMs) return "wall_clock"
+	return null
+}
+
+/**
+ * @param {RepairState} state a tracker state (createTracker or deserializeState)
+ * @param {Defect[]} defects the current check's defects
+ * @param {Date|string|number} now injected time of this check
+ * @param {{ artifactOk?: boolean }} [artifact] caller-supplied; see isArtifactOk
+ * @returns {{ state: RepairState, decision: Decision }}
+ */
+export function decide(state, defects, now, { artifactOk = false } = {}) {
+	if (!Array.isArray(defects)) throw new RepairTrackerError("invalid_defects", "defects must be an array")
+	defects.forEach((defect, index) => assertKnownCode(defect?.code, `defects[${index}].code`))
+	const at = toIso(now, "now")
+	const measure = measureOf(defects)
+	const signature = signatureOf(defects)
+	const previous = state.attempts.at(-1)
+	const consecutiveNonProgress = previous && !lessThan(measure, previous.measure) ? state.consecutiveNonProgress + 1 : 0
+	const repairsTaken = state.attempts.filter((attempt) => attempt.action === "repair").length
+	const integrity = integritySet(state.integrityCodes)
+	const blocking = defects.filter((defect) => integrity.has(defect.code))
+
+	/** @type {Decision} */
+	let decision
+	if (defects.length === 0) decision = { action: "deliver", reason: "clean", residual: [], blocking: [] }
+	else {
+		const elapsedMs = Date.parse(at) - Date.parse(state.startedAt)
+		const reason = stopReason(state, { signature, consecutiveNonProgress, repairsTaken, elapsedMs })
+		if (reason === null) decision = { action: "repair", reason: null, residual: [...defects], blocking }
+		else if (blocking.length > 0) decision = { action: "block", reason: "blocking", residual: [...defects], blocking }
+		else decision = { action: artifactOk ? "deliver" : "block", reason, residual: [...defects], blocking }
+	}
+
+	const next = {
+		...state,
+		budget: { ...state.budget },
+		integrityCodes: [...state.integrityCodes],
+		attempts: [...state.attempts, { at, measure, signature, action: decision.action }],
+		consecutiveNonProgress,
+		seenSignatures: state.seenSignatures.includes(signature) ? [...state.seenSignatures] : [...state.seenSignatures, signature],
+	}
+	return { state: next, decision }
+}
+
+function assertValid(state) {
+	const { ok, errors } = validateRepairState(state)
+	if (!ok) throw new RepairTrackerError("invalid_repair_state", `invalid repair state: ${errors.join("; ")}`)
+	if (!Array.isArray(state.integrityCodes)) throw new RepairTrackerError("invalid_repair_state", "integrityCodes must be an array")
+	for (const code of state.integrityCodes) assertKnownCode(code, "integrity code")
+}
+
+/** @returns {string} the repair-state.json text */
+export function serializeState(state) {
+	assertValid(state)
+	return `${JSON.stringify(state, null, 2)}\n`
+}
+
+/** @param {string} text repair-state.json contents @returns {RepairState} */
+export function deserializeState(text) {
+	let state
+	try {
+		state = JSON.parse(text)
+	} catch (error) {
+		throw new RepairTrackerError("invalid_repair_state", `repair state is not JSON: ${error.message}`)
+	}
+	assertValid(state)
+	return state
+}

package/packages/shared-skills/skills/ulw-research/scripts/repair-tracker.test.ts

@@ -0,0 +1,246 @@
+import { describe, expect, test } from "bun:test"
+
+import { REPAIR_DEFAULTS, validateRepairState } from "./contracts.mjs"
+import {
+	RepairTrackerError,
+	createTracker,
+	decide,
+	deserializeState,
+	isArtifactOk,
+	serializeState,
+} from "./repair-tracker.mjs"
+
+const START = "2026-09-24T00:00:00.000Z"
+const MINUTE = 60 * 1000
+const OK = { artifactOk: true }
+
+function at(minutes: number): string {
+	return new Date(Date.parse(START) + minutes * MINUTE).toISOString()
+}
+
+function defects(...codes: string[]) {
+	return codes.map((code) => ({ code, message: `${code} found` }))
+}
+
+type Step = { codes: string[]; minutes?: number }
+
+function runSequence(options: Record<string, unknown>, steps: Step[], extra: Record<string, unknown> = OK) {
+	let state = createTracker({ startedAt: START, ...options })
+	const decisions = []
+	for (const [index, step] of steps.entries()) {
+		const result = decide(state, defects(...step.codes), at(step.minutes ?? index), extra)
+		state = result.state
+		decisions.push(result.decision)
+	}
+	return { state, decisions }
+}
+
+describe("createTracker", () => {
+	test("#given no budget #when a tracker is created #then it uses REPAIR_DEFAULTS and validates", () => {
+		const state = createTracker({ startedAt: START })
+
+		expect(state.budget).toEqual({ ...REPAIR_DEFAULTS })
+		expect(state.attempts).toEqual([])
+		expect(state.consecutiveNonProgress).toBe(0)
+		expect(validateRepairState(state)).toEqual({ ok: true, errors: [] })
+	})
+
+	test("#given no startedAt #when a tracker is created #then it throws instead of reading the clock", () => {
+		// @ts-expect-error startedAt is deliberately omitted to prove the runtime guard
+		expect(() => createTracker({})).toThrow(RepairTrackerError)
+	})
+
+	test("#given an empty integrityCodes list #when a blocker remains at stop #then the integrity code is still blocking", () => {
+		const { decisions } = runSequence({ maxAttempts: 1, integrityCodes: [] }, [
+			{ codes: ["missing_citation_section"] },
+			{ codes: ["missing_citation_section", "heading_generic"] },
+		])
+
+		expect(decisions[1]).toMatchObject({ action: "block", reason: "blocking" })
+	})
+
+	test("#given an extra integrity code #when it remains at stop #then delivery is blocked on it", () => {
+		const { decisions } = runSequence({ maxAttempts: 1, integrityCodes: ["em_dash_in_prose"] }, [
+			{ codes: ["em_dash_in_prose"] },
+			{ codes: ["em_dash_in_prose", "heading_generic"] },
+		])
+
+		expect(decisions[1].action).toBe("block")
+		expect(decisions[1].blocking.map((d: { code: string }) => d.code)).toEqual(["em_dash_in_prose"])
+	})
+
+	test("#given an unknown integrity code #when a tracker is created #then it throws a typed error", () => {
+		expect(() => createTracker({ startedAt: START, integrityCodes: ["not_a_code"] })).toThrow(RepairTrackerError)
+	})
+})
+
+describe("decide stop conditions", () => {
+	test("#given plateauLimit 2 #when the measure stops improving twice #then the fourth decide stops with plateau", () => {
+		// [0,3,1] -> [0,2,1] -> [0,2,1] -> [0,2,1], every signature distinct
+		const { decisions, state } = runSequence({ maxAttempts: 5, plateauLimit: 2 }, [
+			{ codes: ["emoji_in_prose", "em_dash_in_prose", "unsourced_number", "heading_generic"] },
+			{ codes: ["chart_without_figure", "chart_svg_no_text", "heading_too_long"] },
+			{ codes: ["korean_no_keep_all", "korean_serif_font", "palette_off_token"] },
+			{ codes: ["layout_overflow", "layout_text_clipped", "en_dash_in_prose"] },
+		])
+
+		expect(decisions.slice(0, 3).map((d) => d.action)).toEqual(["repair", "repair", "repair"])
+		expect(decisions[3]).toMatchObject({ action: "deliver", reason: "plateau" })
+		expect(decisions[3].residual.map((d: { code: string }) => d.code)).toEqual([
+			"layout_overflow",
+			"layout_text_clipped",
+			"en_dash_in_prose",
+		])
+		expect(state.consecutiveNonProgress).toBe(2)
+	})
+
+	test("#given the literal blocker plateau sequence #when it stops #then the integrity codes block delivery", () => {
+		// [2,1,0] -> [1,1,0] -> [1,1,0] -> [1,1,0]
+		const { decisions } = runSequence({ maxAttempts: 5, plateauLimit: 2 }, [
+			{ codes: ["missing_citation_section", "missing_closing_section", "emoji_in_prose"] },
+			{ codes: ["missing_citation_section", "em_dash_in_prose"] },
+			{ codes: ["missing_closing_section", "unsourced_number"] },
+			{ codes: ["broken_asset_reference", "layout_overflow"] },
+		])
+
+		expect(decisions.slice(0, 3).map((d) => d.action)).toEqual(["repair", "repair", "repair"])
+		expect(decisions[3]).toMatchObject({ action: "block", reason: "blocking" })
+		expect(decisions[3].blocking.map((d: { code: string }) => d.code)).toEqual(["broken_asset_reference"])
+	})
+
+	test("#given signatures A, B, A #when the third decide runs #then it stops with oscillation", () => {
+		const { decisions } = runSequence({ maxAttempts: 5 }, [
+			{ codes: ["emoji_in_prose", "heading_generic"] },
+			{ codes: ["unsourced_number"] },
+			{ codes: ["heading_generic", "emoji_in_prose"] },
+		])
+
+		expect(decisions.map((d) => d.action)).toEqual(["repair", "repair", "deliver"])
+		expect(decisions[2].reason).toBe("oscillation")
+	})
+
+	test("#given oscillation and plateau both hold #when decided #then oscillation wins by precedence", () => {
+		const { decisions } = runSequence({ maxAttempts: 5, plateauLimit: 1 }, [
+			{ codes: ["unsourced_number"] },
+			{ codes: ["unsourced_number"] },
+		])
+
+		expect(decisions[1]).toMatchObject({ action: "deliver", reason: "oscillation" })
+	})
+
+	test("#given maxAttempts 3 and improving measures #when the fourth decide runs #then it stops with max_attempts", () => {
+		// [0,3,0] -> [0,2,0] -> [0,1,0] -> [0,1,0], every signature distinct
+		const { decisions } = runSequence({ maxAttempts: 3 }, [
+			{ codes: ["emoji_in_prose", "em_dash_in_prose", "unsourced_number"] },
+			{ codes: ["chart_without_figure", "chart_svg_no_text"] },
+			{ codes: ["korean_serif_font"] },
+			{ codes: ["layout_text_clipped"] },
+		])
+
+		expect(decisions.slice(0, 3).map((d) => d.action)).toEqual(["repair", "repair", "repair"])
+		expect(decisions[3]).toMatchObject({ action: "deliver", reason: "max_attempts" })
+	})
+
+	test("#given the literal blocker max_attempts sequence #when the fourth decide runs #then it blocks", () => {
+		// [3,0,0] -> [2,0,0] -> [1,0,0] -> [1,0,0]
+		const { decisions } = runSequence({ maxAttempts: 3 }, [
+			{ codes: ["missing_citation_section", "missing_closing_section", "broken_asset_reference"] },
+			{ codes: ["missing_citation_section", "missing_required_section"] },
+			{ codes: ["missing_closing_section"] },
+			{ codes: ["missing_citation_section"] },
+		])
+
+		expect(decisions.slice(0, 3).map((d) => d.action)).toEqual(["repair", "repair", "repair"])
+		expect(decisions[3]).toMatchObject({ action: "block", reason: "blocking" })
+	})
+
+	test("#given wallClockMs 900000 and improving measures #when now is start + 15 min #then it stops with wall_clock", () => {
+		const { decisions } = runSequence({ maxAttempts: 5, wallClockMs: 900000 }, [
+			{ codes: ["emoji_in_prose", "em_dash_in_prose"], minutes: 0 },
+			{ codes: ["unsourced_number"], minutes: 7 },
+			{ codes: ["heading_generic"], minutes: 15 },
+		])
+
+		expect(decisions.map((d) => d.action)).toEqual(["repair", "repair", "deliver"])
+		expect(decisions[2].reason).toBe("wall_clock")
+	})
+
+	test("#given an integrity code and no stop condition #when decided #then it schedules a repair", () => {
+		const { decisions } = runSequence({}, [{ codes: ["missing_citation_section"] }])
+
+		expect(decisions[0]).toMatchObject({ action: "repair", reason: null })
+		expect(decisions[0].blocking.map((d: { code: string }) => d.code)).toEqual(["missing_citation_section"])
+	})
+
+	test("#given a stop without a usable artifact #when decided #then it blocks with the stop reason", () => {
+		const { decisions } = runSequence({ maxAttempts: 1 }, [{ codes: ["emoji_in_prose"] }, { codes: ["heading_generic"] }], {
+			artifactOk: false,
+		})
+
+		expect(decisions[1]).toMatchObject({ action: "block", reason: "max_attempts", blocking: [] })
+	})
+
+	test("#given zero defects #when decided #then it delivers clean", () => {
+		const { decisions } = runSequence({ maxAttempts: 1 }, [{ codes: ["emoji_in_prose"] }, { codes: [] }], { artifactOk: false })
+
+		expect(decisions[1]).toEqual({ action: "deliver", reason: "clean", residual: [], blocking: [] })
+	})
+
+	test("#given a defect with an unknown code #when decided #then it throws a typed error", () => {
+		const state = createTracker({ startedAt: START })
+		let caught: unknown
+		try {
+			decide(state, [{ code: "made_up_code", message: "x" }], at(1), OK)
+		} catch (error) {
+			caught = error
+		}
+
+		expect(caught).toBeInstanceOf(RepairTrackerError)
+		expect((caught as RepairTrackerError).code).toBe("unknown_defect_code")
+	})
+
+	test("#given an invalid now #when decided #then it throws a typed error", () => {
+		const state = createTracker({ startedAt: START })
+
+		expect(() => decide(state, [], "not a date", OK)).toThrow(RepairTrackerError)
+	})
+
+	test("#given a state #when decided #then the input state is not mutated", () => {
+		const state = createTracker({ startedAt: START })
+		const before = serializeState(state)
+		decide(state, defects("emoji_in_prose"), at(1), OK)
+
+		expect(serializeState(state)).toBe(before)
+	})
+})
+
+describe("isArtifactOk", () => {
+	test("#given bytes and renders #when checked #then it needs at least 512 bytes and one render", () => {
+		expect(isArtifactOk({ bytes: 512, renders: 1 })).toBe(true)
+		expect(isArtifactOk({ bytes: 511, renders: 1 })).toBe(false)
+		expect(isArtifactOk({ bytes: 4096, renders: 0 })).toBe(false)
+	})
+})
+
+describe("serializeState / deserializeState", () => {
+	test("#given a state after several decides #when round-tripped #then the bytes are identical and valid", () => {
+		const { state } = runSequence({ maxAttempts: 5 }, [{ codes: ["emoji_in_prose"] }, { codes: ["heading_generic"] }])
+		const text = serializeState(state)
+		const restored = deserializeState(text)
+
+		expect(serializeState(restored)).toBe(text)
+		expect(validateRepairState(restored)).toEqual({ ok: true, errors: [] })
+	})
+
+	test("#given a restored state #when decide continues #then it keeps the attempt history", () => {
+		const { state } = runSequence({ maxAttempts: 5 }, [{ codes: ["emoji_in_prose"] }, { codes: ["heading_generic"] }])
+		const { decision } = decide(deserializeState(serializeState(state)), defects("emoji_in_prose"), at(3), OK)
+
+		expect(decision.reason).toBe("oscillation")
+	})
+
+	test("#given an invalid state file #when deserialized #then it throws a typed error", () => {
+		expect(() => deserializeState('{"schemaVersion":1}')).toThrow(RepairTrackerError)
+		expect(() => deserializeState("not json")).toThrow(RepairTrackerError)
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/report-tools-commands.mjs

@@ -0,0 +1,214 @@
+// report-tools-commands.mjs - one function per report-tools subcommand. Each returns
+// { json | text, summary?, exitCode } and never exits the process; report-tools.mjs dispatches.
+
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+
+import { CliError, parseArgs, readJsonFile, writeJsonAtomic } from "./cli-support.mjs"
+import { REPAIR_DEFAULTS } from "./contracts.mjs"
+import { parseLineageMode, parsePalette, renderDesignSpec } from "./design-spec.mjs"
+import { extractFromHtml, extractFromPath, fetchHtml } from "./format-extract.mjs"
+import { checkLayout } from "./gates-layout.mjs"
+import { checkStatic } from "./gates-static.mjs"
+import { parseHtml } from "./html-lite.mjs"
+import { buildProbeSource } from "./layout-probe.mjs"
+import * as outcome from "./outcome.mjs"
+import { createTracker, decide, deserializeState, isArtifactOk, serializeState } from "./repair-tracker.mjs"
+
+const SEVERITY_ORDER = { blocker: 0, major: 1, minor: 2 }
+
+function readText(path) {
+	try {
+		return readFileSync(path, "utf8")
+	} catch (error) {
+		throw new CliError(`cannot read ${path}: ${error.code ?? error.message}`)
+	}
+}
+
+function nowFrom(flags) {
+	if (flags.now === undefined) return new Date()
+	const date = new Date(flags.now)
+	if (Number.isNaN(date.getTime())) throw new CliError("--now requires an ISO timestamp")
+	return date
+}
+
+function sessionDirFrom(flags) {
+	const dir = flags["session-dir"] ?? process.env.SESSION_DIR
+	if (!dir) throw new CliError("--session-dir is required (or set SESSION_DIR)")
+	return resolve(dir)
+}
+
+export function runCheck(argv) {
+	const args = parseArgs(argv, { repeatable: ["require-section"] })
+	const reportPath = args.positionals[0]
+	if (!reportPath) throw new CliError("usage: check <report.html> --design-spec <design-spec.md> [--layout <boxes.json>] [--require-section <regex>]... [--max-defects N]")
+	const specText = readText(args.required("design-spec"))
+	const doc = parseHtml(readText(reportPath))
+	const requireSections = (args.flags["require-section"] ?? []).map((source) => new RegExp(source, "i"))
+	const result = checkStatic(doc, {
+		palette: parsePalette(specText),
+		lineageMode: parseLineageMode(specText),
+		requireSections,
+		baseDir: dirname(resolve(reportPath)),
+	})
+	const defects = [...result.defects]
+	const gatesRun = [...result.gatesRun]
+	let layout = "not_run"
+	if (args.flags.layout !== undefined) {
+		const layoutResult = checkLayout(readJsonFile(args.flags.layout))
+		defects.push(...layoutResult.defects)
+		gatesRun.push("layout")
+		layout = layoutResult.defects.some((d) => d.severity === "blocker") ? "fail" : "pass"
+	}
+	defects.sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity] || (a.line ?? 0) - (b.line ?? 0) || a.code.localeCompare(b.code))
+	const counts = { blocker: 0, major: 0, minor: 0, total: defects.length }
+	for (const defect of defects) counts[defect.severity] += 1
+	const max = args.int("max-defects", 200)
+	const status = counts.blocker > 0 ? "fail" : "pass"
+	const exitCode = status === "fail" ? 1 : 0
+	return {
+		json: { command: "check", status, exitCode, layout, defects: defects.slice(0, max), counts, gatesRun, gatesSkipped: result.gatesSkipped },
+		summary: `check: ${status.toUpperCase()} - ${counts.blocker} blocker, ${counts.major} major, ${counts.minor} minor; layout ${layout}`,
+		exitCode,
+	}
+}
+
+export function runLayoutProbe(argv) {
+	const args = parseArgs(argv, { booleans: ["json"] })
+	const source = buildProbeSource({ cap: args.int("cap", 400), root: args.flags.root ?? "main, article" })
+	return args.flags.json ? { json: { command: "layout-probe", source }, exitCode: 0 } : { text: source, exitCode: 0 }
+}
+
+export function runRepairDecide(argv) {
+	const args = parseArgs(argv)
+	const statePath = args.required("state")
+	const now = nowFrom(args.flags)
+	const defectsInput = readJsonFile(args.required("defects"))
+	const defects = Array.isArray(defectsInput) ? defectsInput : defectsInput.defects
+	if (!Array.isArray(defects)) throw new CliError("--defects must be a JSON array or a check result with a defects array")
+	const state = existsSync(statePath)
+		? deserializeState(readText(statePath))
+		: createTracker({
+				maxAttempts: args.int("max-attempts", REPAIR_DEFAULTS.maxAttempts),
+				plateauLimit: args.int("plateau-limit", REPAIR_DEFAULTS.plateauLimit),
+				wallClockMs: args.int("wall-clock-ms", REPAIR_DEFAULTS.wallClockMs),
+				startedAt: now,
+			})
+	// Fail closed: deliver-on-exhaustion needs proof of a usable artifact (bytes and renders).
+	const artifactOk =
+		args.flags["artifact-bytes"] !== undefined && args.flags.renders !== undefined
+			? isArtifactOk({ bytes: Number(args.flags["artifact-bytes"]), renders: Number(args.flags.renders) })
+			: false
+	const { state: next, decision } = decide(state, defects, now, { artifactOk })
+	writeFileSync(statePath, serializeState(next))
+	recordRepair(args.flags, next, decision)
+	const exitCode = decision.action === "block" ? 1 : 0
+	return { json: { command: "repair decide", decision }, summary: `repair: ${decision.action}${decision.reason ? ` (${decision.reason})` : ""}`, exitCode }
+}
+
+/** With a session dir that holds outcome.json, the repair summary and residual list land in the manifest. */
+function recordRepair(flags, state, decision) {
+	const dir = flags["session-dir"] ?? process.env.SESSION_DIR
+	if (!dir) return
+	const file = join(resolve(dir), outcome.MANIFEST_FILENAME)
+	if (!existsSync(file)) return
+	const manifest = outcome.readManifest(file)
+	manifest.repair = { attempts: state.attempts.length, action: decision.action, reason: decision.reason }
+	if (decision.action !== "repair") manifest.residualDefects = decision.residual.map((defect) => ({ ...defect, message: defect.message ?? defect.code }))
+	outcome.writeManifest(file, manifest)
+}
+
+function manifestPath(flags) {
+	return join(sessionDirFrom(flags), outcome.MANIFEST_FILENAME)
+}
+
+export function runOutcome(argv) {
+	const [sub, ...rest] = argv
+	const args = parseArgs(rest, { booleans: ["json"] })
+	const file = sub === "state" ? null : manifestPath(args.flags)
+	switch (sub) {
+		case "init": {
+			const promised = args.required("promised").split(",").map((s) => s.trim()).filter(Boolean)
+			const manifest = outcome.initManifest({ sessionDir: sessionDirFrom(args.flags), promised, lane: args.flags.lane ?? null, now: nowFrom(args.flags) })
+			outcome.writeManifest(file, manifest)
+			return { json: { command: "outcome init", path: file, deliverables: manifest.deliverables }, exitCode: 0 }
+		}
+		case "set": {
+			const [format, status] = args.positionals
+			if (!format || !status) throw new CliError("usage: outcome set <format> <status> [--path p] [--reason r] [--pages n]")
+			const manifest = outcome.readManifest(file)
+			const detail = {}
+			if (args.flags.path !== undefined) {
+				detail.path = resolve(args.flags.path)
+				if (existsSync(detail.path)) detail.bytes = statSync(detail.path).size
+			}
+			if (args.flags.reason !== undefined) detail.reason = args.flags.reason
+			if (args.flags.pages !== undefined) detail.pages = args.int("pages")
+			outcome.writeManifest(file, outcome.setDeliverable(manifest, format, status, { ...detail, now: nowFrom(args.flags) }))
+			return { json: { command: "outcome set", format, status }, exitCode: 0 }
+		}
+		case "gate": {
+			const [gate, status] = args.positionals
+			if (!gate || !status) throw new CliError("usage: outcome gate <static|layout|visual|proofread> <pass|fail|not_run>")
+			outcome.writeManifest(file, outcome.setGate(outcome.readManifest(file), gate, status))
+			return { json: { command: "outcome gate", gate, status }, exitCode: 0 }
+		}
+		case "render": {
+			const [path] = args.positionals
+			if (!path) throw new CliError("usage: outcome render <path> --page N")
+			outcome.writeManifest(file, outcome.addRender(outcome.readManifest(file), resolve(path), args.int("page")))
+			return { json: { command: "outcome render", path: resolve(path) }, exitCode: 0 }
+		}
+		case "state": {
+			const deliverable = args.required("deliverable")
+			const sibling = join(dirname(resolve(deliverable)), outcome.MANIFEST_FILENAME)
+			const dir = args.flags["session-dir"] ?? process.env.SESSION_DIR
+			const candidate = dir ? join(resolve(dir), outcome.MANIFEST_FILENAME) : sibling
+			const manifest = existsSync(candidate) ? outcome.readManifest(candidate) : null
+			const state = outcome.deliverableState(resolve(deliverable), manifest)
+			return { json: { command: "outcome state", state }, summary: `state: ${state}`, exitCode: 0 }
+		}
+		case "verify": {
+			const result = outcome.verifyManifest(outcome.readManifest(file))
+			return { json: { command: "outcome verify", ...result }, summary: `verify: ${result.ok ? "OK" : `${result.problems.length} problem(s)`}`, exitCode: result.ok ? 0 : 1 }
+		}
+		case "finish": {
+			const manifest = outcome.readManifest(file)
+			const ledgerPath = args.flags.ledger ?? join(sessionDirFrom(args.flags), "sources-ledger.md")
+			const now = nowFrom(args.flags)
+			const facts = outcome.briefingFacts(manifest, existsSync(ledgerPath) ? readText(ledgerPath) : "", now)
+			manifest.finishedAt = now.toISOString()
+			manifest.elapsedMinutes = facts.minutes
+			manifest.sources = { total: facts.sources, domains: facts.domains }
+			outcome.writeManifest(file, manifest)
+			return { json: { command: "outcome finish", finishedAt: manifest.finishedAt, elapsedMinutes: facts.minutes, sources: manifest.sources }, exitCode: 0 }
+		}
+		case "briefing": {
+			const manifest = outcome.readManifest(file)
+			const ledgerPath = args.flags.ledger ?? join(sessionDirFrom(args.flags), "sources-ledger.md")
+			const ledger = existsSync(ledgerPath) ? readText(ledgerPath) : ""
+			const now = nowFrom(args.flags)
+			if (args.flags.json) return { json: { command: "outcome briefing", ...outcome.briefingFacts(manifest, ledger, now) }, exitCode: 0 }
+			return { text: outcome.buildBriefing(manifest, ledger, now), exitCode: 0 }
+		}
+		default:
+			throw new CliError("usage: outcome <init|set|gate|render|state|verify|finish|briefing> ...")
+	}
+}
+
+export async function runFormatExtract(argv) {
+	const args = parseArgs(argv, { booleans: ["from-url"] })
+	const [reference] = args.positionals
+	if (!reference) throw new CliError("usage: format-extract <reference> --out <design-spec.md> [--from-url]")
+	const out = args.required("out")
+	let extract
+	try {
+		extract = args.flags["from-url"] ? extractFromHtml(await fetchHtml(reference), { origin: reference }) : extractFromPath(reference)
+	} catch (error) {
+		// An unsupported, unreadable, or unreachable reference is an input problem (exit 2), not a gate result.
+		throw new CliError(`format-extract ${reference}: ${error.message}`)
+	}
+	writeJsonAtomic(`${out}.extract.json`, { ...extract, tokens: { light: Object.fromEntries(extract.tokens?.light ?? []), dark: Object.fromEntries(extract.tokens?.dark ?? []) } })
+	writeFileSync(out, renderDesignSpec(extract))
+	return { json: { command: "format-extract", out: resolve(out), origin: extract.origin, lineageMode: extract.lineageMode, notes: extract.notes ?? [] }, summary: `format-extract: wrote ${out}`, exitCode: 0 }
+}