lazycodex-ai 5.1.45 → 5.1.46

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

@@ -0,0 +1,229 @@
+// fidelity-values.mjs - value, quote, and chart checks of the deterministic fidelity gate.
+//
+// Each data-fact element must match its ledger row, and each Q element the script's
+// reconstruction of its selection (report text never gets a fuzzy pass). Cited rows, table rows,
+// snapshots, and chart CSVs are rechecked; the numeral and quotation trace is fidelity-trace.mjs,
+// and the claim-kind checks (data-claim-kind, unsupported_verification) are fidelity-claims.mjs.
+// No model, no network.
+
+import { existsSync, readFileSync } from "node:fs"
+import { join, resolve, sep } from "node:path"
+
+import { sha256Of } from "./cli-support.mjs"
+import { sameValue, unitKey } from "./fidelity-binding.mjs"
+import { claimChecks } from "./fidelity-claims.mjs"
+import { STRUCTURAL, clip, traceChecks } from "./fidelity-trace.mjs"
+import { parseHtml, proseText } from "./html-lite.mjs"
+import { parseNumeral } from "./numerals.mjs"
+import { div, fromDecimal, sub } from "./rational.mjs"
+import { normalizeText } from "./text-normalize.mjs"
+
+const DECIMAL = /^-?\d+(?:\.\d+)?$/
+
+const bare = (text) => normalizeText(String(text ?? "").replace(/\s*\[(?:S|Source\s*)\d+\]\s*$/i, "")).replace(/\u2026/g, "...").replace(/\s*\.\.\.\s*/g, "...").replace(/^["']+|["']+$/g, "").trim()
+
+/** The text fill renders for a quote selection: full, lead=<n>, or from=<a>;to=<b> (placeholder form accepted). */
+export function selectQuote(quote, selector) {
+	const text = String(quote ?? "").trim()
+	if (selector === "full") return text
+	const lead = /^lead=(\d+)$/.exec(selector)
+	const words = text.split(/\s+/)
+	if (lead) return words.length <= Number(lead[1]) ? text : `${words.slice(0, Number(lead[1])).join(" ")}...`
+	const range = /^from=(.+);to=(.+)$/.exec(selector) ?? /^from="(.+)":to="(.+)"$/.exec(selector)
+	if (!range) return null
+	const once = (anchor) => text.indexOf(anchor) !== -1 && text.indexOf(anchor) === text.lastIndexOf(anchor)
+	if (!once(range[1]) || !once(range[2])) return null
+	const start = text.indexOf(range[1])
+	const end = text.indexOf(range[2]) + range[2].length
+	if (end <= start) return null
+	return `${start > 0 ? "..." : ""}${text.slice(start, end)}${end < text.length ? "..." : ""}`
+}
+
+function quoteProblem(row, shown, selector) {
+	const want = selectQuote(row.quote, selector)
+	if (want === null) return ["quote_not_verbatim", `selection "${selector}" does not resolve in ${row.fact_id}'s quote`]
+	return bare(shown) === bare(want) ? null : ["quote_not_verbatim", `"${clip(shown)}" is not the ${selector} selection of ${row.fact_id}: "${clip(want)}"`]
+}
+
+function factProblem(row, shown, attrs = {}) {
+	if (attrs["data-unit"] !== undefined && unitKey(attrs["data-unit"]) !== unitKey(row.unit)) return ["unit_mismatch", `data-unit "${attrs["data-unit"]}" but ${row.fact_id} is in "${row.unit}"`]
+	if (attrs.value !== undefined && !sameValue(attrs.value, row.value)) return ["value_mismatch", `value="${attrs.value}" but ${row.fact_id} is ${row.value}`]
+	const text = normalizeText(shown)
+	const forms = [row.raw, row.render, row.value, row.unit && `${row.value} ${row.unit}`].filter(Boolean).map(normalizeText)
+	if (forms.some((form) => text === form || (text.endsWith(` ${form}`) && !/\d/.test(text.slice(0, -form.length))))) return null
+	const parsed = parseNumeral(text)
+	if (!parsed) return unitKey(text) === unitKey(row.unit) ? null : ["value_mismatch", `"${clip(shown)}" shows no value of ${row.fact_id} (${row.value})`]
+	if (!sameValue(parsed.value, row.value)) return ["value_mismatch", `"${clip(shown)}" reads ${parsed.value}, but ${row.fact_id} is ${row.value}`]
+	if (parsed.unitRaw && unitKey(parsed.unitRaw) !== unitKey(row.unit)) return ["unit_mismatch", `"${clip(shown)}" is in ${parsed.unitRaw}, but ${row.fact_id} is in ${row.unit}`]
+	return null
+}
+
+/** Whether a candidate fill site reads as what fill wrote there or as the entry's row ("1,237 million" is neither 1,237 nor F2). */
+const fillSiteFits = (rows) => (entry, tail) => {
+	const [row, site, own] = [rows.get(entry.fact_id), parseNumeral(tail, 0), parseNumeral(entry.rendered, 0)]
+	if (!row || row.kind === "quote" || !site || !own) return true
+	if (sameValue(site.value, own.value) && unitKey(site.unitRaw ?? "") === unitKey(own.unitRaw ?? "")) return true
+	return factProblem(row, tail.slice(0, Math.max(entry.rendered.length, site.span[1]))) === null
+}
+
+const withoutFooter = (node) => proseText({ children: node.children.filter((child) => child.tag !== "footer") })
+
+/** One row per active value row, as `fact export --csv` writes it. */
+export function exportRows(ledger) {
+	return (ledger?.rows ?? []).filter((row) => row.status === "active" && row.kind !== "quote" && row.value !== null).map((row) => ({ fact_id: row.fact_id, label: row.label, plot_value: row.value, unit: row.unit ?? "" }))
+}
+
+function readCsv(path) {
+	if (!existsSync(path)) return null
+	const lines = readFileSync(path, "utf8").split(/\r?\n/).filter((line) => line.trim() !== "")
+	const cells = (line) => line.split(",").map((cell) => cell.trim().replace(/^"(.*)"$/, "$1"))
+	const head = cells(lines[0] ?? "")
+	const [id, value, unit] = ["fact_id", "plot_value", "unit"].map((name) => head.indexOf(name))
+	if (id < 0 || value < 0 || unit < 0 || lines.length < 2) return null
+	return lines.slice(1).map((line) => cells(line)).map((c) => ({ fact_id: c[id], plot_value: c[value], unit: c[unit] ?? "" }))
+}
+
+const walk = (node) => node.children.filter((child) => child.tag !== "#text").flatMap((child) => [child, ...walk(child)])
+
+/** SVG text nodes of a chart: data labels, or ticks with their declared grid. */
+function svgLabels(raw) {
+	return walk(parseHtml(raw)).filter((node) => node.tag === "text").map((node) => {
+		let tick = null
+		for (let cur = node.parent; cur && !tick; cur = cur.parent) if (cur.tag === "g" && /(?:^|\s)ticks(?:\s|$)/.test(cur.attrs.class ?? "")) tick = cur.attrs
+		return { text: proseText(node), tick }
+	})
+}
+
+function onGrid(value, tick) {
+	const [step, min, max] = [tick["data-tick-step"], tick["data-tick-min"], tick["data-tick-max"]]
+	if (![value, step, min, max].every((v) => DECIMAL.test(String(v ?? ""))) || /^-?0+(?:\.0+)?$/.test(step)) return false
+	const offset = sub(fromDecimal(value), fromDecimal(min))
+	return offset.num >= 0n && sub(fromDecimal(max), fromDecimal(value)).num >= 0n && div(offset, fromDecimal(step)).den === 1n
+}
+
+function numerals(text) {
+	const out = []
+	for (let at = 0, n = parseNumeral(text, 0); n; at = n.span[1], n = parseNumeral(text, at)) out.push(n.value)
+	return out
+}
+
+function chartFigures(ctx) {
+	const charts = new Map()
+	for (const fig of ctx.all.filter((node) => node.tag === "figure")) {
+		const inner = ctx.util.descendants(fig)
+		const labels = inner.filter((node) => node.tag === "svg").flatMap((svg) => svgLabels(svg.raw ?? ""))
+		const marked = fig.attrs["data-chart-source"] !== undefined || ctx.util.classTokens(fig).includes("chart")
+		if (marked || inner.some((node) => node.tag === "img" && ctx.util.classTokens(node).includes("chart")) || labels.some((label) => /\d/.test(label.text))) charts.set(fig, labels)
+	}
+	return charts
+}
+
+function chartProblem(ctx, fig, labels, ledger) {
+	const source = fig.attrs["data-chart-source"]
+	if (!source) return "chart figure has no data-chart-source"
+	const csv = readCsv(resolve(ctx.baseDir ?? ".", source))
+	if (!csv) return `chart data ${source} is missing or lacks fact_id, plot_value, unit columns`
+	const exported = new Map(exportRows(ledger).map((row) => [row.fact_id, row]))
+	const drift = csv.find((row) => exported.get(row.fact_id)?.plot_value !== row.plot_value || exported.get(row.fact_id)?.unit !== row.unit)
+	if (drift) return `chart data row ${drift.fact_id} differs from the ledger export`
+	const plotted = (value) => csv.some((row) => sameValue(row.plot_value, value))
+	for (const label of labels) {
+		const bad = numerals(label.text).find((value) => (label.tick ? !onGrid(value, label.tick) : !plotted(value)))
+		if (bad !== undefined) return `${label.tick ? "tick" : "label"} "${label.text}" is not ${label.tick ? "on the declared tick grid" : `a plot_value of ${source}`}`
+	}
+	const caption = ctx.util.descendants(fig).find((node) => node.tag === "figcaption")
+	const stray = numerals(caption ? STRUCTURAL.reduce((text, re) => text.replace(re, " "), proseText(caption)) : "").find((value) => !plotted(value))
+	return stray === undefined ? null : `caption numeral ${stray} is not a plot_value of ${source}`
+}
+
+/**
+ * @param {object} ctx buildContext(...) from gates-static.mjs
+ * @param {{ rows: object[] }} ledger
+ * @param {{ fact_id: string, rendered: string, selector?: string }[] | null} fillMap Markdown fill map, or null
+ * @param {string | null} sourcesDir directory of <S-id>/{text.txt, meta.json} snapshots
+ * @param {{ recompute?: (ledger: object, row: object) => { ok: boolean }, asOf?: string | null }} options
+ */
+export function valueChecks(ctx, ledger, fillMap, sourcesDir, options = {}) {
+	const out = []
+	const flag = (code, node, message) => out.push(ctx.defect(code, node, message))
+	const rows = new Map((ledger?.rows ?? []).map((row) => [row.fact_id, row]))
+	const cited = new Map()
+	const check = (id, node, problemOf) => {
+		const row = rows.get(id)
+		if (!row) return flag("unresolved_placeholder", node, `${id} names no ledger row`)
+		if (!cited.has(id)) cited.set(id, node)
+		const problem = problemOf(row)
+		if (problem) flag(problem[0], node, problem[1])
+	}
+	for (const node of ctx.all.filter((cur) => cur.attrs["data-fact"] !== undefined)) {
+		const selector = node.attrs["data-quote-sel"] ?? "full"
+		check(node.attrs["data-fact"], node, (row) => (row.kind === "quote" ? quoteProblem(row, withoutFooter(node), selector) : factProblem(row, proseText(node), node.attrs)))
+	}
+	const docText = bare(proseText(ctx.body))
+	for (const entry of fillMap ?? []) {
+		check(entry.fact_id, ctx.body, (row) => {
+			const problem = row.kind === "quote" ? quoteProblem(row, entry.rendered, entry.selector ?? "full") : factProblem(row, entry.rendered)
+			if (problem || docText.includes(bare(entry.rendered))) return problem
+			return [row.kind === "quote" ? "quote_not_verbatim" : "value_mismatch", `filled text "${clip(entry.rendered)}" of ${row.fact_id} is no longer in the report`]
+		})
+	}
+	rowChecks(ctx, ledger, rows, cited, options, flag)
+	for (const tr of ctx.all.filter((node) => node.tag === "tr" && node.attrs["data-row-kind"] !== "comparison")) {
+		const groups = new Set(ctx.util.descendants(tr).map((node) => rows.get(node.attrs["data-fact"])?.observation_id).filter(Boolean))
+		if (groups.size > 1) flag("join_integrity_fail", tr, `one table row joins observations ${[...groups].join(", ")}`)
+	}
+	const meta = sourceChecks(ctx, rows, cited, sourcesDir, flag)
+	claimChecks(ctx, rows, (row) => provenance(sourcesDir, meta, row), flag)
+	const charts = chartFigures(ctx)
+	for (const { node, scope } of ctx.elements) {
+		const kind = ctx.kindOf(scope)
+		if ((node.tag === "q" || node.tag === "blockquote") && node.attrs["data-fact"] === undefined && kind !== "sources" && kind !== "toc") flag("quote_unbound", node, `<${node.tag}> with no Q row: "${clip(proseText(node))}"`)
+	}
+	traceChecks(ctx, charts, fillMap, flag, fillSiteFits(rows))
+	for (const [fig, labels] of charts) {
+		const problem = chartProblem(ctx, fig, labels, ledger)
+		if (problem) flag("chart_value_untraceable", fig, problem)
+	}
+	return out
+}
+
+function rowChecks(ctx, ledger, rows, cited, options, flag) {
+	// An as-of of "latest ..." or "... per snapshot" names no fixed revision, so quote_stale_version is skipped.
+	const asOf = options.asOf && !/^latest\b|per snapshot/i.test(options.asOf) ? options.asOf : null
+	for (const [id, node] of cited) {
+		const row = rows.get(id)
+		if (row.fuzzy === true) flag("quote_fuzzy_match", node, `${id} was registered from a similarity match on an OCR-noisy snapshot`)
+		const revision = typeof row.revision === "string" ? row.revision : (row.revision?.id ?? row.revision?.tag ?? null)
+		if (asOf && revision && !asOf.includes(revision)) flag("quote_stale_version", node, `${id} is from revision ${revision}; the brief targets "${asOf}"`)
+		if ((row.kind === "derived" || row.kind === "converted") && options.recompute?.(ledger, row)?.ok === false) flag("value_mismatch", node, `${id} does not recompute from its operands`)
+		const window = row.snapshot_window
+		if (window && typeof window === "object" && window.start && window.end) {
+			const [start, end] = [Date.parse(window.start), Date.parse(window.end)]
+			const outside = (row.operands ?? []).find((op) => !(Date.parse(rows.get(op)?.observed_at) >= start && Date.parse(rows.get(op)?.observed_at) < end))
+			if (outside) flag("snapshot_mismatch", node, `operand ${outside} of ${id} was observed outside ${window.start} to ${window.end}`)
+		}
+	}
+}
+
+/** meta.json kind of the snapshot holding the row's own locator artifact; undefined when the artifact is absent or escapes sources/<source_id>/. */
+function provenance(sourcesDir, meta, row) {
+	const artifact = row.locator?.artifact
+	if (!sourcesDir || typeof row.source_id !== "string" || typeof artifact !== "string") return undefined
+	const dir = resolve(sourcesDir, row.source_id)
+	const path = resolve(dir, artifact)
+	return path.startsWith(`${dir}${sep}`) && existsSync(path) ? meta.get(row.source_id)?.kind : undefined
+}
+
+function sourceChecks(ctx, rows, cited, sourcesDir, flag) {
+	const ids = new Set([...cited.keys()].map((id) => rows.get(id)?.source_id).filter(Boolean))
+	for (const match of proseText(ctx.body).matchAll(/\[S(\d+)\]/g)) ids.add(`S${match[1]}`)
+	const meta = new Map()
+	for (const id of sourcesDir ? ids : []) {
+		const [metaPath, textPath] = [join(sourcesDir, id, "meta.json"), join(sourcesDir, id, "text.txt")]
+		if (!existsSync(metaPath) || !existsSync(textPath)) continue
+		meta.set(id, JSON.parse(readFileSync(metaPath, "utf8")))
+		const actual = sha256Of(readFileSync(textPath))
+		if (meta.get(id).sha256 !== actual) flag("snapshot_hash_mismatch", ctx.body, `${id}/text.txt changed after its snapshot was pinned`)
+	}
+	return meta
+}

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

@@ -0,0 +1,113 @@
+// gates-fidelity.mjs - the deterministic fidelity gate over a filled HTML report.
+//
+// checkFidelity refuses to judge a report whose brief has no locked `## Fidelity` block (one
+// fidelity_interview_incomplete defect). Otherwise it builds the static-gate document context
+// once and runs the value, binding, and lexicon checks over it, returning defects in the shape
+// `check` emits plus integrity, sorted blocker, major, minor, then line, selector, code. It never
+// calls a model or reads the network; the meaning verifier consumes its pairs separately.
+// Plain Node ESM, sibling imports only.
+
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { DEFECT_CODES } from "./contracts.mjs"
+import { bindingChecks, proseSentences } from "./fidelity-binding.mjs"
+import { isLocked, parseFidelityBlock } from "./fidelity-brief.mjs"
+import { lexiconChecks } from "./fidelity-lexicon.mjs"
+import { valueChecks } from "./fidelity-values.mjs"
+import { buildContext } from "./gates-static.mjs"
+import { parseHtml } from "./html-lite.mjs"
+
+/** Every code this gate can raise. */
+export const FIDELITY_GATE_CODES = Object.freeze([
+	"fidelity_interview_incomplete", "unresolved_placeholder", "value_mismatch", "unit_mismatch", "quote_not_verbatim",
+	"quote_unbound", "claim_status_invalid", "snapshot_hash_mismatch", "chart_value_untraceable", "untraceable_number",
+	"unsupported_verification", "conflicting_readings", "hedge_dropped", "direction_flipped", "causality_added",
+	"qualifier_dropped", "unbound_sentence", "snapshot_mismatch", "join_integrity_fail", "quote_stale_version",
+	"quote_fuzzy_match", "name_outside_quote", "scope_widened_warn", "claim_kind_mismatch", "verification_claim_unmarked",
+])
+const RANK = { blocker: 0, major: 1, minor: 2 }
+
+/** The gate and delivery barrier share registry policy; caller severities cannot demote it. */
+export function blocksDelivery(defect) {
+	if (!Object.hasOwn(DEFECT_CODES, defect?.code)) return true
+	const entry = DEFECT_CODES[defect.code]
+	return entry.integrity || entry.severity !== "minor"
+}
+
+export function deliveryBlockReason(defect) {
+	return Object.hasOwn(DEFECT_CODES, defect?.code) ? `fidelity_unresolved: ${defect.code}` : `unknown defect code ${defect?.code}`
+}
+
+function withIntegrity(defect) {
+	const { code, severity, selector, line, message, hint } = defect
+	return { code, severity, integrity: DEFECT_CODES[code].integrity, selector, line, message, hint }
+}
+
+function compareDefects(a, b) {
+	const text = (x, y) => (x < y ? -1 : x > y ? 1 : 0)
+	return RANK[a.severity] - RANK[b.severity] || (a.line ?? 0) - (b.line ?? 0) || text(a.selector ?? "", b.selector ?? "") || text(a.code, b.code)
+}
+
+function readAcronyms(sourcesDir, sourceId, cache) {
+	if (!sourcesDir || !sourceId) return {}
+	if (!cache.has(sourceId)) {
+		const path = join(sourcesDir, sourceId, "acronyms.json")
+		cache.set(sourceId, existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {})
+	}
+	return cache.get(sourceId)
+}
+
+/** One (row quote, report sentence) pair per fact cited in a prose sentence outside sources and toc. */
+export function fidelityPairs(ctx, ledger, sourcesDir) {
+	const rows = new Map((ledger?.rows ?? []).map((row) => [row.fact_id, row]))
+	const cache = new Map()
+	const pairs = []
+	for (const block of proseSentences(ctx)) {
+		if (block.kind === "sources" || block.kind === "toc") continue
+		block.sentences.forEach((sentence, index) => {
+			for (const fact of sentence.facts) {
+				const row = rows.get(fact.id)
+				if (!row?.quote) continue
+				pairs.push({
+					pair_id: `${fact.id}@${block.owner.line}:${index + 1}`,
+					fact_id: fact.id,
+					quote: row.quote,
+					sentence: sentence.text,
+					span: [fact.start - sentence.start, fact.end - sentence.start],
+					qualifier: row.kind === "quote" ? null : row.qualifier,
+					acronyms: readAcronyms(sourcesDir, row.source_id, cache),
+					node: block.owner,
+				})
+			}
+		})
+	}
+	return pairs
+}
+
+function incomplete(parsed) {
+	const reasons = !parsed?.present ? "no ## Fidelity block" : [...(parsed.errors ?? []), ...parsed.missing.map((f) => `missing: ${f}`), ...parsed.pending.map((f) => `pending: ${f}`)].join("; ")
+	const entry = DEFECT_CODES.fidelity_interview_incomplete
+	return { code: "fidelity_interview_incomplete", severity: entry.severity, integrity: entry.integrity, selector: null, line: null, message: `fidelity interview incomplete (${reasons})`, hint: entry.hint }
+}
+
+/**
+ * @param {string} html the filled report
+ * @param {{ ledger: { rows: object[] }, sourcesDir?: string | null, claims?: object | null, fillMap?: object[] | null,
+ *   brief: string | object, baseDir?: string, recompute?: (ledger: object, row: object) => { ok: boolean } }} options
+ *   `brief` is the brief.md text or parseFidelityBlock output; `baseDir` resolves data-chart-source paths.
+ * @returns {{ defects: object[], gatesRun: string[] }}
+ */
+export function checkFidelity(html, { ledger, sourcesDir = null, claims = null, fillMap = null, brief, baseDir, recompute } = {}) {
+	const parsed = brief && typeof brief === "object" ? brief : parseFidelityBlock(String(brief ?? ""))
+	if (!isLocked(parsed)) return { defects: [incomplete(parsed)], gatesRun: ["fidelity_interview_incomplete"] }
+	const ctx = buildContext(parseHtml(html), { baseDir })
+	const defects = [
+		...valueChecks(ctx, ledger, fillMap, sourcesDir, { recompute, asOf: parsed.fields["as of"] }),
+		...bindingChecks(ctx, claims, ledger),
+	]
+	const pairs = fidelityPairs(ctx, ledger, sourcesDir)
+	const byId = new Map(pairs.map((pair) => [pair.pair_id, pair]))
+	for (const finding of lexiconChecks(pairs).findings) defects.push(ctx.defect(finding.code, byId.get(finding.pair_id).node, `${finding.pair_id}: ${finding.message}`))
+	return { defects: defects.map(withIntegrity).sort(compareDefects), gatesRun: [...FIDELITY_GATE_CODES] }
+}

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

@@ -18,14 +18,19 @@ import { PROSE_TAGS, proseText, selectorPath } from "./html-lite.mjs"
 const CITATION_MARKER = /\[S\d+\]|\[Source\s*\d+\]|\[\uCD9C\uCC98[^\]]*\]|\[\^\d+\]/i
 const ANCHOR_HREF = /^#(?:s|src|source|ref|fn)/i
 const ANCHOR_TEXT = /^\[(?:\uCD9C\uCC98|Source\s*\d+|S\d+)\]$/i
-/** Closing ("how this report was made") heading; Korean alternates cover the same register. */
-export const CLOSING_HEADING = /\b(?:method(?:ology)?|how)\b|\uB4B7\uBA74|\uBC29\uBC95|\uC5B4\uB5BB\uAC8C|\uB9CC\uB4E4\uC5B4/i
+/**
+ * Closing ("how this report was made") heading; Korean alternates cover the same register. A
+ * heading that is exactly "Closing" (or the Korean word for it) also counts; a heading that only
+ * starts with it ("Closing the gap") does not.
+ */
+export const CLOSING_HEADING = /\b(?:method(?:ology)?|how)\b|\uB4B7\uBA74|\uBC29\uBC95|\uC5B4\uB5BB\uAC8C|\uB9CC\uB4E4\uC5B4|^\s*(?:closing|\uB9C8\uBB34\uB9AC)\s*$/i
 export const SOURCES_HEADING = /references|sources|bibliography|\uCD9C\uCC98|\uCC38\uACE0\s*(?:\uBB38\uD5CC|\uC790\uB8CC)/i
-const OTHER_KINDS = [
+/** Section kinds after sources and closing, in match order; HTML and Markdown share this table. */
+export const OTHER_KINDS = Object.freeze([
 	["toc", /\b(?:contents|toc)\b|\uBAA9\uCC28/i],
 	["appendix", /appendix|\uBD80\uB85D/i],
 	["glossary", /glossary|\uC6A9\uC5B4/i],
-]
+])
 const TEXT_SKIP = new Set(["code", "pre", "kbd", "samp", "script", "style", "svg", "template", "noscript"])
 const HEADING_TAG = /^h[1-6]$/
 /** The one sanctioned severity override: section-level lineage demotes unsourced_number. */
@@ -75,9 +80,25 @@ function findBody(doc) {
 	return doc
 }
 
-function sectionKind(text, closingTest) {
+/**
+ * Closing-heading test for both editions: CLOSING_HEADING plus the spec's optional pattern.
+ * @param {RegExp|string|null} [pattern]
+ * @returns {(text: string) => boolean}
+ */
+export function closingTest(pattern) {
+	const extra = pattern ? toRegExp(pattern) : null
+	return (text) => CLOSING_HEADING.test(text) || Boolean(extra?.test(text))
+}
+
+/**
+ * Section kind of an h2 heading text: sources, closing, toc, appendix, glossary, or null.
+ * @param {string} text
+ * @param {(text: string) => boolean} isClosing
+ * @returns {string|null}
+ */
+export function sectionKind(text, isClosing) {
 	if (SOURCES_HEADING.test(text)) return "sources"
-	if (closingTest(text)) return "closing"
+	if (isClosing(text)) return "closing"
 	return OTHER_KINDS.find(([, re]) => re.test(text))?.[0] ?? null
 }
 
@@ -111,7 +132,6 @@ function walkBody(ctx, node, state) {
 export function buildContext(doc, options) {
 	const lineageMode = options.lineageMode ?? "inline"
 	if (!LINEAGE_MODES.includes(lineageMode)) throw new TypeError(`lineageMode must be one of ${LINEAGE_MODES.join(", ")}`)
-	const closingPattern = options.closingPattern ? toRegExp(options.closingPattern) : null
 	const all = descendants(doc)
 	const styleBlocks = all.filter((node) => node.tag === "style").map((node) => ({ node, css: node.raw ?? "" }))
 	const styleAttrs = all.filter((node) => node.attrs.style).map((node) => ({ node, css: node.attrs.style }))
@@ -130,7 +150,7 @@ export function buildContext(doc, options) {
 		requireSections: (options.requireSections ?? []).map(toRegExp),
 		baseDir: options.baseDir ?? null,
 		fs: options.fs ?? nodeFs,
-		isClosing: (text) => CLOSING_HEADING.test(text) || Boolean(closingPattern?.test(text)),
+		isClosing: closingTest(options.closingPattern),
 		util: { classTokens, closest, descendants, hasCitation, citationMarker: CITATION_MARKER },
 		kindOf: (scope) => (scope.closingH3 ? "closing" : (scope.section?.kind ?? null)),
 		defect(code, node, message) {

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

@@ -54,8 +54,8 @@ function skipSpaces(source, at) {
 	return at
 }
 
-/** Read `<name attrs...>` starting just after `<`. */
-function readTag(source, start) {
+/** Read `<name attrs...>` starting just after `<`; the one attribute parser (any quoting). */
+export function readTag(source, start) {
 	const end = source.length
 	let at = start
 	while (at < end && !isSpace(source[at]) && source[at] !== ">" && source[at] !== "/") at++

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

@@ -0,0 +1,182 @@
+// Byte-preserving HTML boundaries for polish. No CSS or visibility inference.
+import { readTag } from "./html-lite.mjs"
+
+const RAW = new Set(["script", "style"])
+const FROZEN = new Set([...RAW, "template"])
+const VOID = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"])
+const isLetter = (ch) => /[a-z]/i.test(ch ?? "")
+
+function scan(src, at, visit) {
+	while (at < src.length) {
+		const start = src.indexOf("<", at)
+		if (start === -1) return
+		const next = src[start + 1]
+		let kind
+		let end
+		let tag = null
+		if (src.startsWith("<!--", start)) {
+			// From start + 2 so the abrupt closes <!--> and <!---> end where the HTML tokenizer ends them.
+			kind = "skip"
+			const stop = src.indexOf("-->", start + 2)
+			end = stop === -1 ? src.length : stop + 3
+		} else if (next === "!" || next === "?" || (next === "/" && !isLetter(src[start + 2]))) {
+			// Declarations, <?...> and </ + non-letter (</> included) are bogus comments up to the next ">".
+			kind = "skip"
+			const stop = src.indexOf(">", start + 2)
+			end = stop === -1 ? src.length : stop + 1
+		} else if (isLetter(next) || (next === "/" && isLetter(src[start + 2]))) {
+			kind = next === "/" ? "close" : "open"
+			tag = readTag(src, start + (kind === "close" ? 2 : 1))
+			end = tag.end
+		} else {
+			at = start + 1
+			continue
+		}
+		const resume = visit(kind, start, end, tag)
+		if (resume === Infinity) return
+		at = resume ?? (kind === "open" && RAW.has(tag.name) ? closeOf(src, end, tag.name) : end)
+	}
+}
+
+// Script data with its escaped and double-escaped states: a </script> inside <!--<script>...-->
+// does not end the script. Returns the end of the closing tag, or the end of input.
+const SCRIPT_MARKS = { data: /<!--|<\/script(?=[\s/>])/gi, escaped: /-->|<\/?script(?=[\s/>])/gi, double: /-->|<\/script(?=[\s/>])/gi }
+function scriptEnd(src, from) {
+	let state = "data"
+	let at = from
+	for (;;) {
+		const marks = SCRIPT_MARKS[state]
+		marks.lastIndex = at
+		const match = marks.exec(src)
+		if (!match) return src.length
+		const token = match[0].toLowerCase()
+		if (token === "-->") [state, at] = ["data", match.index + 3]
+		else if (token === "<!--") [state, at] = ["escaped", match.index + 2]
+		else if (token === "<script") [state, at] = ["double", match.index + 7]
+		else if (state === "double") [state, at] = ["escaped", match.index + 8]
+		else return readTag(src, match.index + 2).end
+	}
+}
+
+function closeOf(src, from, name) {
+	if (name === "script") return scriptEnd(src, from)
+	if (RAW.has(name)) {
+		const close = new RegExp(`</${name}(?=[\\s/>])[^>]*>`, "gi")
+		close.lastIndex = from
+		const match = close.exec(src)
+		return match ? match.index + match[0].length : src.length
+	}
+	let depth = 0
+	let stop = src.length
+	scan(src, from, (kind, _start, end, tag) => {
+		if (tag?.name !== name) return undefined
+		if (kind === "open") depth++
+		else if (depth === 0) {
+			stop = end
+			return Infinity
+		} else depth--
+		return undefined
+	})
+	return stop
+}
+
+const endOf = (src, end, tag) => VOID.has(tag.name) ? end : closeOf(src, end, tag.name)
+
+/** Raw markup sequence, corresponding text slots, and markup with frozen elements omitted. */
+export function markupParts(html) {
+	const src = String(html)
+	const markup = []
+	const text = []
+	let source = ""
+	let kept = 0
+	scan(src, 0, (kind, start, end, tag) => {
+		const frozen = kind === "open" && FROZEN.has(tag.name)
+		const stop = frozen ? endOf(src, end, tag) : end
+		text.push(src.slice(kept, start))
+		markup.push(src.slice(start, stop))
+		source += src.slice(kept, start) + (frozen || kind === "skip" ? " " : src.slice(start, stop))
+		kept = stop
+		return stop
+	})
+	text.push(src.slice(kept))
+	source += src.slice(kept)
+	return { markup, text, source }
+}
+
+/** Whole elements accepted by the caller; nested matches stay within the outer match. */
+export function elementSpans(html, accept) {
+	const src = String(html)
+	const spans = []
+	scan(src, 0, (kind, start, end, tag) => {
+		if (kind !== "open" || !accept(tag.name, tag.attrs)) return undefined
+		const stop = endOf(src, end, tag)
+		spans.push({ start, end: stop, tag })
+		return stop
+	})
+	return spans
+}
+
+export function tagAttributes(html) {
+	const tags = []
+	scan(String(html), 0, (kind, _start, _end, tag) => {
+		if (kind === "open") tags.push({ name: tag.name, attrs: tag.attrs })
+		return undefined
+	})
+	return tags
+}
+
+/**
+ * Constructs this tokenizer does not model exactly; renderer output never contains them, so polish
+ * refuses a document holding any of them instead of trusting the markup comparison.
+ */
+export function ambiguousMarkup(html) {
+	const src = String(html)
+	const found = new Set()
+	if (/<\/(?![a-z])/i.test(src)) found.add("</ before a non-letter")
+	if (/<!\[CDATA\[/i.test(src)) found.add("<![CDATA[")
+	if (src.includes("<?")) found.add("<?")
+	if (src.includes("--!>")) found.add("--!>")
+	scan(src, 0, (kind, start, end, tag) => {
+		if (kind !== "skip" && src.slice(start + 1, end).includes("<")) found.add("< inside a tag or attribute value")
+		if (kind === "open" && RAW.has(tag.name) && src.slice(end, closeOf(src, end, tag.name)).includes("<!--")) found.add(`<!-- inside ${tag.name}`)
+		return undefined
+	})
+	return [...found]
+}
+
+/** One character reference token of a text node: & up to the first ; or non-name character. */
+export const CHARACTER_REFERENCE = /&[^;\s<&]*;?/g
+
+/**
+ * The skeleton of a document: every markup token (tags, comments, bogus comments and the frozen
+ * content of script/style/template) and every character reference of a text node, in document
+ * order, each with its byte offset. Polish may change text node characters only, and an edit can
+ * carry neither <, > nor & and may not touch a character reference, so an edited span holds no
+ * skeleton token: a polished document keeps this sequence byte-identical.
+ */
+export function skeletonTokens(html) {
+	const { markup, text } = markupParts(html)
+	const tokens = []
+	let at = 0
+	text.forEach((slot, index) => {
+		for (const match of slot.matchAll(CHARACTER_REFERENCE)) tokens.push({ kind: "reference", value: match[0], offset: at + match.index })
+		at += slot.length
+		if (index < markup.length) {
+			tokens.push({ kind: "markup", value: markup[index], offset: at })
+			at += markup[index].length
+		}
+	})
+	return tokens
+}
+
+const describeToken = (token) => (token ? `${token.kind} ${JSON.stringify(token.value)} at offset ${token.offset}` : "end of document")
+
+/** The first skeleton token two documents disagree on, as a message, or null when they agree. */
+export function skeletonChange(beforeHtml, afterHtml) {
+	const [before, after] = [skeletonTokens(beforeHtml), skeletonTokens(afterHtml)]
+	for (let index = 0; index < Math.max(before.length, after.length); index++) {
+		if (before[index]?.value === after[index]?.value) continue
+		return `skeleton changed at token ${index}: ${describeToken(before[index])} became ${describeToken(after[index])}`
+	}
+	return null
+}