lazycodex-ai 5.0.0-beta.9 → 5.0.0

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

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

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// report-tools.mjs - the ulw-research deliverable CLI. Invoked as
+//   node "$SKILL_DIR/scripts/report-tools.mjs" <command> ...
+// Exit codes: 0 pass, 1 semantic failure (blockers, a failed verify, a blocked repair), 2 usage or IO.
+
+import { CliError, emit, exitCodeFor } from "./cli-support.mjs"
+import { isCliEntry } from "./entry-guard.mjs"
+import { runCheck, runFormatExtract, runLayoutProbe, runOutcome, runRepairDecide } from "./report-tools-commands.mjs"
+
+export const COMMANDS = Object.freeze([
+	"check",
+	"layout-probe",
+	"repair decide",
+	"outcome init",
+	"outcome set",
+	"outcome gate",
+	"outcome render",
+	"outcome state",
+	"outcome verify",
+	"outcome finish",
+	"outcome briefing",
+	"format-extract",
+])
+
+export async function run(argv) {
+	const [command, ...rest] = argv
+	switch (command) {
+		case "check":
+			return runCheck(rest)
+		case "layout-probe":
+			return runLayoutProbe(rest)
+		case "repair":
+			if (rest[0] !== "decide") throw new CliError("usage: repair decide --state <file> --defects <json>")
+			return runRepairDecide(rest.slice(1))
+		case "outcome":
+			return runOutcome(rest)
+		case "format-extract":
+			return runFormatExtract(rest)
+		case "--help":
+		case "help":
+			if (rest.includes("--json")) return { json: { commands: COMMANDS }, exitCode: 0 }
+			return { text: `report-tools <command>\n${COMMANDS.map((name) => `  ${name}`).join("\n")}`, exitCode: 0 }
+		default:
+			throw new CliError(`usage: report-tools <${COMMANDS.join(" | ")}> (run --help)`)
+	}
+}
+
+export async function main(argv = process.argv.slice(2)) {
+	try {
+		const result = await run(argv)
+		emit(result)
+		return exitCodeFor(result)
+	} catch (error) {
+		process.stderr.write(`report-tools: ${error.message}\n`)
+		return exitCodeFor(error)
+	}
+}
+
+if (isCliEntry(import.meta.url)) {
+	process.exitCode = await main()
+}

package/packages/omo-codex/plugin/skills/visual-qa/AGENTS.md

@@ -0,0 +1,58 @@
+# visual-qa — Bundled Visual-Evidence CLI
+
+**Generated:** 2026-08-24 (f3642fcda)
+
+## OVERVIEW
+
+The visual-QA skill's executable core: a zero-dependency Node CLI that produces machine evidence (`image-diff`, `tui-check`) plus the TypeScript sources it is bundled from. Earned this file: the only shared skill shipping a built bundle whose runtime and development sources must be kept in lockstep.
+
+## STRUCTURE
+
+```
+visual-qa/
+├── SKILL.md                      # reviewer workflow (dual oracle, evidence gates) — the prose contract
+├── references/browser-setup.md
+└── scripts/
+    ├── visual-qa.mjs             # SHIPPED RUNTIME: bun-build bundle of cli.ts (+ embedded modules)
+    ├── cli.ts                    # development source; dispatches image-diff / tui-check
+    ├── image-diff.ts             # diffImages — 8x8 grid cells, hotspots, rounded metrics
+    ├── tui-grid.ts               # checkTui — column overflow + border alignment verdicts
+    ├── east-asian-width.ts       # charWidth / stringWidth — CJK-aware width math
+    ├── ansi.ts                   # ANSI escape stripping (width must be escape-aware)
+    ├── png-decode.ts / png-crc.ts / png-synth.ts   # stdlib PNG codec (no deps)
+    ├── types.ts
+    └── *.test.ts                 # co-located bun tests for every module above
+```
+
+## BUNDLE/SOURCE DUALITY
+
+`visual-qa.mjs` is the artifact the skill's commands invoke (`node "$SKILL_DIR/scripts/visual-qa.mjs" …`); the `.ts` files exist for development and tests only. A behavior fix lands in the TS source AND the bundle is regenerated from `cli.ts` — editing one without the other makes tests and runtime disagree. Never hand-edit the `.mjs`.
+
+## SURFACE
+
+- Commands: `image-diff <reference.png> <actual.png>` and `tui-check <capture.txt> --cols <N>`; JSON verdict output (hotspot cells, overflow lines, wide-char columns, border alignment).
+- Module exports: `diffImages`, `checkTui`, `charWidth`/`stringWidth`, ANSI + PNG helpers. `cli.ts` owns `CliError`, `parseColumns`, `run`, `main`.
+
+## CONVENTIONS
+
+- Zero runtime dependencies — PNG decode/synthesis and ANSI handling are hand-rolled in `scripts/`; keep it that way (the bundle must stay require-free apart from `node:` builtins).
+- Width is never `String.length`: CJK wide characters and ANSI escapes are accounted for before any column math.
+- Tests are co-located `bun test scripts/*.test.ts`, given/when/then style per repo convention.
+
+## ANTI-PATTERNS
+
+- NEVER hand-edit `visual-qa.mjs`; regenerate from source.
+- Don't add an npm dependency to make PNG/diff easier — the no-dep bundle is the point.
+- Column math that ignores CJK width or ANSI escapes is wrong by construction; `tui-check` exists because text-diff tools get terminal grids wrong.
+- Skill-level rule worth repeating for code changes: `tmux capture-pane` is forbidden as a capture mechanism.
+
+## COMMANDS
+
+```bash
+# from packages/shared-skills/skills/visual-qa/
+node scripts/visual-qa.mjs image-diff <reference.png> <actual.png>
+node scripts/visual-qa.mjs tui-check <capture.txt> --cols 80
+bun test scripts/*.test.ts
+```
+
+- Parent: [`packages/shared-skills/AGENTS.md`](../../AGENTS.md).

package/packages/omo-codex/plugin/skills/visual-qa/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: visual-qa
-description: "MUST USE after building/changing any UI or when asked whether a page, component, or TUI looks right. Rigorous visual QA across web/page and terminal UIs. Prefer browser:control-in-app-browser for unauthenticated browser/page QA in Codex, then Playwright/agent-browser/dev-browser. Captures screenshot/TUI evidence with bundled diff scripts, runs design-system/functional and visual-fidelity/CJK reviewer passes, then synthesizes a good/bad verdict. Triggers: visual QA, screenshot/pixel diff, UI looks wrong, reference fidelity, design system check, responsive check, CJK text clipping, TUI alignment, box-drawing drift."
+description: "Runs rigorous visual QA across web, terminal, and paginated surfaces with screenshot evidence and a verdict. Use for any UI build or change, or when asked whether a page, component, or TUI looks right."
 ---
 
 ## Codex Harness Tool Compatibility
@@ -12,17 +12,19 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 | `call_omo_agent(subagent_type="explore", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as an explorer. ...","agent_type":"explorer","fork_context":false})` |
 | `call_omo_agent(subagent_type="librarian", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a librarian. ...","agent_type":"librarian","fork_context":false})` |
 | `task(subagent_type="plan", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a planning agent. ...","agent_type":"plan","fork_context":false})` |
-| `task(subagent_type="oracle", ...)` for final verification | `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"lazycodex-gate-reviewer","fork_context":false})` |
-| `task(category="...", ...)` for implementation or QA | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false})` |
+| `task(subagent_type="oracle", ...)` for final verification | By default, record a self-review in the notepad: re-read the diff, run diagnostics, and capture evidence for every acceptance criterion. Only when the user demanded strict, rigorous, or high-accuracy review, use `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"lazycodex-gate-reviewer","fork_context":false})`; include `fork_context: false`. |
+| `task(category="...", ...)` for implementation or QA | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","agent_type":"lazycodex-worker-medium","fork_context":false})` |
 | `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals |
 | `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent` and `multi_agent_v1.wait_agent`; use `multi_agent_v1.send_input` and `multi_agent_v1.close_agent` only when exposed in the active tools list |
 
-Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
+Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. Inspect the actual spawn schema: whenever `agent_type` is exposed, EVERY spawn MUST select an exact LazyCodex role, on V1 or V2. Implementation difficulty selects `lazycodex-worker-low`, `lazycodex-worker-medium`, or `lazycodex-worker-high`; clone QA can select `lazycodex-clone-fidelity-reviewer`. Never select generic `worker` or `default`. If a code block below conflicts with this section, this section wins.
 
-Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. On the v2 surface `agent_type` may be ABSENT from the spawn schema (verified 2026-07-11: only `fork_turns`/`message`/`task_name`) — when absent, omit it and describe the role inside `message`; installed role TOMLs cannot be selected on that surface. If a code block below conflicts with this section, this section wins.
+Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. Do not infer role support from V1/V2 or a model version. Legacy-schema exception: only if the actual schema lacks `agent_type`, omit that unsupported field and carry the complete role instructions in `message`, with history explicitly disabled. This cannot select a specialized TOML; an installed managed default supplies the medium worker for unnamed non-forks. The guard has no schema metadata and rejects unnamed calls, so report incompatible routing instead of retrying generically. Every deliberate full-history fork must still name its role: Codex skips role application on unnamed full-history forks, an upstream gap no LazyCodex default can repair. If a code block below conflicts with this section, this section wins. `fork_context` is rejected on `multi_agent_v2` (`fork_context is not supported in MultiAgentV2; use fork_turns instead`).
 
 When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
 
+Omit optional keys you do not set. Never send `items: []`, `message: ""`, `model: ""`, `reasoning_effort: ""`, or `service_tier: ""` — Codex rejects them (`Items can't be empty`, `reasoning_effort must not be empty`).
+
 For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived; back off between waits (double the timeout up to ~5 minutes) instead of spinning short cycles. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 # Visual QA - Dual-Oracle Web and TUI Verification
@@ -31,7 +33,7 @@ Verify a rendered UI against intent using objective script evidence plus two par
 
 ## Purpose and when to use
 
-- Use after you build or change any UI, before calling it done. Covers web/page UIs and TUI/terminal UIs.
+- Use after you build or change any UI, before calling it done. Covers web/page UIs, TUI/terminal UIs, and paginated documents.
 - Use when output must match a mock, a baseline, or a stated design intent; when you suspect a regression; when CJK (Korean/Japanese/Chinese) text may clip, misalign, or wrap awkwardly; when a claimed design system might actually be a flat image; when a terminal layout may overflow or its borders may break.
 - Skip when there is no rendered surface (pure backend or library logic with no visual or terminal output). For broad post-implementation review use review-work; this skill is the visual specialist.
 
@@ -41,6 +43,7 @@ In the commands below, `$SKILL_DIR` is this skill's own directory (the folder co
 
 - Web/page UI: renders in a browser (HTML/CSS/JS, components, canvas, SVG). Evidence is screenshots.
 - TUI/terminal UI: renders as text in a terminal (box-drawing, panes, status lines, REPL/TUI apps). Evidence is terminal captures.
+- Paginated document: renders as ordered pages (PDF report, printed HTML, exported deck). Evidence is every page rendered to an image - `pdftoppm -png -r 150 <file>.pdf <prefix>` or the pipeline's own renderer. Extracted text is not evidence here: layout is exactly what extraction discards, so a stranded block, a split table, or a near-empty page survives a clean text check.
 - Reference-fidelity UI: any web/page UI built from a concrete reference packet, including screenshots, generated Imagen/Stitch mockups, Figma exports, overview text, annotations, or source-site captures. Evidence is the full reference packet plus same-size actual captures.
 
 If the change touches both, run both capture tracks and feed both into the passes.
@@ -70,7 +73,7 @@ Before any reviewer sees an image, verify each capture yourself: the file signat
 ### Web
 
 1. Capture a REFERENCE image: the user's mock/target, generated page snapshot, Figma export, source-site capture, or known-good baseline. Save as PNG. If the user provided overview text or annotations, save them next to the image and treat them as part of the reference packet.
-2. Capture the ACTUAL rendered screenshot at the same viewport size. In Codex, when `browser:control-in-app-browser` is available and the page does not need an authenticated user browser session, use that Browser plugin first for navigation, page state inspection, and screenshots. If it is unavailable or lacks the needed capture action, use the project's configured browser tooling (the playwright, agent-browser, or dev-browser skill). Save as PNG. If none is configured or available, install [agent-browser](https://github.com/vercel-labs/agent-browser) (`npm install -g agent-browser && agent-browser install`) and capture with it — see `$SKILL_DIR/references/agent-browser-setup.md` for the full setup, including how to shoot a fixed-viewport screenshot.
+2. Capture the ACTUAL rendered screenshot at the reference viewport with omowright from js eval (the library is staged in the `browser` skill): the owned engine (`connectPipe` on a task-owned profile, viewport pinned with `emulate`, then `page.screenshot()`) for anything unauthenticated, or the attached engine (`connectBrowserSkill()` → `session.screenshot()`) when the page needs the user's login — never a clone of, or a launch against, the user's live profile. Save PNG and return its path; close the browser or stop the session. See `$SKILL_DIR/references/browser-setup.md` for fixed-viewport examples and prerequisites.
 3. Run the diff and keep the JSON:
 
 ```

package/packages/omo-codex/plugin/skills/visual-qa/references/browser-setup.md

@@ -0,0 +1,77 @@
+# Browser setup (Web capture)
+
+Capture with omowright from the js-eval kernel. The library is staged inside the `browser` skill;
+load it once per session:
+
+```js
+const { loadOmowright } = await import("<browser-skill-root>/scripts/omowright.mjs")
+const { omowright } = await loadOmowright()
+```
+
+## Owned engine (default for QA)
+
+A browser your code launches, with a task-owned profile, pinned viewport and no user state.
+`connectPipe` opens no listening port and reaps the process on `close()`.
+
+```js
+// js-eval cell; url and pngPath belong to this QA run.
+const { mkdtempSync, rmSync } = await import("node:fs")
+const profile = mkdtempSync(`${(await import("node:os")).tmpdir()}/visual-qa-`)
+const browser = await omowright.connectPipe({
+  browserPath: chromeBinary,                      // installed Chrome, Chromium, CloakBrowser or chrome-headless-shell
+  browserArgs: ["--headless", "--no-first-run", `--user-data-dir=${profile}`],
+  storageRoot: profile,
+})
+try {
+  const page = await browser.newTab("about:blank")
+  await omowright.emulate(page, { width: 1280, height: 720, deviceScaleFactor: 1, mobile: false, hasTouch: false })
+  await page.goto(url, { waitUntil: "load" })
+  await Bun.write(pngPath, await page.screenshot())
+  console.log(pngPath)
+} finally {
+  await browser.close()
+  rmSync(profile, { recursive: true, force: true })
+}
+```
+
+Chrome must already be installed; report an absent executable rather than downloading a managed
+browser. For bot-scored or WAF targets use `connectCloakProfile({ profileDir })` (CloakBrowser
+with a pinned fingerprint seed) — the `browser` skill's `references/owned-engine/README.md`
+covers it.
+
+## Attached engine (authenticated pages)
+
+When the capture needs the user's login, drive the browser they are signed into instead of
+cloning its profile:
+
+```js
+const session = await omowright.connectBrowserSkill({ name: "visual-qa capture", focused: false })
+try {
+  await session.navigate(url, { waitUntil: "load" })
+  await session.resize(1280, 720)
+  const shot = await session.screenshot()            // { buffer, width, height }
+  await Bun.write(pngPath, shot.buffer)
+} finally {
+  await session.stop()
+}
+```
+
+NEVER launch anything against, or clear cookies/cache/site data from, the user's live profile;
+the attached engine is the only sanctioned way to a signed-in page. If no extension is connected,
+run the `browser` skill's `scripts/browser-install.mjs` for the browser the user actually uses
+(from memory, or its detection; on `needsChoice` ask them and pass `--browser=<id>`), relay its
+one human step, and wait — do
+not fall back to the owned engine for an authenticated criterion.
+
+## Capture a screenshot at a fixed viewport
+
+Match CSS viewport AND PNG dimensions: pin `deviceScaleFactor` through `emulate` (owned) or
+`resize` (attached) instead of resizing the PNG to force a pass. Wait for the specific page state
+(a locator, a `waitForURL`, a `createNetworkSnoop(page).waitFor(...)`), not a sleep, then compare:
+
+```sh
+node "$SKILL_DIR/scripts/visual-qa.mjs" image-diff reference.png actual.png
+```
+
+Inspect `dimensionsMatch` and `diffRatio`, then inspect the image. Close every browser and session
+and the fixture server, even on a failed capture; remove the owned profile in the same `finally`.