lazycodex-ai 5.0.0-beta.9 → 5.0.0

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

@@ -0,0 +1,102 @@
+// cli-support.mjs - argument parsing, typed usage errors, exit-code mapping, and JSON file IO
+// shared by every report-tools subcommand. node: builtins only.
+
+import { readFileSync, renameSync, writeFileSync } from "node:fs"
+import { basename, dirname, join } from "node:path"
+
+/** A usage or input error: always exit code 2. */
+export class CliError extends Error {
+	constructor(message) {
+		super(message)
+		this.name = "CliError"
+	}
+}
+
+const IO_CODES = new Set(["ENOENT", "EACCES", "EISDIR", "ENOTDIR", "EPERM"])
+
+/** 0 pass, 1 semantic failure (result.exitCode), 2 usage or IO error. */
+export function exitCodeFor(resultOrError) {
+	if (resultOrError instanceof CliError) return 2
+	if (resultOrError instanceof Error) return IO_CODES.has(resultOrError.code) ? 2 : 1
+	return resultOrError?.exitCode === 1 ? 1 : 0
+}
+
+/**
+ * Parse `--name value`, `--name=value`, boolean flags, and repeatable flags.
+ * @param {readonly string[]} argv
+ * @param {{ repeatable?: string[], booleans?: string[] }} spec
+ */
+export function parseArgs(argv, { repeatable = [], booleans = [] } = {}) {
+	const repeat = new Set(repeatable)
+	const bools = new Set(booleans)
+	const positionals = []
+	const flags = {}
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index]
+		if (!arg.startsWith("--")) {
+			positionals.push(arg)
+			continue
+		}
+		const eq = arg.indexOf("=")
+		const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq)
+		let value
+		if (bools.has(name) && eq === -1) value = true
+		else if (eq !== -1) value = arg.slice(eq + 1)
+		else {
+			value = argv[index + 1]
+			if (value === undefined || value.startsWith("--")) throw new CliError(`--${name} requires a value`)
+			index += 1
+		}
+		if (repeat.has(name)) flags[name] = [...(flags[name] ?? []), value]
+		else flags[name] = value
+	}
+	return {
+		positionals,
+		flags,
+		/** @param {string} name @param {number} [fallback] */
+		int(name, fallback) {
+			if (flags[name] === undefined) {
+				if (fallback === undefined) throw new CliError(`--${name} is required`)
+				return fallback
+			}
+			const parsed = Number(flags[name])
+			if (!Number.isInteger(parsed) || parsed <= 0) throw new CliError(`--${name} requires a positive integer`)
+			return parsed
+		},
+		/** @param {string} name */
+		required(name) {
+			const value = flags[name]
+			if (value === undefined || value === true) throw new CliError(`--${name} is required`)
+			return value
+		},
+	}
+}
+
+/** Read and parse a JSON file; a missing or malformed file is a CliError naming the path. */
+export function readJsonFile(path) {
+	let text
+	try {
+		text = readFileSync(path, "utf8")
+	} catch (error) {
+		throw new CliError(`cannot read ${path}: ${error.code ?? error.message}`)
+	}
+	try {
+		return JSON.parse(text)
+	} catch (error) {
+		throw new CliError(`${path} is not valid JSON: ${error.message}`)
+	}
+}
+
+/** Write JSON through a sibling temp file + rename, so a crash never leaves a half-written file. */
+export function writeJsonAtomic(path, value) {
+	const temp = join(dirname(path), `.${basename(path)}.${process.pid}.${Date.now()}.tmp`)
+	writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`)
+	renameSync(temp, path)
+}
+
+/** Print a result: JSON on stdout, one summary line on stderr. */
+export function emit(result, { stdout = process.stdout, stderr = process.stderr } = {}) {
+	if (typeof result.text === "string") stdout.write(result.text.endsWith("\n") ? result.text : `${result.text}\n`)
+	else stdout.write(`${JSON.stringify(result.json ?? result, null, 2)}\n`)
+	if (result.summary) stderr.write(`${result.summary}\n`)
+}

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

@@ -0,0 +1,162 @@
+// contracts.mjs - the fixed vocabulary every report-tools module shares.
+//
+// Severities live here and nowhere else: no module exports a way to change them, so a
+// content-integrity defect can never be demoted by a caller. Plain Node ESM, node: builtins
+// only, runnable by `node` and `bun` alike.
+
+export const SCHEMA_VERSION = 1
+
+function deepFreeze(value) {
+	if (value === null || typeof value !== "object") return value
+	for (const key of Object.keys(value)) deepFreeze(value[key])
+	return Object.freeze(value)
+}
+
+/** code -> { severity, integrity, hint }. integrity = blocks delivery even on repair exhaustion. */
+export const DEFECT_CODES = deepFreeze({
+	korean_no_keep_all: { severity: "major", integrity: false, hint: 'Add "word-break: keep-all; overflow-wrap: anywhere" to the body or the slide text container.' },
+	palette_off_token: { severity: "minor", integrity: false, hint: "Replace the literal color with a design-spec token (var(--...)) or add the color to the spec palette." },
+	emoji_in_prose: { severity: "major", integrity: false, hint: "Remove the emoji; use an inline SVG icon or plain text." },
+	em_dash_in_prose: { severity: "major", integrity: false, hint: "Rewrite the sentence with a comma, colon, or period instead of an em dash." },
+	en_dash_in_prose: { severity: "minor", integrity: false, hint: "Use a hyphen for compounds; keep the en dash only between numbers." },
+	heading_too_long: { severity: "minor", integrity: false, hint: "Shorten the heading to one line (26 Korean characters or 12 English words)." },
+	heading_generic: { severity: "minor", integrity: false, hint: "Make the heading carry the section's claim instead of a generic label." },
+	unsourced_number: { severity: "major", integrity: false, hint: "Tag the number MEASURED / ASSUMED / DERIVED or cite its source in the same paragraph." },
+	chart_without_figure: { severity: "major", integrity: false, hint: "Wrap the image or chart in a figure container with a caption." },
+	chart_svg_no_text: { severity: "major", integrity: false, hint: "Give the chart a title, axis labels, units, and value labels as SVG text." },
+	chart_svg_missing_labels: { severity: "minor", integrity: false, hint: "Add the missing title, axis ticks, or unit label to the chart." },
+	korean_serif_font: { severity: "major", integrity: false, hint: "Use a gothic (sans) Korean family; serif and brush families are banned by the design spec." },
+	section_without_citation: { severity: "major", integrity: false, hint: "Cite at least one source inside this section or merge it into a cited one." },
+	missing_closing_section: { severity: "blocker", integrity: true, hint: "Add the closing section that explains how the report was made (method, sources, gates)." },
+	missing_citation_section: { severity: "blocker", integrity: true, hint: "Add a sources or references section, or [S<n>] definition lines." },
+	broken_asset_reference: { severity: "blocker", integrity: true, hint: "Re-render or restore the missing asset file before delivery." },
+	missing_required_section: { severity: "blocker", integrity: true, hint: "Add the section the brief requires (matched by --require-section)." },
+	missing_promised_deliverable: { severity: "blocker", integrity: true, hint: "Produce the promised deliverable or record it as blocked_capability or skipped with a reason." },
+	layout_overflow: { severity: "major", integrity: false, hint: "Constrain the element to its container (max-width: 100%, overflow-wrap: anywhere, or a narrower measure)." },
+	layout_text_clipped: { severity: "major", integrity: false, hint: "Remove the overflow: hidden clip or give the text room to wrap." },
+	layout_scroll_container: { severity: "minor", integrity: false, hint: "Scrolling content prints clipped; make the content fit or wrap the table in a scroll wrapper only for HTML deliverables." },
+	layout_image_distorted: { severity: "major", integrity: false, hint: "Preserve the image aspect ratio (object-fit: contain inside a fixed container)." },
+	layout_sibling_overlap: { severity: "major", integrity: false, hint: "Separate the overlapping elements (margins, grid, or a slide split)." },
+})
+
+const LAYOUT_PREFIX = "layout_"
+/** Codes checkStatic can raise (G1-G15). */
+export const STATIC_CODES = Object.freeze(
+	Object.keys(DEFECT_CODES).filter((code) => !code.startsWith(LAYOUT_PREFIX) && code !== "missing_promised_deliverable"),
+)
+/** Codes checkLayout can raise (L1-L5). */
+export const LAYOUT_CODES = Object.freeze(Object.keys(DEFECT_CODES).filter((code) => code.startsWith(LAYOUT_PREFIX)))
+/** Codes only the outcome manifest verifier raises. */
+export const MANIFEST_CODES = Object.freeze(["missing_promised_deliverable"])
+
+export const INTEGRITY_CODES = Object.freeze(
+	new Set(Object.entries(DEFECT_CODES).filter(([, entry]) => entry.integrity).map(([code]) => code)),
+)
+
+export const LANES = Object.freeze(["template-strict", "template-vibe", "no-format", "edit-existing"])
+export const STATES = Object.freeze(["none", "partial", "complete"])
+export const DELIVERABLE_FORMATS = Object.freeze(["pdf", "docx", "html", "md", "latex", "slides", "post"])
+export const DELIVERABLE_STATUSES = Object.freeze(["pending", "delivered", "blocked_capability", "skipped", "failed"])
+export const GATE_NAMES = Object.freeze(["static", "layout", "visual", "proofread"])
+export const GATE_STATUSES = Object.freeze(["pass", "fail", "not_run"])
+export const LINEAGE_MODES = Object.freeze(["inline", "section"])
+export const ANSWERED_BY = Object.freeze(["user", "default", "request"])
+export const REPAIR_DEFAULTS = Object.freeze({ maxAttempts: 3, plateauLimit: 2, wallClockMs: 15 * 60 * 1000 })
+export const DESIGN_SPEC_SECTIONS = Object.freeze([
+	"Extracted from",
+	"Tokens",
+	"Typography",
+	"Layout",
+	"Structure",
+	"Figures",
+	"Citations",
+	"Open questions",
+])
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/
+
+function isObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+}
+
+function check(errors, condition, message) {
+	if (!condition) errors.push(message)
+}
+
+function validateDeliverable(row, index, errors) {
+	const at = `deliverables[${index}]`
+	if (!isObject(row)) return errors.push(`${at} must be an object`)
+	check(errors, DELIVERABLE_FORMATS.includes(row.format), `${at}.format must be one of ${DELIVERABLE_FORMATS.join(", ")}`)
+	check(errors, DELIVERABLE_STATUSES.includes(row.status), `${at}.status must be one of ${DELIVERABLE_STATUSES.join(", ")}`)
+	check(errors, typeof row.promised === "boolean", `${at}.promised must be a boolean`)
+	check(errors, typeof row.updatedAt === "string" && ISO_DATE.test(row.updatedAt), `${at}.updatedAt must be an ISO timestamp`)
+	for (const key of ["path", "reason"]) {
+		if (row[key] !== undefined) check(errors, typeof row[key] === "string", `${at}.${key} must be a string`)
+	}
+	for (const key of ["bytes", "pages"]) {
+		if (row[key] !== undefined) check(errors, Number.isInteger(row[key]) && row[key] >= 0, `${at}.${key} must be a non-negative integer`)
+	}
+}
+
+function validateDefect(defect, at, errors) {
+	if (!isObject(defect)) return errors.push(`${at} must be an object`)
+	check(errors, Object.hasOwn(DEFECT_CODES, defect.code), `${at}.code is not a known defect code`)
+	check(errors, typeof defect.message === "string", `${at}.message must be a string`)
+}
+
+/** @returns {{ ok: boolean, errors: string[] }} */
+export function validateOutcomeManifest(manifest) {
+	const errors = []
+	if (!isObject(manifest)) return { ok: false, errors: ["manifest must be an object (schemaVersion missing)"] }
+	check(errors, manifest.schemaVersion === SCHEMA_VERSION, `schemaVersion must be ${SCHEMA_VERSION}`)
+	check(errors, typeof manifest.sessionDir === "string" && manifest.sessionDir.length > 0, "sessionDir must be a non-empty string")
+	check(errors, typeof manifest.startedAt === "string" && ISO_DATE.test(manifest.startedAt), "startedAt must be an ISO timestamp")
+	check(errors, manifest.finishedAt === null || (typeof manifest.finishedAt === "string" && ISO_DATE.test(manifest.finishedAt)), "finishedAt must be null or an ISO timestamp")
+	check(errors, manifest.elapsedMinutes === null || (Number.isFinite(manifest.elapsedMinutes) && manifest.elapsedMinutes >= 0), "elapsedMinutes must be null or a non-negative number")
+	check(errors, manifest.lane === null || LANES.includes(manifest.lane), `lane must be null or one of ${LANES.join(", ")}`)
+	check(errors, manifest.interview === null || isObject(manifest.interview), "interview must be null or an object")
+	if (Array.isArray(manifest.deliverables)) manifest.deliverables.forEach((row, index) => validateDeliverable(row, index, errors))
+	else errors.push("deliverables must be an array")
+	if (Array.isArray(manifest.renders)) {
+		manifest.renders.forEach((render, index) => {
+			check(errors, isObject(render) && typeof render.path === "string" && Number.isInteger(render.page) && render.page >= 1, `renders[${index}] must be { path: string, page: integer >= 1 }`)
+		})
+	} else errors.push("renders must be an array")
+	if (isObject(manifest.gates)) {
+		for (const gate of GATE_NAMES) check(errors, GATE_STATUSES.includes(manifest.gates[gate]), `gates.${gate} must be one of ${GATE_STATUSES.join(", ")}`)
+	} else errors.push("gates must be an object")
+	if (Array.isArray(manifest.residualDefects)) manifest.residualDefects.forEach((defect, index) => validateDefect(defect, `residualDefects[${index}]`, errors))
+	else errors.push("residualDefects must be an array")
+	check(errors, manifest.repair === null || isObject(manifest.repair), "repair must be null or an object")
+	check(errors, manifest.sources === null || isObject(manifest.sources), "sources must be null or an object")
+	return { ok: errors.length === 0, errors }
+}
+
+function isMeasure(value) {
+	return Array.isArray(value) && value.length === 3 && value.every((n) => Number.isInteger(n) && n >= 0)
+}
+
+/** @returns {{ ok: boolean, errors: string[] }} */
+export function validateRepairState(state) {
+	const errors = []
+	if (!isObject(state)) return { ok: false, errors: ["repair state must be an object (schemaVersion missing)"] }
+	check(errors, state.schemaVersion === SCHEMA_VERSION, `schemaVersion must be ${SCHEMA_VERSION}`)
+	check(errors, typeof state.startedAt === "string" && ISO_DATE.test(state.startedAt), "startedAt must be an ISO timestamp")
+	if (isObject(state.budget)) {
+		for (const key of ["maxAttempts", "plateauLimit", "wallClockMs"]) {
+			check(errors, Number.isInteger(state.budget[key]) && state.budget[key] > 0, `budget.${key} must be a positive integer`)
+		}
+	} else errors.push("budget must be an object")
+	if (Array.isArray(state.attempts)) {
+		state.attempts.forEach((attempt, index) => {
+			const at = `attempts[${index}]`
+			if (!isObject(attempt)) return errors.push(`${at} must be an object`)
+			check(errors, typeof attempt.at === "string" && ISO_DATE.test(attempt.at), `${at}.at must be an ISO timestamp`)
+			check(errors, isMeasure(attempt.measure), `${at}.measure must be [blocker, major, minor] counts`)
+			check(errors, typeof attempt.signature === "string", `${at}.signature must be a string`)
+		})
+	} else errors.push("attempts must be an array")
+	check(errors, Number.isInteger(state.consecutiveNonProgress) && state.consecutiveNonProgress >= 0, "consecutiveNonProgress must be a non-negative integer")
+	check(errors, Array.isArray(state.seenSignatures) && state.seenSignatures.every((s) => typeof s === "string"), "seenSignatures must be an array of strings")
+	return { ok: errors.length === 0, errors }
+}

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

@@ -0,0 +1,204 @@
+// css-lite.mjs - a tolerant, dependency-free CSS scanner for report gates and spec extraction.
+//
+// Never throws on malformed input: an unbalanced stylesheet yields the rules closed so far.
+// Plain Node ESM, no imports.
+
+const GROUP_AT = /^@(?:-[a-z]+-)?(?:media|supports|container|layer|document|scope|starting-style|keyframes)\b/i
+const HEX = /(?<![\w&])#([0-9a-f]{8}|[0-9a-f]{6}|[0-9a-f]{4}|[0-9a-f]{3})(?![\w-])/gi
+const DARK_MEDIA = /prefers-color-scheme\s*:\s*dark/i
+const DARK_THEME = /\[data-theme\s*=\s*["']?dark/i
+const TOKEN_SCOPE = /(?:^|[\s,>])(?::root|html)\b|^\[data-theme/i
+
+function stripComments(css) {
+	return css.replace(/\/\*[\s\S]*?(?:\*\/|$)/g, "")
+}
+
+/** Split on `separator` outside quotes and parentheses. */
+function splitTopLevel(text, separator) {
+	const parts = []
+	let depth = 0
+	let quote = null
+	let current = ""
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i]
+		if (quote) {
+			if (ch === "\\") current += ch + (text[++i] ?? "")
+			else {
+				if (ch === quote) quote = null
+				current += ch
+			}
+			continue
+		}
+		if (ch === '"' || ch === "'") quote = ch
+		else if (ch === "(") depth++
+		else if (ch === ")") depth = Math.max(0, depth - 1)
+		else if (ch === separator && depth === 0) {
+			parts.push(current)
+			current = ""
+			continue
+		}
+		current += ch
+	}
+	parts.push(current)
+	return parts
+}
+
+function parseDeclarations(text) {
+	const declarations = []
+	for (const piece of splitTopLevel(text, ";")) {
+		const colon = piece.indexOf(":")
+		if (colon <= 0) continue
+		const rawProp = piece.slice(0, colon).trim()
+		const value = piece.slice(colon + 1).trim()
+		if (!rawProp || /[\s{}]/.test(rawProp)) continue
+		declarations.push({ prop: rawProp.startsWith("--") ? rawProp : rawProp.toLowerCase(), value })
+	}
+	return declarations
+}
+
+/**
+ * @returns {{ selector: string, declarations: { prop: string, value: string }[], atRule?: string }[]}
+ * atRule is the chain of enclosing grouping at-rule preludes joined by a space.
+ */
+export function scanRules(css) {
+	if (typeof css !== "string") return []
+	const src = stripComments(css)
+	const slots = []
+	const stack = []
+	let buffer = ""
+	for (let i = 0; i < src.length; i++) {
+		const ch = src[i]
+		if (ch === '"' || ch === "'") {
+			let end = i + 1
+			while (end < src.length && src[end] !== ch) end += src[end] === "\\" ? 2 : 1
+			buffer += src.slice(i, end + 1)
+			i = end
+		} else if (ch === "{") {
+			const pieces = splitTopLevel(buffer, ";")
+			const prelude = pieces.pop().trim()
+			const frame = stack.at(-1)
+			if (frame && pieces.length) frame.body += `${pieces.join(";")};`
+			const group = GROUP_AT.test(prelude)
+			const slot = group ? -1 : slots.push(null) - 1
+			stack.push({ prelude, group, slot, body: "" })
+			buffer = ""
+		} else if (ch === "}") {
+			const frame = stack.pop()
+			if (frame && !frame.group) {
+				const atChain = stack.filter((entry) => entry.group).map((entry) => entry.prelude)
+				const rule = { selector: frame.prelude, declarations: parseDeclarations(frame.body + buffer) }
+				if (atChain.length) rule.atRule = atChain.join(" ")
+				slots[frame.slot] = rule
+			}
+			buffer = ""
+		} else if (ch === ";" && stack.length === 0) {
+			buffer = ""
+		} else {
+			buffer += ch
+		}
+	}
+	return slots.filter(Boolean)
+}
+
+function isDarkRule(rule) {
+	if (rule.atRule && DARK_MEDIA.test(rule.atRule)) return true
+	return DARK_THEME.test(rule.selector.replace(/:not\([^)]*\)/gi, ""))
+}
+
+/**
+ * Global design tokens from `:root`, `html`, and `[data-theme]` rules. Dark = inside
+ * `@media (prefers-color-scheme: dark)` or on a `[data-theme="dark"]` selector. Last value wins.
+ * @returns {{ light: Map<string, string>, dark: Map<string, string> }}
+ */
+export function customProperties(css) {
+	const light = new Map()
+	const dark = new Map()
+	for (const rule of scanRules(css)) {
+		if (!rule.selector.split(",").some((part) => TOKEN_SCOPE.test(part.trim()))) continue
+		const target = isDarkRule(rule) ? dark : light
+		for (const { prop, value } of rule.declarations) if (prop.startsWith("--")) target.set(prop, value)
+	}
+	return { light, dark }
+}
+
+function splitFamilies(value) {
+	return splitTopLevel(value, ",")
+		.map((family) => family.trim().replace(/^(["'])(.*)\1$/, "$2").trim())
+		.filter(Boolean)
+}
+
+/** Font stack after the size token of a `font` shorthand, or null when the shorthand has none. */
+function shorthandFamilies(value) {
+	const match = /(?:^|\s)[\d.]+(?:px|em|rem|pt|%|vw|vh|ch|ex)(?:\s*\/\s*\S+)?\s+(.+)$/i.exec(value)
+	return match ? match[1] : null
+}
+
+/** @returns {{ selector: string, families: string[] }[]} var() references resolve against light tokens. */
+export function fontFamilies(css) {
+	const props = customProperties(css).light
+	const result = []
+	for (const rule of scanRules(css)) {
+		for (const { prop, value } of rule.declarations) {
+			const resolved = resolveVar(value, props)
+			const stack = prop === "font-family" ? resolved : prop === "font" ? shorthandFamilies(resolved) : null
+			if (stack === null) continue
+			const families = splitFamilies(stack)
+			if (families.length) result.push({ selector: rule.selector, families })
+		}
+	}
+	return result
+}
+
+/** #abc / #abcd / #aabbcc / #aabbccdd -> #aabbcc (lowercase, alpha dropped); anything else -> null. */
+export function normalizeHex(hex) {
+	const match = /^#([0-9a-f]{3,8})$/i.exec(String(hex).trim())
+	if (!match || ![3, 4, 6, 8].includes(match[1].length)) return null
+	const digits = match[1].toLowerCase()
+	const six = digits.length <= 4 ? [...digits.slice(0, 3)].map((d) => d + d).join("") : digits.slice(0, 6)
+	return `#${six}`
+}
+
+/** Every hex color in `text`, normalized, in order of appearance, repeats kept. */
+export function hexColors(text) {
+	if (typeof text !== "string") return []
+	return [...text.matchAll(HEX)].map((match) => normalizeHex(match[0]))
+}
+
+/** Unique px widths named in @media preludes (min-/max-width and range syntax), ascending. */
+export function mediaBreakpoints(css) {
+	if (typeof css !== "string") return []
+	const widths = new Set()
+	for (const media of stripComments(css).matchAll(/@media\b([^{;]*)/gi)) {
+		for (const match of media[1].matchAll(/\b(?:min-|max-)?width\s*(?::|[<>]=?|=)\s*(\d+(?:\.\d+)?)px/gi)) {
+			widths.add(Number(match[1]))
+		}
+	}
+	return [...widths].sort((a, b) => a - b)
+}
+
+function lookup(props, name) {
+	if (props instanceof Map) return props.get(name)
+	return props && Object.hasOwn(props, name) ? props[name] : undefined
+}
+
+/** Substitute var(--name[, fallback]) from `props` (Map or object); unresolvable references keep their text. */
+export function resolveVar(value, props, depth = 0) {
+	if (typeof value !== "string" || depth > 10) return value
+	let out = ""
+	let cursor = 0
+	for (;;) {
+		const start = value.indexOf("var(", cursor)
+		if (start === -1) return out + value.slice(cursor)
+		let end = start + 4
+		for (let open = 1; end < value.length && open > 0; end++) {
+			if (value[end] === "(") open++
+			else if (value[end] === ")") open--
+		}
+		const [name, ...rest] = splitTopLevel(value.slice(start + 4, end - 1), ",")
+		const fallback = rest.length ? rest.join(",").trim() : undefined
+		const replacement = lookup(props, name.trim()) ?? fallback
+		const original = value.slice(start, end)
+		out += value.slice(cursor, start) + (replacement === undefined ? original : resolveVar(replacement, props, depth + 1))
+		cursor = end
+	}
+}

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

@@ -0,0 +1,161 @@
+// design-spec.mjs - read the palette and lineage mode out of design-spec.md, and render a
+// design-spec.md draft from a format extract. Nothing is guessed: every value the extract
+// does not carry is written `TODO: ask` and listed under Open questions.
+// Plain Node ESM, node: builtins and siblings only.
+
+import { DESIGN_SPEC_SECTIONS, LINEAGE_MODES } from "./contracts.mjs"
+import { hexColors } from "./css-lite.mjs"
+
+const TODO = "TODO: ask"
+// English and Korean section names (the requester writes specs in either language).
+const PALETTE_HEADING = /^(palette|tokens|colou?rs?|\uD1A0\uD070|\uD314\uB808\uD2B8|\uC0C9\uC0C1|\uCEEC\uB7EC)/i
+const FENCE = /^\s{0,3}(`{3,}|~{3,})/
+const HEADING = /^(#{1,6})\s+(.*?)\s*#*\s*$/
+const TOKEN_DECLARATION = /--[\w-]+\s*:\s*([^;]*)/g
+const FIGURE_STANDARD =
+	"Each figure sits in a fixed-size container with a caption; the image scales to fit with its aspect ratio preserved (object-fit: contain), never stretched, cropped, or spilling out. Every chart carries a title, axis labels, units, and value labels."
+
+/**
+ * Walk markdown lines with fence awareness.
+ * visit(line, { fenced, heading: { level, text } | null })
+ */
+function walkLines(markdown, visit) {
+	let fence = null
+	for (const line of String(markdown ?? "").split(/\r?\n/)) {
+		const fenceMatch = FENCE.exec(line)
+		if (fence) {
+			const closes = fenceMatch && fenceMatch[1][0] === fence[0] && fenceMatch[1].length >= fence.length && line.trim() === fenceMatch[1]
+			if (closes) fence = null
+			else visit(line, { fenced: true, heading: null })
+			continue
+		}
+		if (fenceMatch) {
+			fence = fenceMatch[1]
+			continue
+		}
+		const heading = HEADING.exec(line)
+		visit(line, { fenced: false, heading: heading ? { level: heading[1].length, text: heading[2].replace(/^[\d.\s]+/, "") } : null })
+	}
+}
+
+/**
+ * Palette = hex values of every `--x: #hex` inside any fenced code block, plus every hex
+ * anywhere under a heading named Palette / Tokens / Colors / Colours or their Korean equivalents (subheadings included).
+ * @returns {Set<string>} normalized #rrggbb values
+ */
+export function parsePalette(specMarkdown) {
+	const palette = new Set()
+	let paletteLevel = 0
+	walkLines(specMarkdown, (line, { fenced, heading }) => {
+		if (heading) {
+			if (paletteLevel && heading.level > paletteLevel) return
+			paletteLevel = PALETTE_HEADING.test(heading.text) ? heading.level : 0
+			return
+		}
+		if (fenced) for (const match of line.matchAll(TOKEN_DECLARATION)) for (const hex of hexColors(match[1])) palette.add(hex)
+		if (paletteLevel) for (const hex of hexColors(line)) palette.add(hex)
+	})
+	return palette
+}
+
+/** `Lineage: inline|section` under the Citations heading; absent or unrecognized -> "inline". */
+export function parseLineageMode(specMarkdown) {
+	let citationsLevel = 0
+	let mode = null
+	walkLines(specMarkdown, (line, { fenced, heading }) => {
+		if (mode || fenced) return
+		if (heading) {
+			if (citationsLevel && heading.level > citationsLevel) return
+			citationsLevel = /^citations\b/i.test(heading.text) ? heading.level : 0
+			return
+		}
+		const match = citationsLevel ? /^\s*(?:[-*]\s+)?lineage\s*:\s*(\S+)/i.exec(line) : null
+		if (match && LINEAGE_MODES.includes(match[1].toLowerCase())) mode = match[1].toLowerCase()
+	})
+	return mode ?? "inline"
+}
+
+function entriesOf(value) {
+	if (value instanceof Map) return [...value]
+	return value !== null && typeof value === "object" ? Object.entries(value) : []
+}
+
+function isKnown(value) {
+	if (value === undefined || value === null || value === "" || value === "unknown") return false
+	if (Array.isArray(value)) return value.length > 0
+	return true
+}
+
+function tokenFence(entries, dark) {
+	const lines = entries.map(([name, value]) => `${dark ? "    " : "  "}${name}: ${value};`)
+	const body = dark ? ["@media (prefers-color-scheme: dark) {", "  :root {", ...lines, "  }", "}"] : [":root {", ...lines, "}"]
+	return ["```css", ...body, "```"]
+}
+
+/**
+ * Render a design-spec.md draft. `extract` follows the format-extract shape
+ * ({ origin, bytes, date?, tokens: { light, dark }, fonts, colors, breakpoints, headingNumbering,
+ * citationStyle, lineageMode, figureContainers, skeleton, measure, notes }); every field is optional.
+ * @returns {string}
+ */
+export function renderDesignSpec(extract = {}) {
+	const source = extract ?? {}
+	const open = []
+	const field = (label, value, format = String) => {
+		if (isKnown(value)) return format(value)
+		open.push(label)
+		return TODO
+	}
+	const fonts = source.fonts ?? {}
+	const measure = source.measure ?? {}
+	const light = entriesOf(source.tokens?.light)
+	const dark = entriesOf(source.tokens?.dark)
+	const colors = Array.isArray(source.colors) ? source.colors : []
+	const skeleton = Array.isArray(source.skeleton) ? source.skeleton : []
+	const notes = Array.isArray(source.notes) ? source.notes : []
+
+	const sections = {
+		"Extracted from": [
+			`- Source: ${field("Source path or URL", source.origin)}`,
+			`- Bytes: ${field("Source byte count", source.bytes)}`,
+			`- Date: ${source.date ?? new Date().toISOString().slice(0, 10)}`,
+			...notes.map((note) => `- Note: ${note}`),
+		],
+		Tokens: [
+			...(light.length ? tokenFence(light, false) : [`- Light tokens: ${field("Light tokens", null)}`]),
+			...(dark.length ? tokenFence(dark, true) : [`- Dark tokens: ${field("Dark tokens", null)}`]),
+			...(colors.length
+				? ["- Top colors:", ...colors.map((c) => `  - ${c.hex}${c.count ? ` (${c.count} uses${c.roles?.length ? `; ${c.roles.join(", ")}` : ""})` : ""}`)]
+				: [`- Top colors: ${field("Top colors", null)}`]),
+		],
+		Typography: [
+			`- Body font: ${field("Body font", fonts.body)}`,
+			`- Heading font: ${field("Heading font", fonts.heading)}`,
+			`- Mono font: ${field("Mono font", fonts.mono)}`,
+			`- Body size: ${field("Body size", measure.fontSize)}`,
+			`- Line height: ${field("Line height", measure.lineHeight)}`,
+		],
+		Layout: [
+			`- Breakpoints: ${field("Breakpoints", source.breakpoints, (list) => list.map((px) => `${px}px`).join(", "))}`,
+			`- Measure (max width): ${field("Measure", measure.maxWidth)}`,
+		],
+		Structure: [
+			`- Heading numbering: ${field("Heading numbering", source.headingNumbering)}`,
+			skeleton.length ? "- Skeleton:" : `- Skeleton: ${field("Section skeleton", null)}`,
+			...skeleton.map((entry) => `${"  ".repeat(Math.max(1, entry.level))}- ${entry.text}`),
+		],
+		Figures: [
+			`- Containers: ${field("Figure containers", source.figureContainers, (list) => list.join(", "))}`,
+			`- Standard: ${FIGURE_STANDARD}`,
+		],
+		Citations: [
+			`- Style: ${field("Citation style", source.citationStyle)}`,
+			`- Lineage: ${field("Lineage mode", LINEAGE_MODES.includes(source.lineageMode) ? source.lineageMode : null)}`,
+		],
+	}
+	sections["Open questions"] = open.length ? open.map((label) => `- ${label}: ${TODO}`) : ["- None"]
+
+	const out = ["# Design spec", ""]
+	for (const heading of DESIGN_SPEC_SECTIONS) out.push(`## ${heading}`, ...(sections[heading] ?? [`- ${TODO}`]), "")
+	return out.join("\n")
+}

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

@@ -0,0 +1,39 @@
+// entities.mjs - HTML character reference decoding for html-lite.mjs.
+//
+// Supports a fixed set of named entities plus decimal and hex numeric references. Unknown or
+// malformed references stay verbatim. Single indexOf scan; plain Node ESM, no dependencies.
+
+const NAMED_ENTITIES = {
+	amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: "\u00a0", mdash: "\u2014", ndash: "\u2013",
+	hellip: "\u2026", copy: "\u00a9", reg: "\u00ae", times: "\u00d7", middot: "\u00b7",
+}
+
+function decodeOne(body) {
+	if (Object.hasOwn(NAMED_ENTITIES, body)) return NAMED_ENTITIES[body]
+	if (body[0] !== "#") return null
+	const hex = body[1] === "x" || body[1] === "X"
+	const digits = body.slice(hex ? 2 : 1)
+	if (!(hex ? /^[0-9a-fA-F]{1,6}$/ : /^[0-9]{1,7}$/).test(digits)) return null
+	const cp = Number.parseInt(digits, hex ? 16 : 10)
+	return cp > 0 && cp <= 0x10ffff && (cp < 0xd800 || cp > 0xdfff) ? String.fromCodePoint(cp) : "\ufffd"
+}
+
+/** Decode the supported named entities plus decimal/hex numeric references; unknown ones stay verbatim. */
+export function decodeEntities(text) {
+	const source = String(text)
+	let out = ""
+	let last = 0
+	let at = source.indexOf("&")
+	while (at !== -1) {
+		const semi = source.indexOf(";", at + 1)
+		const decoded = semi !== -1 && semi - at <= 12 ? decodeOne(source.slice(at + 1, semi)) : null
+		if (decoded !== null) {
+			out += source.slice(last, at) + decoded
+			last = semi + 1
+			at = source.indexOf("&", last)
+		} else {
+			at = source.indexOf("&", at + 1)
+		}
+	}
+	return out + source.slice(last)
+}