oh-my-opencode 5.0.0-beta.89 → 5.0.0-beta.90

package/packages/omo-codex/plugin/skills/ulw-research/scripts/outcome.mjs

@@ -0,0 +1,250 @@
+// outcome.mjs - the per-run outcome manifest (`outcome.json`) and the closing briefing.
+// Manifest functions are pure (they return a new manifest); the briefing reads only the
+// manifest, the sources-ledger text, and an injected `now`. node: builtins only.
+
+import * as nodeFs from "node:fs"
+import { basename, dirname, join } from "node:path"
+
+import { DELIVERABLE_FORMATS, DELIVERABLE_STATUSES, GATE_NAMES, GATE_STATUSES, LANES } from "./contracts.mjs"
+import { MANIFEST_CODES, SCHEMA_VERSION, validateOutcomeManifest } from "./contracts.mjs"
+
+export const MANIFEST_FILENAME = "outcome.json"
+const MISSING = MANIFEST_CODES[0]
+const SESSION_STAMP = /^(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})$/
+const SOURCE_LINE = /^\[(S|Source )\d+\]/
+const URL_PATTERN = /https?:\/\/[^\s)<>\]"'`]+/g
+const DRAFT_MARKER = "STATUS: draft"
+const DRAFT_SCAN_LINES = 5
+const REASON_REQUIRED = new Set(["blocked_capability", "skipped", "failed"])
+
+export class OutcomeError extends Error {
+	/** @param {string} code @param {string} message @param {readonly string[]} [allowed] */
+	constructor(code, message, allowed) {
+		super(message)
+		this.name = "OutcomeError"
+		this.code = code
+		if (allowed) this.allowed = [...allowed]
+	}
+}
+
+function assertOneOf(code, label, value, allowed) {
+	if (!allowed.includes(value)) {
+		throw new OutcomeError(code, `unknown ${label} ${JSON.stringify(value)}; allowed: ${allowed.join(", ")}`, allowed)
+	}
+}
+
+const clone = (manifest) => structuredClone(manifest)
+const isMissing = (error) => error?.code === "ENOENT" || error?.code === "ENOTDIR"
+
+function stamp(now) {
+	return (now ?? new Date()).toISOString()
+}
+
+/** Local wall-clock start time from a `YYYYMMDD-HHMMSS` session dir basename. */
+export function parseSessionStart(sessionDir) {
+	const match = SESSION_STAMP.exec(basename(sessionDir))
+	if (!match) throw new OutcomeError("invalid_session_dir", `session dir basename must be YYYYMMDD-HHMMSS: ${sessionDir}`)
+	const [y, mo, d, h, mi, s] = match.slice(1).map(Number)
+	const date = new Date(y, mo - 1, d, h, mi, s)
+	if (date.getMonth() !== mo - 1 || date.getDate() !== d || date.getHours() !== h) {
+		throw new OutcomeError("invalid_session_dir", `session dir basename is not a real local time: ${sessionDir}`)
+	}
+	return date
+}
+
+/** @param {{ sessionDir: string, promised: string[], lane: string|null, interview?: object|null, now?: Date }} input */
+export function initManifest({ sessionDir, promised, lane, interview = null, now }) {
+	const startedAt = parseSessionStart(sessionDir).toISOString()
+	if (lane !== null && lane !== undefined) assertOneOf("unknown_lane", "lane", lane, LANES)
+	const formats = [...new Set(promised)]
+	for (const format of formats) assertOneOf("unknown_format", "deliverable format", format, DELIVERABLE_FORMATS)
+	const updatedAt = stamp(now)
+	return {
+		schemaVersion: SCHEMA_VERSION,
+		sessionDir,
+		startedAt,
+		finishedAt: null,
+		elapsedMinutes: null,
+		lane: lane ?? null,
+		interview,
+		deliverables: formats.map((format) => ({ format, status: "pending", promised: true, updatedAt })),
+		renders: [],
+		gates: Object.fromEntries(GATE_NAMES.map((gate) => [gate, "not_run"])),
+		residualDefects: [],
+		repair: null,
+		sources: null,
+	}
+}
+
+/**
+ * Set one format's row; every other row is kept as is. An unpromised format gets a new
+ * row with promised=false. The row's detail fields are replaced by the ones given.
+ * @param {{ path?: string, reason?: string, pages?: number, bytes?: number, now?: Date }} [detail]
+ */
+export function setDeliverable(manifest, format, status, detail = {}) {
+	assertOneOf("unknown_format", "deliverable format", format, DELIVERABLE_FORMATS)
+	assertOneOf("unknown_status", "deliverable status", status, DELIVERABLE_STATUSES)
+	const next = clone(manifest)
+	const index = next.deliverables.findIndex((row) => row.format === format)
+	const row = { format, status, promised: index >= 0 ? next.deliverables[index].promised : false, updatedAt: stamp(detail.now) }
+	for (const key of ["path", "reason", "pages", "bytes"]) {
+		if (detail[key] !== undefined) row[key] = detail[key]
+	}
+	if (index >= 0) next.deliverables[index] = row
+	else next.deliverables.push(row)
+	return next
+}
+
+export function setGate(manifest, gate, status) {
+	assertOneOf("unknown_gate", "gate", gate, GATE_NAMES)
+	assertOneOf("unknown_gate_status", "gate status", status, GATE_STATUSES)
+	const next = clone(manifest)
+	next.gates[gate] = status
+	return next
+}
+
+export function addRender(manifest, path, page) {
+	if (typeof path !== "string" || path.length === 0) throw new OutcomeError("invalid_render", "render path must be a non-empty string")
+	if (!Number.isInteger(page) || page < 1) throw new OutcomeError("invalid_render", `render page must be an integer >= 1, got ${page}`)
+	const next = clone(manifest)
+	if (!next.renders.some((render) => render.path === path && render.page === page)) next.renders.push({ path, page })
+	return next
+}
+
+function fileSize(fs, path) {
+	try {
+		const stat = fs.statSync(path)
+		return stat.isFile() ? stat.size : null
+	} catch (error) {
+		if (isMissing(error)) return null
+		throw error
+	}
+}
+
+/**
+ * @param {object} manifest
+ * @param {{ statSync: typeof nodeFs.statSync }} [fs]
+ * @returns {{ ok: boolean, problems: { code: string, format: string, message: string, path?: string }[] }}
+ */
+export function verifyManifest(manifest, fs = nodeFs) {
+	const problems = []
+	for (const row of manifest.deliverables) {
+		const problem = (message, path) => problems.push({ code: MISSING, format: row.format, message, ...(path ? { path } : {}) })
+		if (row.status === "pending") problem(`${row.format} is still pending`)
+		else if (row.status === "delivered") {
+			if (!row.path) problem(`${row.format} is delivered without a path`)
+			else {
+				const size = fileSize(fs, row.path)
+				if (size === null) problem(`${row.format} delivered file is missing: ${row.path}`, row.path)
+				else if (size === 0) problem(`${row.format} delivered file is empty: ${row.path}`, row.path)
+			}
+		} else if (REASON_REQUIRED.has(row.status) && !row.reason) problem(`${row.format} is ${row.status} without a reason`)
+	}
+	return { ok: problems.length === 0, problems }
+}
+
+/**
+ * none = missing or empty file; partial = `STATUS: draft` in the first 5 lines, or the
+ * manifest (given, else a sibling outcome.json) still has a pending row; else complete.
+ * @returns {"none"|"partial"|"complete"}
+ */
+export function deliverableState(deliverablePath, manifestOrNull) {
+	let text
+	try {
+		text = nodeFs.readFileSync(deliverablePath, "utf8")
+	} catch (error) {
+		if (isMissing(error)) return "none"
+		throw error
+	}
+	if (text.trim() === "") return "none"
+	if (text.split(/\r?\n/, DRAFT_SCAN_LINES).some((line) => line.includes(DRAFT_MARKER))) return "partial"
+	const sibling = join(dirname(deliverablePath), MANIFEST_FILENAME)
+	const manifest = manifestOrNull ?? (nodeFs.existsSync(sibling) ? readManifest(sibling) : null)
+	if (manifest && manifest.deliverables.some((row) => row.status === "pending")) return "partial"
+	return "complete"
+}
+
+/** Hostname without a leading `www.`; null for a string URL cannot parse (not a source host). */
+function hostOf(url) {
+	return URL.canParse(url) ? new URL(url).hostname.toLowerCase().replace(/^www\./, "") : null
+}
+
+function repairSummary(repair) {
+	if (!repair) return null
+	const attempts = Array.isArray(repair.attempts) ? repair.attempts.length : repair.attempts ?? null
+	return { attempts, action: repair.decision?.action ?? repair.action ?? null, reason: repair.decision?.reason ?? repair.reason ?? null }
+}
+
+/** The briefing numbers, from the manifest + ledger text + injected `now` only. */
+export function briefingFacts(manifest, sourcesLedgerText, now) {
+	const sourceLines = String(sourcesLedgerText ?? "").split(/\r?\n/).filter((line) => SOURCE_LINE.test(line))
+	const hosts = new Set()
+	for (const line of sourceLines) {
+		for (const url of line.match(URL_PATTERN) ?? []) {
+			const host = hostOf(url)
+			if (host) hosts.add(host)
+		}
+	}
+	const elapsedMs = now.getTime() - new Date(manifest.startedAt).getTime()
+	return {
+		sources: sourceLines.length,
+		domains: hosts.size,
+		hosts: [...hosts].sort(),
+		minutes: Math.max(0, Math.round(elapsedMs / 60000)),
+		deliverables: manifest.deliverables.map((row) => ({ format: row.format, status: row.status, reason: row.reason ?? null, path: row.path ?? null })),
+		gates: { ...manifest.gates },
+		residualDefects: manifest.residualDefects.length,
+		repair: repairSummary(manifest.repair),
+	}
+}
+
+/** The closing briefing block as plain text. */
+export function buildBriefing(manifest, sourcesLedgerText, now) {
+	const facts = briefingFacts(manifest, sourcesLedgerText, now)
+	const repair = facts.repair
+		? `${facts.repair.attempts ?? "?"} attempt(s), last decision ${facts.repair.action ?? "?"} (${facts.repair.reason ?? "?"})`
+		: "not run"
+	return [
+		"Closing briefing",
+		`- Sources: ${facts.sources} from ${facts.domains} distinct domain(s), counted from the sources ledger.`,
+		`- Elapsed: ${facts.minutes} minute(s) since ${manifest.startedAt}.`,
+		"- Deliverables:",
+		"  | format | status | detail |",
+		"  |---|---|---|",
+		...facts.deliverables.map((row) => `  | ${row.format} | ${row.status} | ${row.reason ?? row.path ?? ""} |`),
+		`- Gates: ${GATE_NAMES.map((gate) => `${gate} ${facts.gates[gate]}`).join(", ")}.`,
+		`- Residual defects: ${facts.residualDefects}.`,
+		`- Repair: ${repair}.`,
+	].join("\n")
+}
+
+function assertValid(manifest, where) {
+	const { ok, errors } = validateOutcomeManifest(manifest)
+	if (!ok) throw new OutcomeError("invalid_manifest", `${where}: ${errors.join("; ")}`)
+}
+
+export function readManifest(file) {
+	let manifest
+	try {
+		manifest = JSON.parse(nodeFs.readFileSync(file, "utf8"))
+	} catch (error) {
+		if (error instanceof SyntaxError) throw new OutcomeError("invalid_manifest", `${file}: not valid JSON (${error.message})`)
+		throw error
+	}
+	assertValid(manifest, file)
+	return manifest
+}
+
+/** Validate, then write atomically (temp file in the same dir + rename). */
+export function writeManifest(file, manifest) {
+	assertValid(manifest, file)
+	const temp = join(dirname(file), `.${basename(file)}.${process.pid}.${Date.now()}.tmp`)
+	try {
+		nodeFs.writeFileSync(temp, `${JSON.stringify(manifest, null, "\t")}\n`, "utf8")
+		nodeFs.renameSync(temp, file)
+	} catch (error) {
+		nodeFs.rmSync(temp, { force: true })
+		throw error
+	}
+	return file
+}

package/packages/omo-codex/plugin/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/omo-codex/plugin/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 }
+}