oh-my-opencode 5.1.44 → 5.1.46

package/dist/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/dist/skills/ulw-research/scripts/fidelity-values.test.ts

@@ -0,0 +1,270 @@
+import { describe, expect, test } from "bun:test"
+import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { exportRows, valueChecks } from "./fidelity-values.mjs"
+import { buildContext } from "./gates-static.mjs"
+import { parseHtml } from "./html-lite.mjs"
+import { similarity } from "./text-similarity.mjs"
+
+type Defect = { code: string; severity: string; selector: string; line: number; message: string; hint: string }
+type Row = Record<string, unknown> & { fact_id: string }
+type Ledger = { schemaVersion: number; rows: Row[]; events: unknown[] }
+type Options = { ledger?: Ledger; fillMap?: unknown[] | null; sourcesDir?: string | null; baseDir?: string; recompute?: (ledger: Ledger, row: Row) => { ok: boolean }; asOf?: string }
+
+const FIX = join(import.meta.dir, "tests", "fixtures", "fidelity")
+const SOURCES = join(FIX, "sources")
+const LEDGER: Ledger = JSON.parse(readFileSync(join(FIX, "ledger-verify.json"), "utf8"))
+const FULL = "we estimate completion no earlier than 2027"
+
+function ledgerWith(id: string, patch: Record<string, unknown>): Ledger {
+	const copy = structuredClone(LEDGER)
+	copy.rows = copy.rows.map((row) => (row.fact_id === id ? { ...row, ...patch } : row))
+	return copy
+}
+
+function run(body: string, options: Options = {}): Defect[] {
+	const html = /<h2/.test(body) ? body : `<h2>Findings</h2>\n${body}`
+	const ctx = buildContext(parseHtml(html), { baseDir: options.baseDir ?? FIX })
+	const sourcesDir = options.sourcesDir === undefined ? SOURCES : options.sourcesDir
+	return valueChecks(ctx, options.ledger ?? LEDGER, options.fillMap ?? null, sourcesDir, options) as Defect[]
+}
+
+const codes = (defects: Defect[]) => defects.map((defect) => defect.code)
+const fact = (id: string, text: string, unit = "") => `<data class="fact" data-fact="${id}"${unit ? ` data-unit="${unit}"` : ""}>${text}</data>`
+const quote = (sel: string, text: string) => `<p>They wrote <q data-fact="Q1" data-quote-sel="${sel}">${text}</q> [S4].</p>`
+
+const TICKS = (labels: string[]) => `<g class="ticks" data-tick-step="10" data-tick-min="0" data-tick-max="30">${labels.map((label) => `<text>${label}</text>`).join("")}</g>`
+const chart = (attrs: string, ticks: string[], labels: string[]) =>
+	`<figure ${attrs}><svg viewBox="0 0 200 100">${TICKS(ticks)}${labels.map((label) => `<text>${label}</text>`).join("")}</svg><figcaption>Share by segment [S4].</figcaption></figure>`
+
+describe("untraceable numbers", () => {
+	test("#given a typed 12% with no ledger row #when checked #then untraceable_number", () => {
+		expect(codes(run("<p>Revenue grew 12% [S4].</p>"))).toEqual(["untraceable_number"])
+	})
+
+	test("#given a table cell numeral without data-fact #when checked #then untraceable_number covers table cells", () => {
+		const defects = run("<table><tr><th>Metric</th><th>Value</th></tr><tr><td>Span</td><td>320 m</td></tr></table>")
+		expect(codes(defects)).toEqual(["untraceable_number"])
+	})
+
+	test("#given an appendix sentence with a citation but no row #when checked #then the citation does not exempt it", () => {
+		expect(codes(run("<h2>Appendix</h2><p>Revenue grew 12% [S4].</p>"))).toEqual(["untraceable_number"])
+	})
+
+	test("#given the same sentence under Sources #when checked #then it is out of scope", () => {
+		expect(run("<h2>Sources</h2><p>Revenue grew 12% [S4].</p>")).toEqual([])
+	})
+
+	test("#given a date in prose #when checked #then dates are in scope", () => {
+		expect(codes(run("<p>The board met on 2026-03-04 [S4].</p>"))).toEqual(["untraceable_number"])
+	})
+
+	test("#given heading numbering, figure references, versions and times #when checked #then structural numerals are exempt", () => {
+		const body = "<h2>2. Findings</h2><p>See Figure 3 and table 2 on page 7; v1.2.3 shipped at 10:30 [S4].</p>"
+		expect(run(body)).toEqual([])
+	})
+
+	test("#given the good report's facts #when checked #then numerals inside data-fact and Q elements are traced", () => {
+		const body = `<p>The span is ${fact("F1", "up to 320 m", "m")} long [S4].</p>${quote("full", FULL)}`
+		expect(run(body)).toEqual([])
+	})
+})
+
+describe("protected values", () => {
+	test("#given '320 mm' on a 320 m row #when checked #then unit_mismatch", () => {
+		expect(codes(run(`<p>Span ${fact("F1", "320 mm", "m")} [S4].</p>`))).toEqual(["unit_mismatch"])
+	})
+
+	test("#given '1,273' on a 1,237 row #when checked #then value_mismatch", () => {
+		expect(codes(run(`<p>Units ${fact("F2", "1,273")} [S4].</p>`))).toEqual(["value_mismatch"])
+	})
+
+	test("#given the converted row's render #when checked #then it verifies clean", () => {
+		expect(run(`<p>Span ${fact("F8", "320,000 mm (320 m)", "mm")} [S4].</p>`)).toEqual([])
+	})
+
+	test("#given a data-fact id with no ledger row #when checked #then unresolved_placeholder", () => {
+		expect(codes(run(`<p>Span ${fact("F99", "5 m")} [S4].</p>`))).toEqual(["unresolved_placeholder"])
+	})
+
+	test("#given a leftover placeholder #when checked #then unresolved_placeholder", () => {
+		expect(codes(run("<p>Next year brings {{F9:growth}} more traffic [S4].</p>"))).toEqual(["unresolved_placeholder"])
+	})
+})
+
+describe("quotes", () => {
+	test("#given a digit changed inside a rendered quote #when checked #then quote_not_verbatim with no fuzzy downgrade", () => {
+		const altered = FULL.replace("2027", "2028")
+		expect(similarity(altered, FULL)).toBeGreaterThan(0.95)
+		expect(codes(run(quote("full", altered)))).toEqual(["quote_not_verbatim"])
+	})
+
+	const SELECTIONS: [string, string, string][] = [
+		["full", FULL, FULL.replace("estimate", "expect")],
+		["lead=4", "we estimate completion no\u2026", "we estimate completion soon\u2026"],
+		["from=no earlier;to=2027", "\u2026no earlier than 2027", "\u2026no later than 2027"],
+	]
+	for (const [sel, rendered, altered] of SELECTIONS) {
+		test(`#given fill's ${sel} rendering #when verified #then clean, and one altered word is quote_not_verbatim`, () => {
+			expect(run(quote(sel, rendered))).toEqual([])
+			expect(codes(run(quote(sel, altered)))).toEqual(["quote_not_verbatim"])
+		})
+	}
+
+	test("#given a quote row flagged fuzzy at registration #when cited #then quote_fuzzy_match describes the source", () => {
+		expect(codes(run(quote("full", FULL), { ledger: ledgerWith("Q1", { fuzzy: true }) }))).toEqual(["quote_fuzzy_match"])
+	})
+
+	test("#given a quote revision that differs from the brief's as-of anchor #when checked #then quote_stale_version", () => {
+		const ledger = ledgerWith("Q1", { revision: "v3.1" })
+		expect(codes(run(quote("full", FULL), { ledger, asOf: "v3.2 (release notes)" }))).toEqual(["quote_stale_version"])
+		expect(run(quote("full", FULL), { ledger, asOf: "v3.1" })).toEqual([])
+		expect(run(quote("full", FULL), { ledger, asOf: "latest at run start, 2026-10-23" })).toEqual([])
+	})
+})
+
+describe("quote binding", () => {
+	test("#given a <q> with no Q row #when checked #then quote_unbound (rule a)", () => {
+		expect(codes(run("<p><q>Completion is guaranteed.</q> [S4]</p>"))).toEqual(["quote_unbound"])
+	})
+
+	test("#given a quoted run of three words with a citation and no fillMap Q entry #when checked #then quote_unbound (rule c)", () => {
+		expect(codes(run('<p>"Completion is guaranteed." [S4]</p>', { fillMap: [] }))).toEqual(["quote_unbound"])
+	})
+
+	test("#given the same quote covered by a fillMap Q entry #when checked #then clean", () => {
+		const ledger = structuredClone(LEDGER)
+		ledger.rows.push({ ...ledger.rows.find((row) => row.fact_id === "Q1"), fact_id: "Q2", label: "guarantee", quote: "Completion is guaranteed.", raw: "Completion is guaranteed." } as Row)
+		const fillMap = [{ token: "{{Q2:guarantee}}", fact_id: "Q2", start: 0, end: 27, rendered: '"Completion is guaranteed."', selector: "full" }]
+		expect(run('<p>"Completion is guaranteed." [S4]</p>', { ledger, fillMap })).toEqual([])
+	})
+
+	test("#given a four-word quoted run with no citation #when checked #then quote_unbound (rule b)", () => {
+		expect(codes(run('<p>The plan says "no earlier than 2027" for now.</p>'))).toContain("quote_unbound")
+	})
+
+	test("#given a single quoted UI label without a citation #when checked #then not a quotation", () => {
+		expect(run('<p>Press the "Save" button.</p>')).toEqual([])
+	})
+
+	test("#given a single quoted term followed by a citation #when checked #then quote_unbound (rule c)", () => {
+		expect(codes(run('<p>Press the "Save" button [S4].</p>'))).toEqual(["quote_unbound"])
+	})
+})
+
+describe("fill maps (Markdown)", () => {
+	test("#given a fillMap F entry whose text was edited after fill #when checked #then value_mismatch", () => {
+		const fillMap = [{ token: "{{F2:units_sold}}", fact_id: "F2", start: 0, end: 5, rendered: "1,273" }]
+		expect(codes(run("<p>Units sold reached 1,273 [S4].</p>", { fillMap }))).toEqual(["value_mismatch"])
+	})
+
+	test("#given a fillMap F entry that matches its row and the text #when checked #then the numeral is traced", () => {
+		const fillMap = [{ token: "{{F2:units_sold}}", fact_id: "F2", start: 0, end: 5, rendered: "1,237" }]
+		expect(run("<p>Units sold reached 1,237 [S4].</p>", { fillMap })).toEqual([])
+	})
+})
+
+describe("derivations, joins, snapshots", () => {
+	test("#given recompute reports a tampered derived row #when checked #then value_mismatch", () => {
+		const body = `<p>Span ${fact("F8", "320,000 mm (320 m)", "mm")} [S4].</p>`
+		expect(codes(run(body, { recompute: () => ({ ok: false }) }))).toEqual(["value_mismatch"])
+		expect(run(body, { recompute: () => ({ ok: true }) })).toEqual([])
+	})
+
+	test("#given a derived row whose operand was observed outside its snapshot window #when checked #then snapshot_mismatch", () => {
+		const ledger = ledgerWith("F8", { snapshot_window: { dataset_id: "d1", start: "2026-11-01T00:00:00Z", end: "2026-12-01T00:00:00Z" } })
+		expect(codes(run(`<p>Span ${fact("F8", "320,000 mm (320 m)", "mm")} [S4].</p>`, { ledger }))).toEqual(["snapshot_mismatch"])
+	})
+
+	test("#given a table row joining two observations #when checked #then join_integrity_fail", () => {
+		const table = `<table><tr><td>${fact("F1", "320 m", "m")}</td><td>${fact("F3", "12%", "%")}</td></tr></table>`
+		expect(codes(run(table))).toEqual(["join_integrity_fail"])
+		expect(run(table.replace("<tr>", '<tr data-row-kind="comparison">'))).toEqual([])
+	})
+
+	test("#given a snapshot whose text changed after pinning #when checked #then snapshot_hash_mismatch", () => {
+		const dir = mkdtempSync(join(tmpdir(), "fidelity-values-"))
+		try {
+			cpSync(SOURCES, dir, { recursive: true })
+			writeFileSync(join(dir, "S4", "text.txt"), "edited\n")
+			expect(codes(run(`<p>Span ${fact("F1", "up to 320 m", "m")} [S4].</p>`, { sourcesDir: dir }))).toEqual(["snapshot_hash_mismatch"])
+		} finally {
+			rmSync(dir, { recursive: true, force: true })
+		}
+	})
+
+})
+
+describe("verification claims are structural (data-claim-kind)", () => {
+	const verified = (id: string, text: string, unit = "") => fact(id, text, unit).replace("<data ", '<data data-claim-kind="verified" ')
+	const severities = (defects: Defect[]) => defects.map((defect) => `${defect.code}:${defect.severity}`)
+
+	test("#given a claim MARKED verified citing a measured page row #when checked #then unsupported_verification major", () => {
+		expect(severities(run(`<p>The span is ${verified("F1", "up to 320 m", "m")} [S4].</p>`))).toEqual(["unsupported_verification:major"])
+	})
+
+	test("#given a claim MARKED verified citing a recorded command row #when checked #then no defect", () => {
+		expect(run(`<p>The suite ran with ${verified("F7", "42 passed")} [S5].</p>`)).toEqual([])
+	})
+
+	test("#given an UNMARKED pretend-verification sentence #when checked #then verification_claim_unmarked as a minor warning and no major", () => {
+		expect(severities(run("<p>We verified the span by running the measurement script [S4].</p>"))).toEqual(["verification_claim_unmarked:minor"])
+	})
+
+	const quiet = [
+		`<p>The tests showed a ${fact("F3", "12%", "%")} drop [S4].</p>`,
+		`<p>The bridge, which ran across the river, spans ${fact("F1", "up to 320 m", "m")} [S4].</p>`,
+		`<p>The span is ${fact("F1", "up to 320 m", "m")}, as confirmed with the annual inspection report [S4].</p>`,
+		`<p>Clinical tests confirmed the span of ${fact("F1", "up to 320 m", "m")} [S4].</p>`,
+		`<p>확인된 길이는 ${fact("F1", "최대 320 m", "m")} [S4].</p>`,
+	]
+	for (const body of quiet) {
+		test(`#given findings prose ${JSON.stringify(body.replace(/<[^>]+>/g, ""))} #when checked #then no warning and no major`, () => expect(run(body)).toEqual([]))
+	}
+
+	test("#given an UNMARKED Korean run-and-check sentence #when checked #then verification_claim_unmarked minor only", () => {
+		expect(severities(run(`<p>우리가 실행해 확인한 길이는 ${fact("F1", "최대 320 m", "m")} [S4].</p>`))).toEqual(["verification_claim_unmarked:minor"])
+	})
+
+	test("#given the same run-and-check sentence MARKED verified on a command row #when checked #then no warning", () => {
+		expect(run(`<p>We ran the suite by running the test script, and it reported ${verified("F7", "42 passed")} [S5].</p>`)).toEqual([])
+	})
+})
+
+describe("charts", () => {
+	const SRC = 'data-chart-source="assets/share.csv"'
+
+	test("#given a chart with an on-grid ticks group and a data label matching the CSV #when checked #then clean", () => {
+		expect(run(chart(SRC, ["0", "10", "20", "30"], ["12%"]))).toEqual([])
+	})
+
+	test("#given an off-grid tick #when checked #then chart_value_untraceable", () => {
+		expect(codes(run(chart(SRC, ["0", "10", "25", "30"], ["12%"])))).toEqual(["chart_value_untraceable"])
+	})
+
+	test("#given a data label with no CSV plot value #when checked #then chart_value_untraceable", () => {
+		expect(codes(run(chart(SRC, ["0", "10", "20", "30"], ["13%"])))).toEqual(["chart_value_untraceable"])
+	})
+
+	test("#given a chart figure without data-chart-source #when checked #then chart_value_untraceable", () => {
+		expect(codes(run(chart("", ["0", "10", "20", "30"], ["12%"])))).toEqual(["chart_value_untraceable"])
+	})
+
+	test("#given a CSV whose row differs from the ledger export #when checked #then chart_value_untraceable", () => {
+		const dir = mkdtempSync(join(tmpdir(), "fidelity-chart-"))
+		try {
+			writeFileSync(join(dir, "share.csv"), "fact_id,plot_value,unit\nF5,13,%\nF6,27,%\n")
+			expect(codes(run(chart('data-chart-source="share.csv"', ["0", "10", "20", "30"], ["27%"]), { baseDir: dir }))).toEqual(["chart_value_untraceable"])
+		} finally {
+			rmSync(dir, { recursive: true, force: true })
+		}
+	})
+
+	test("#given the ledger #when exported #then each active value row gives fact_id, plot_value and unit", () => {
+		const rows = exportRows(LEDGER) as { fact_id: string; plot_value: string; unit: string }[]
+		expect(rows.find((row) => row.fact_id === "F5")).toMatchObject({ plot_value: "12", unit: "%" })
+		expect(rows.some((row) => row.fact_id === "Q1")).toBe(false)
+	})
+})

package/dist/skills/ulw-research/scripts/gates-context.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { parseLineageMode, parsePalette } from "./design-spec.mjs"
+import * as gatesStatic from "./gates-static.mjs"
+import * as gatesStructure from "./gates-structure.mjs"
+import { parseHtml } from "./html-lite.mjs"
+
+const FIXTURES = join(import.meta.dir, "tests", "fixtures")
+const GOOD = readFileSync(join(FIXTURES, "good-report.html"), "utf8")
+const SPEC = readFileSync(join(FIXTURES, "design-spec.md"), "utf8")
+
+type BuildContext = (doc: unknown, options: Record<string, unknown>) => Record<string, unknown>
+
+function buildContextExport(): BuildContext {
+	const buildContext = (gatesStatic as Record<string, unknown>).buildContext
+	if (typeof buildContext !== "function") throw new Error("buildContext is not exported")
+	return buildContext as BuildContext
+}
+
+describe("static-gate context exports", () => {
+	test("#given gates-static #when imported #then buildContext is an exported function", () => {
+		// given
+		const exported = (gatesStatic as Record<string, unknown>).buildContext
+		// when
+		const kind = typeof exported
+		// then
+		expect(kind).toBe("function")
+	})
+
+	test("#given the passing fixture report #when buildContext runs #then the walk, sections and helpers are present", () => {
+		// given
+		const buildContext = buildContextExport()
+		const options = { palette: parsePalette(SPEC), lineageMode: parseLineageMode(SPEC), requireSections: [], baseDir: FIXTURES }
+		// when
+		const ctx = buildContext(parseHtml(GOOD), options) as {
+			elements: unknown[]
+			texts: unknown[]
+			sections: { kind: string | null }[]
+			util: { hasCitation: unknown; citationMarker: unknown }
+			kindOf: unknown
+		}
+		// then
+		expect(ctx.elements.length).toBeGreaterThan(0)
+		expect(ctx.texts.length).toBeGreaterThan(0)
+		expect(ctx.sections.length).toBeGreaterThan(0)
+		expect(ctx.sections.map((section) => section.kind)).toContain("sources")
+		expect(typeof ctx.util.hasCitation).toBe("function")
+		expect(ctx.util.citationMarker).toBeInstanceOf(RegExp)
+		expect(typeof ctx.kindOf).toBe("function")
+	})
+
+	test("#given gates-structure #when imported #then UNCHECKED_KINDS lists the closing and sources kinds", () => {
+		// given
+		const unchecked = (gatesStructure as Record<string, unknown>).UNCHECKED_KINDS as Set<string> | undefined
+		// when
+		const kinds = unchecked ? [...unchecked] : []
+		// then
+		expect(unchecked).toBeInstanceOf(Set)
+		expect(kinds).toContain("closing")
+		expect(kinds).toContain("sources")
+	})
+})