lazycodex-ai 5.1.44 → 5.1.46

package/packages/shared-skills/skills/ulw-research/scripts/report-tools.test.ts

@@ -1,8 +1,13 @@
 import { describe, expect, onTestFinished, test } from "bun:test"
-import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { createHash } from "node:crypto"
+import { copyFileSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { delimiter, join } from "node:path"
 
+import { PROMOTION } from "./fact-commands-meaning.mjs"
+import { writeFidelityRecord } from "./fidelity-records.mjs"
+import { PAIR_KINDS } from "./fact-pairs.mjs"
+import { VERDICT_SCHEMA } from "./meaning-check.mjs"
 import { COMMANDS, run } from "./report-tools.mjs"
 
 const SCRIPT = join(import.meta.dir, "report-tools.mjs")
@@ -33,7 +38,7 @@ describe("help and usage", () => {
 	test("#given --help --json #when run #then it lists exactly the command matrix", async () => {
 		const result = await run(["--help", "--json"])
 		expect(result.json.commands).toEqual([...COMMANDS])
-		expect(COMMANDS).toEqual(["check", "layout-probe", "repair decide", "outcome init", "outcome set", "outcome gate", "outcome render", "outcome state", "outcome verify", "outcome finish", "outcome briefing", "format-extract"])
+		expect(COMMANDS).toEqual(["check", "layout-probe", "repair decide", "outcome init", "outcome set", "outcome gate", "outcome render", "outcome state", "outcome verify", "outcome finish", "outcome briefing", "format-extract", "fact add", "fact quote", "fact retract", "fact export", "fact fill", "fact verify", "fact derive", "source snapshot", "claims index"])
 	})
 
 	test("#given no arguments under node #when spawned #then it exits 2 with a usage line on stderr", () => {
@@ -84,6 +89,7 @@ describe("outcome", () => {
 		await run(["outcome", "set", "pdf", "delivered", "--path", pdf, "--session-dir", dir])
 		await run(["outcome", "set", "docx", "skipped", "--reason", "no editing audience", "--session-dir", dir])
 		await run(["outcome", "gate", "static", "pass", "--session-dir", dir])
+		await run(["outcome", "gate", "fidelity", "not_run", "--reason", "Fixture has no factual content", "--session-dir", dir])
 		const after = await run(["outcome", "verify", "--session-dir", dir])
 		// then
 		expect(before.exitCode).toBe(1)
@@ -185,6 +191,7 @@ describe("manifest bookkeeping", () => {
 		await run(["outcome", "init", "--session-dir", dir, "--promised", "pdf"])
 		await run(["outcome", "set", "pdf", "delivered", "--path", pdf, "--session-dir", dir])
 		writeFileSync(join(dir, "sources-ledger.md"), ["[S1] https://a.example/x", "[S2] https://b.example/y"].join("\n"))
+		await run(["outcome", "gate", "fidelity", "not_run", "--reason", "Fixture has no factual content", "--session-dir", dir])
 		const now = new Date(new Date(2026, 0, 1, 12, 0, 0).getTime() + 30 * 60_000).toISOString()
 		const result = await run(["outcome", "finish", "--session-dir", dir, "--now", now])
 		const manifest = JSON.parse(readFileSync(join(dir, "outcome.json"), "utf8"))
@@ -212,3 +219,452 @@ describe("format-extract exit codes", () => {
 		expect(proc.exitCode).toBe(2)
 	})
 })
+
+const FIDELITY = join(FIXTURES, "fidelity")
+const sha256 = (path: string) => createHash("sha256").update(readFileSync(path)).digest("hex")
+
+type CliRow = { fact_id: string; kind: string; value: string | null }
+type CliJson = { data: { row: CliRow; context: { match: string } }; defects: { code: string }[] }
+
+function nodeJson(args: string[]) {
+	const proc = nodeWithoutBun(args)
+	const stdout = proc.stdout.toString()
+	let json = {} as CliJson
+	try {
+		json = JSON.parse(stdout) as CliJson
+	} catch {}
+	return { code: proc.exitCode, json, stdout, stderr: proc.stderr.toString() }
+}
+
+/** A session with the locked brief, S4 snapshotted, F1 (span), Q1 (completion), and F<n> (span in mm). */
+function fidelitySession() {
+	const dir = sessionDir()
+	copyFileSync(join(FIXTURES, "fidelity-brief-locked.md"), join(dir, "brief.md"))
+	const s = ["--session-dir", dir]
+	const snap = nodeJson(["source", "snapshot", "--id", "S4", "--html", join(FIDELITY, "sources", "S4.html"), ...s])
+	const add = nodeJson(["fact", "add", "--source", "S4", "--find", "Span length", "--label", "span_len", "--json", ...s])
+	const quote = nodeJson(["fact", "quote", "--source", "S4", "--match", "no earlier than 2027", "--label", "completion", "--json", ...s])
+	const derive = nodeJson(["fact", "derive", "--op", "convert", "F1", "--to", "mm", "--label", "span_mm", "--json", ...s])
+	const mm = derive.json.data?.row?.fact_id
+	const source = [
+		'<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Bridge</title></head><body><h1>Bridge</h1>',
+		"<h2>Findings</h2>",
+		"<p>The span length is {{F1:span_len}} [S4].</p>",
+		`<p>In millimetres the span is {{${mm}:span_mm}} [S4].</p>`,
+		"<p>The operator wrote {{Q1:completion}} [S4].</p>",
+		"<h2>How this report was made</h2><p>Collected from one cited public page [S4].</p>",
+		'<h2>Sources</h2><ol><li id="s4">[S4] Bridge page, retrieved 2026-10-01.</li></ol></body></html>',
+	].join("\n")
+	writeFileSync(join(dir, "report.src.html"), source)
+	return { dir, s, snap, add, quote, derive, mm }
+}
+
+function verify(dir: string, report: string, extra: string[] = []) {
+	return nodeJson(["fact", "verify", join(dir, report), "--sources", join(dir, "sources"), "--brief", join(dir, "brief.md"), "--session-dir", dir, ...extra])
+}
+
+const codesOf = (json: { defects?: { code: string }[] }) => (json.defects ?? []).map((d) => d.code)
+
+describe("fact, source, and claims under node", () => {
+	test("#given a fresh session #when snapshot, add, quote, derive, fill, and verify run #then the filled report verifies clean", () => {
+		// given
+		const { dir, s, snap, add, quote, derive, mm } = fidelitySession()
+		// when
+		const filled = nodeJson(["fact", "fill", join(dir, "report.src.html"), "--out", join(dir, "report.html"), ...s])
+		const checked = verify(dir, "report.html")
+		// then
+		expect(snap.code).toBe(0)
+		expect(add.code).toBe(0)
+		expect(add.json.data.row.value).toBe("320")
+		expect(add.json.data.context.match).toBe("320 m")
+		expect(quote.code).toBe(0)
+		expect(quote.json.data.row.fact_id).toBe("Q1")
+		expect(derive.code).toBe(0)
+		expect(mm).toBe("F2")
+		expect(filled.code).toBe(0)
+		expect(readFileSync(join(dir, "report.html"), "utf8")).toContain("320,000 mm (320 m)")
+		expect(checked.code).toBe(0)
+		expect(checked.json.defects).toEqual([])
+		const record = JSON.parse(readFileSync(join(dir, "fidelity-defects.json"), "utf8"))
+		expect(record.artifact_sha256).toBe(sha256(join(dir, "report.html")))
+	})
+
+	test("#given a filled report #when a value is hand-edited or a number typed #then verify exits 1 with the code", () => {
+		const { dir, s } = fidelitySession()
+		nodeJson(["fact", "fill", join(dir, "report.src.html"), "--out", join(dir, "report.html"), ...s])
+		const html = readFileSync(join(dir, "report.html"), "utf8")
+		writeFileSync(join(dir, "unit.html"), html.replace("320 m", "320 mm"))
+		writeFileSync(join(dir, "typed.html"), html.replace("<h2>How", "<p>Revenue grew 12% [S4].</p>\n<h2>How"))
+		const unit = verify(dir, "unit.html")
+		const typed = verify(dir, "typed.html")
+		expect(unit.code).toBe(1)
+		expect(codesOf(unit.json)).toContain("unit_mismatch")
+		expect(typed.code).toBe(1)
+		expect(codesOf(typed.json)).toContain("untraceable_number")
+	})
+
+	test("#given an anchor that is not in the source #when fact add runs #then it exits 1 with fact_not_located and writes no row", () => {
+		const { dir, s } = fidelitySession()
+		const proc = nodeJson(["fact", "add", "--source", "S4", "--find", "nope", "--label", "x", ...s])
+		expect(proc.code).toBe(1)
+		expect(proc.stdout).toContain("fact_not_located")
+		expect(JSON.parse(readFileSync(join(dir, "fact-ledger.json"), "utf8")).rows.map((r: { fact_id: string }) => r.fact_id)).toEqual(["F1", "Q1", "F2"])
+	})
+
+	test("#given a snapshotted source #when snapshotted again with the same or different content #then same is a no-op and different exits 1", () => {
+		const { dir, s } = fidelitySession()
+		writeFileSync(join(dir, "other.txt"), "Span length: 999 m\n")
+		expect(nodeJson(["source", "snapshot", "--id", "S4", "--html", join(FIDELITY, "sources", "S4.html"), ...s]).code).toBe(0)
+		expect(nodeJson(["source", "snapshot", "--id", "S4", "--text", join(dir, "other.txt"), ...s]).code).toBe(1)
+	})
+
+	test("#given an assumed value with and without a rationale #when added #then the row is kind assumed, and no rationale exits 2", () => {
+		const { s } = fidelitySession()
+		const added = nodeJson(["fact", "add", "--assumed", "12", "--unit", "%", "--rationale", "planning share chosen by the requester", "--label", "share_assumed", "--json", ...s])
+		expect(added.code).toBe(0)
+		expect(added.json.data.row.kind).toBe("assumed")
+		expect(nodeJson(["fact", "add", "--assumed", "12", "--label", "x", ...s]).code).toBe(2)
+	})
+
+	test("#given the fixture claim graph #when claims index runs #then claims.json lists its claims", () => {
+		const dir = sessionDir()
+		const proc = nodeJson(["claims", "index", join(FIDELITY, "claim-graph.md"), "--out", join(dir, "claims.json")])
+		expect(proc.code).toBe(0)
+		expect(JSON.parse(readFileSync(join(dir, "claims.json"), "utf8")).claims.length).toBeGreaterThan(0)
+	})
+
+	test("#given a ledger #when exported as csv #then rows carry fact_id and plot_value and stderr has the coverage line", () => {
+		const { s } = fidelitySession()
+		const proc = nodeJson(["fact", "export", "--csv", ...s])
+		expect(proc.code).toBe(0)
+		expect(proc.stdout.split("\n")[0]).toContain("fact_id")
+		expect(proc.stdout).toContain("F2")
+		expect(proc.stderr).toContain("1 of 1 sources snapshotted")
+	})
+})
+
+type Pair = { pair_id: string; kind: string; fact_ids?: string[]; sentence: string; quote?: string }
+
+/** A filled session plus the pair artifact `fact pairs` wrote for it. */
+function pairedSession() {
+	const session = fidelitySession()
+	const { dir, s } = session
+	nodeJson(["fact", "fill", join(dir, "report.src.html"), "--out", join(dir, "report.html"), ...s])
+	const pairs = nodeJson(["fact", "pairs", join(dir, "report.html"), "--ledger", join(dir, "fact-ledger.json"), "--out", join(dir, "pairs.json"), ...s])
+	return { ...session, pairs }
+}
+
+function verdicts(dir: string, name: string, tier: string, list: object[]) {
+	const file = join(dir, name)
+	writeFileSync(file, JSON.stringify({ model_tier: tier, verdicts: list }))
+	return file
+}
+
+const calibrationRows = (dir: string) =>
+	readFileSync(join(dir, "fidelity-calibration.jsonl"), "utf8")
+		.trim()
+		.split("\n")
+		.map((line) => JSON.parse(line))
+		.filter((row) => row.header !== true && row.run !== true)
+
+const runLines = (dir: string) =>
+	readFileSync(join(dir, "fidelity-calibration.jsonl"), "utf8")
+		.trim()
+		.split("\n")
+		.map((line) => JSON.parse(line))
+		.filter((row) => row.run === true)
+
+describe("meaning verifier under node", () => {
+	test("#given the filled fixture #when fact pairs runs #then pairs.json holds one quote pair per cited ledger quote", () => {
+		const { dir, pairs } = pairedSession()
+		const written = JSON.parse(readFileSync(join(dir, "pairs.json"), "utf8"))
+		expect(pairs.code).toBe(0)
+		expect(written.skipped).toBe(false)
+		expect(written.pairs.map((p: Pair) => [p.pair_id, p.kind, p.fact_ids])).toEqual([
+			["P1", "quote", ["F1"]],
+			["P2", "quote", ["Q1"]],
+		])
+		expect(written.pairs_sha256).toMatch(/^[0-9a-f]{64}$/)
+		expect(Object.keys(written.counts).filter((key) => key !== "total" && key !== "force_strong")).toEqual([...PAIR_KINDS])
+		expect(written.verdict_schema).toEqual(JSON.parse(JSON.stringify(VERDICT_SCHEMA)))
+	})
+
+	test("#given cheap and strong verdicts agreeing on hedge_dropped #when meaning-check runs #then it exits 1 with one confirmed defect and one calibration line", () => {
+		const { dir, s } = pairedSession()
+		const drift = { pair_id: "P2", verdict: "drift", drift_kind: "hedge_dropped", fragment: "no earlier than 2027", source_fragment: "we estimate", explanation: "The estimate reads as a fact." }
+		const cheap = verdicts(dir, "cheap.json", "cheap", [drift, { pair_id: "P1", verdict: "ok" }])
+		const strong = verdicts(dir, "strong.json", "strong", [drift])
+		const checked = nodeJson(["fact", "meaning-check", "--pairs", join(dir, "pairs.json"), "--verdicts", cheap, "--verdicts", strong, ...s])
+		const record = JSON.parse(readFileSync(join(dir, "fidelity-meaning-defects.json"), "utf8"))
+		expect(checked.code).toBe(1)
+		expect(codesOf(checked.json)).toEqual(["meaning_drift_confirmed"])
+		expect(codesOf(record)).toEqual(["meaning_drift_confirmed"])
+		expect(calibrationRows(dir)).toHaveLength(1)
+		expect(calibrationRows(dir)[0]).toMatchObject({ pair_id: "P2", drift_kind: "hedge_dropped", confirmed: true, disputed: false })
+		const header = JSON.parse(readFileSync(join(dir, "fidelity-calibration.jsonl"), "utf8").split("\n")[0])
+		expect(header.promotion).toEqual({ ...PROMOTION })
+		const again = nodeJson(["fact", "meaning-check", "--pairs", join(dir, "pairs.json"), "--verdicts", cheap, "--verdicts", strong, ...s])
+		expect(again.code).toBe(1)
+		expect(calibrationRows(dir)).toHaveLength(1)
+	})
+
+	test("#given a dispute on the confirmed pair #when meaning-check runs #then the defect stays and the calibration line is disputed", () => {
+		const { dir, s } = pairedSession()
+		const drift = { pair_id: "P2", verdict: "drift", drift_kind: "hedge_dropped", fragment: "no earlier than 2027", source_fragment: "we estimate" }
+		const files = ["--verdicts", verdicts(dir, "cheap.json", "cheap", [drift, { pair_id: "P1", verdict: "ok" }]), "--verdicts", verdicts(dir, "strong.json", "strong", [drift])]
+		const checked = nodeJson(["fact", "meaning-check", "--pairs", join(dir, "pairs.json"), ...files, "--dispute", "P2", "--reason", "the operator states it", ...s])
+		expect(checked.code).toBe(1)
+		expect(codesOf(checked.json)).toEqual(["meaning_drift_confirmed"])
+		expect(calibrationRows(dir)[0]).toMatchObject({ pair_id: "P2", disputed: true, reason: "the operator states it" })
+	})
+
+	test("#given a dropped verdict and an unread pair #when meaning-check runs #then both pairs are meaning_unverified and it exits 1", () => {
+		const { dir, s } = pairedSession()
+		const cheap = verdicts(dir, "cheap.json", "cheap", [{ pair_id: "P2", verdict: "drift", drift_kind: "hedge_dropped", fragment: "certainly by 2027", source_fragment: "we estimate" }])
+		const checked = nodeJson(["fact", "meaning-check", "--pairs", join(dir, "pairs.json"), "--verdicts", cheap, ...s])
+		const summary = JSON.parse(checked.stderr.trim().split("\n").at(-1) ?? "{}")
+		expect(checked.code).toBe(1)
+		expect(checked.json.status).toBe("fail")
+		expect(codesOf(checked.json)).toEqual(["meaning_unverified", "meaning_unverified"])
+		expect(checked.json.unverified.map((gap: { pair_id: string }) => gap.pair_id)).toEqual(["P1", "P2"])
+		expect(summary).toMatchObject({ command: "fact meaning-check", defects: 2, dropped: 1, unverified: 2 })
+	})
+
+	test("#given an unreadable verdict file or a malformed pairs file #when meaning-check runs #then it exits 2", () => {
+		const { dir, s } = pairedSession()
+		const broken = join(dir, "broken.json")
+		writeFileSync(broken, "{ not json")
+		expect(nodeJson(["fact", "meaning-check", "--pairs", join(dir, "pairs.json"), "--verdicts", broken, ...s]).code).toBe(2)
+		const ok = verdicts(dir, "cheap.json", "cheap", [])
+		for (const body of ["{}", "null", '{ "pairs": "P1" }']) {
+			writeFileSync(join(dir, "bad-pairs.json"), body)
+			expect(nodeJson(["fact", "meaning-check", "--pairs", join(dir, "bad-pairs.json"), "--verdicts", ok, ...s]).code, body).toBe(2)
+		}
+	})
+
+	test("#given a confirmed run then a dispute on the same inputs #when meaning-check reruns #then the log still holds one run with the dispute", () => {
+		const { dir, s } = pairedSession()
+		const drift = { pair_id: "P2", verdict: "drift", drift_kind: "hedge_dropped", fragment: "no earlier than 2027", source_fragment: "we estimate" }
+		const files = ["--verdicts", verdicts(dir, "cheap.json", "cheap", [drift, { pair_id: "P1", verdict: "ok" }]), "--verdicts", verdicts(dir, "strong.json", "strong", [drift])]
+		const first = nodeJson(["fact", "meaning-check", "--pairs", join(dir, "pairs.json"), ...files, ...s])
+		const disputed = nodeJson(["fact", "meaning-check", "--pairs", join(dir, "pairs.json"), ...files, "--dispute", "P2", "--reason", "the operator states it", ...s])
+		expect(disputed.code).toBe(1)
+		expect(disputed.json.run_id).toBe(first.json.run_id)
+		expect(disputed.json.promotion_eligibility).toMatchObject({ runs: 1, confirmed: 1, disputed_confirmed: 1, disputed_to_confirmed: 1 })
+		expect(calibrationRows(dir)).toEqual([expect.objectContaining({ pair_id: "P2", disputed: true, reason: "the operator states it" })])
+		const plain = nodeJson(["fact", "meaning-check", "--pairs", join(dir, "pairs.json"), ...files, ...s])
+		expect(plain.json.promotion_eligibility).toMatchObject({ runs: 1, disputed_confirmed: 1 })
+	})
+
+	test("#given a run with no flagged pair #when meaning-check runs #then the run is still logged and counted", () => {
+		const { dir, s } = pairedSession()
+		const ok = (pair_id: string) => ({ pair_id, verdict: "ok" })
+		const files = ["--verdicts", verdicts(dir, "cheap.json", "cheap", [ok("P1"), ok("P2")]), "--verdicts", verdicts(dir, "strong.json", "strong", [ok("P1"), ok("P2")])]
+		const checked = nodeJson(["fact", "meaning-check", "--pairs", join(dir, "pairs.json"), ...files, ...s])
+		expect(checked.code).toBe(0)
+		expect(calibrationRows(dir)).toEqual([])
+		expect(runLines(dir)).toEqual([expect.objectContaining({ run_id: checked.json.run_id, flagged: 0 })])
+		expect(checked.json.promotion_eligibility.runs).toBe(1)
+	})
+
+	test("#given a corrupt calibration log #when meaning-check runs #then it exits 2 naming the file and line", () => {
+		const { dir, s } = pairedSession()
+		writeFileSync(join(dir, "fidelity-calibration.jsonl"), "{ not json\n")
+		const checked = nodeJson(["fact", "meaning-check", "--pairs", join(dir, "pairs.json"), "--verdicts", verdicts(dir, "cheap.json", "cheap", []), ...s])
+		expect(checked.code).toBe(2)
+		expect(checked.stderr).toContain(`${join(dir, "fidelity-calibration.jsonl")}:1`)
+	})
+
+	test("#given a skipped pairs file #when meaning-check runs #then it is accepted only when the locked brief says off", () => {
+		const { dir, s } = fidelitySession()
+		const skip = join(dir, "skip.json")
+		writeFileSync(skip, JSON.stringify({ schemaVersion: 1, skipped: true, pairs: [] }))
+		const check = () => nodeJson(["fact", "meaning-check", "--pairs", skip, "--verdicts", verdicts(dir, "cheap.json", "cheap", []), ...s])
+		const on = check()
+		expect(on.code).toBe(1)
+		expect(on.json.error).toBe("meaning_check_required")
+		writeFileSync(join(dir, "brief.md"), "# Brief\n")
+		expect(check().json.error).toBe("fidelity_interview_incomplete")
+		expect(check().code).toBe(1)
+		writeFileSync(join(dir, "brief.md"), readFileSync(join(FIXTURES, "fidelity-brief-locked.md"), "utf8").replace("meaning check: on", "meaning check: off"))
+		const off = check()
+		expect(off.code).toBe(0)
+		expect(off.json.status).toBe("skipped")
+	})
+
+	test("#given a brief with meaning check off #when fact pairs runs #then it exits 0 and writes skipped", () => {
+		const { dir, s } = fidelitySession()
+		const brief = readFileSync(join(dir, "brief.md"), "utf8").replace("meaning check: on", "meaning check: off")
+		writeFileSync(join(dir, "brief.md"), brief)
+		nodeJson(["fact", "fill", join(dir, "report.src.html"), "--out", join(dir, "report.html"), ...s])
+		const pairs = nodeJson(["fact", "pairs", join(dir, "report.html"), "--out", join(dir, "pairs.json"), ...s])
+		expect(pairs.code).toBe(0)
+		expect(JSON.parse(readFileSync(join(dir, "pairs.json"), "utf8"))).toMatchObject({ skipped: true })
+	})
+})
+
+describe("markdown editions under node", () => {
+	const MD = ["# Bridge", "", "## Findings", "", "The span length is {{F1:span_len}} [S4].", "", "The operator wrote {{Q1:completion}} [S4].", "", "## How this report was made", "", "Collected from one cited public page [S4].", "", "## Sources", "", "1. [S4] Bridge page, retrieved 2026-10-01.", ""].join("\n")
+
+	function mdSession() {
+		const session = fidelitySession()
+		writeFileSync(join(session.dir, "report.src.md"), MD)
+		const filled = nodeJson(["fact", "fill", join(session.dir, "report.src.md"), "--format", "md", "--out", join(session.dir, "report.md"), ...session.s])
+		return { ...session, filled }
+	}
+
+	test("#given a markdown source #when filled and verified as md #then verify passes and records the md bytes", () => {
+		const { dir, filled } = mdSession()
+		const checked = verify(dir, "report.md", ["--format", "md"])
+		expect(filled.code).toBe(0)
+		expect(readFileSync(join(dir, "report.md"), "utf8")).toContain("The span length is 320 m [S4].")
+		expect(checked.code).toBe(0)
+		expect(checked.json.defects).toEqual([])
+		expect(JSON.parse(readFileSync(join(dir, "fidelity-defects.json"), "utf8")).artifact_sha256).toBe(sha256(join(dir, "report.md")))
+	})
+
+	test("#given a filled markdown edition #when a value is hand-edited or a number typed #then md verify exits 1 with the code", () => {
+		const { dir } = mdSession()
+		const md = readFileSync(join(dir, "report.md"), "utf8")
+		writeFileSync(join(dir, "typed.md"), md.replace("## How", "Revenue grew 12% [S4].\n\n## How"))
+		copyFileSync(join(dir, "report.md.fill-map.json"), join(dir, "typed.md.fill-map.json"))
+		const typed = verify(dir, "typed.md", ["--format", "md"])
+		expect(typed.code).toBe(1)
+		expect(codesOf(typed.json)).toContain("untraceable_number")
+	})
+
+	test("#given a filled markdown edition with an unterminated fence #when verified or paired #then both refuse with exit 2", () => {
+		const { dir, s } = mdSession()
+		writeFileSync(join(dir, "fence.md"), `${readFileSync(join(dir, "report.md"), "utf8")}\n\`\`\`\nunclosed code\n`)
+		copyFileSync(join(dir, "report.md.fill-map.json"), join(dir, "fence.md.fill-map.json"))
+		const checked = verify(dir, "fence.md", ["--format", "md"])
+		expect(checked.code).toBe(2)
+		expect(checked.stderr).toContain("unterminated_fence")
+		expect(nodeJson(["fact", "pairs", join(dir, "fence.md"), "--out", join(dir, "pairs.json"), ...s]).code).toBe(2)
+	})
+
+	test("#given a filled markdown edition #when fact pairs runs on it #then it pairs the same quotes as the html edition", () => {
+		const { dir, s } = mdSession()
+		const pairs = nodeJson(["fact", "pairs", join(dir, "report.md"), "--out", join(dir, "pairs.json"), ...s])
+		expect(pairs.code).toBe(0)
+		expect(JSON.parse(readFileSync(join(dir, "pairs.json"), "utf8")).pairs.map((p: Pair) => p.fact_ids)).toEqual([["F1"], ["Q1"]])
+	})
+})
+
+describe("repair decide with several defect files", () => {
+	test("#given two --defects files #when decided #then the attempt signature carries both codes", async () => {
+		const dir = sessionDir()
+		const state = join(dir, "repair-state.json")
+		await run(["repair", "decide", "--state", state, "--defects", defectsFile(dir, "a.json", ["heading_generic"]), "--defects", defectsFile(dir, "b.json", ["untraceable_number"])])
+		const signature = JSON.parse(readFileSync(state, "utf8")).attempts[0].signature
+		expect(signature).toContain("heading_generic")
+		expect(signature).toContain("untraceable_number")
+	})
+})
+
+describe("fidelity delivery barrier", () => {
+	/** The locked brief has meaning check on, so a deliverable session also carries a clean meaning record. */
+	const meaningRan = (dir: string) => writeFidelityRecord(join(dir, "fidelity-meaning-defects.json"), "meaning", { artifact_sha256: sha256(join(dir, "report.html")), report: join(dir, "report.html"), defects: [] })
+
+	async function deliveredSession(codes: string[]) {
+		const { dir, s } = fidelitySession()
+		nodeJson(["fact", "fill", join(dir, "report.src.html"), "--out", join(dir, "report.html"), ...s])
+		meaningRan(dir)
+		const record = (list: string[]) => writeFidelityRecord(join(dir, "fidelity-defects.json"), "fidelity", { artifact_sha256: sha256(join(dir, "report.html")), report: join(dir, "report.html"), defects: list.map((code) => ({ code, message: code })) })
+		record(codes)
+		await run(["outcome", "init", "--session-dir", dir, "--promised", "html"])
+		await run(["outcome", "set", "html", "delivered", "--path", join(dir, "report.html"), "--verified-by", join(dir, "fidelity-defects.json"), "--session-dir", dir])
+		const decide = ["repair", "decide", "--state", join(dir, "repair-state.json"), "--defects", join(dir, "fidelity-defects.json"), "--artifact-bytes", "4096", "--renders", "1", "--session-dir", dir]
+		await run(decide)
+		const decision = await run(decide)
+		return { dir, record, decision }
+	}
+
+	test("#given a clean meaning record #when the report is edited and fact verify re-run #then the stale meaning record refuses, and a fresh one passes", async () => {
+		// given: meaning check on, readers clean, the edition verified and delivered
+		const { dir, s } = pairedSession()
+		const report = join(dir, "report.html")
+		const clean = [{ pair_id: "P1", verdict: "ok" }, { pair_id: "P2", verdict: "ok" }]
+		const readers = () => nodeJson(["fact", "meaning-check", "--pairs", join(dir, "pairs.json"), "--verdicts", verdicts(dir, "cheap.json", "cheap", clean), "--verdicts", verdicts(dir, "strong.json", "strong", clean), ...s])
+		expect(readers().code).toBe(0)
+		expect(verify(dir, "report.html").code).toBe(0)
+		await run(["outcome", "init", "--session-dir", dir, "--promised", "html"])
+		await run(["outcome", "set", "html", "delivered", "--path", report, "--verified-by", join(dir, "fidelity-defects.json"), "--session-dir", dir])
+		const first = await run(["outcome", "verify", "--session-dir", dir])
+		// when: draft 2 (a repair rewrite) is re-verified by fact verify only
+		writeFileSync(report, `${readFileSync(report, "utf8")}\n<!-- draft 2 -->\n`)
+		expect(verify(dir, "report.html").code).toBe(0)
+		const stale = await run(["outcome", "verify", "--session-dir", dir])
+		// when: the meaning readers run again on draft 2
+		expect(nodeJson(["fact", "pairs", report, "--out", join(dir, "pairs.json"), ...s]).code).toBe(0)
+		expect(readers().code).toBe(0)
+		const fresh = await run(["outcome", "verify", "--session-dir", dir])
+		// then
+		expect(first.exitCode).toBe(0)
+		expect(stale.exitCode).toBe(1)
+		expect(stale.json.problems).toContainEqual(expect.objectContaining({ code: "edition_unverified", path: join(dir, "fidelity-meaning-defects.json"), message: expect.stringContaining("meaning record") }))
+		expect(fresh.exitCode).toBe(0)
+	})
+
+	test("#given an unregistered appendix value #when verified #then untraceable_number and outcome verify refuses", async () => {
+		const { dir, s } = fidelitySession()
+		nodeJson(["fact", "fill", join(dir, "report.src.html"), "--out", join(dir, "report.html"), ...s])
+		const html = readFileSync(join(dir, "report.html"), "utf8").replace("<h2>How", "<h2>Appendix</h2>\n<p>Revenue grew 12% [S4].</p>\n<h2>How")
+		writeFileSync(join(dir, "report.html"), html)
+		const checked = verify(dir, "report.html")
+		await run(["outcome", "init", "--session-dir", dir, "--promised", "html"])
+		await run(["outcome", "set", "html", "delivered", "--path", join(dir, "report.html"), "--verified-by", join(dir, "fidelity-defects.json"), "--session-dir", dir])
+		const outcome = await run(["outcome", "verify", "--session-dir", dir])
+		expect(codesOf(checked.json)).toContain("untraceable_number")
+		expect(outcome.exitCode).toBe(1)
+		expect(outcome.json.problems.map((p: { code: string }) => p.code)).toContain("fidelity_unresolved")
+	})
+
+	for (const code of ["untraceable_number", "unbound_sentence"]) {
+		test(`#given ${code} left after repair delivers on exhaustion #when verified and finished #then both refuse, and an empty record passes`, async () => {
+			const { dir, record, decision } = await deliveredSession([code])
+			const refused = await run(["outcome", "verify", "--session-dir", dir])
+			const finish = await run(["outcome", "finish", "--session-dir", dir])
+			record([])
+			const passed = await run(["outcome", "verify", "--session-dir", dir])
+			const finished = await run(["outcome", "finish", "--session-dir", dir])
+			expect(decision.json.decision.action).toBe("deliver")
+			expect(refused.exitCode).toBe(1)
+			expect(JSON.stringify(refused.json.problems)).toContain(`fidelity_unresolved: ${code}`)
+			expect(finish.exitCode).toBe(1)
+			expect(passed.exitCode).toBe(0)
+			expect(finished.exitCode).toBe(0)
+		})
+	}
+
+	test("#given a clean main report and an inline edition #when the edition lacks or mismatches its verify record #then edition_unverified, and its own record passes", async () => {
+		// given
+		const { dir, s } = fidelitySession()
+		nodeJson(["fact", "fill", join(dir, "report.src.html"), "--out", join(dir, "report.html"), ...s])
+		expect(verify(dir, "report.html").code).toBe(0)
+		meaningRan(dir)
+		expect(nodeJson(["fact", "fill", join(dir, "report.src.html"), "--inline", "--out", join(dir, "report.inline.html"), ...s]).code).toBe(0)
+		await run(["outcome", "init", "--session-dir", dir, "--promised", "html,pdf"])
+		await run(["outcome", "set", "html", "delivered", "--path", join(dir, "report.html"), "--verified-by", join(dir, "fidelity-defects.json"), "--session-dir", dir])
+		const problems = async () => {
+			const result = await run(["outcome", "verify", "--session-dir", dir])
+			return { exitCode: result.exitCode, codes: result.json.problems.map((p: { code: string }) => p.code) }
+		}
+		// when: no --verified-by
+		await run(["outcome", "set", "pdf", "delivered", "--path", join(dir, "report.inline.html"), "--session-dir", dir])
+		const missing = await problems()
+		// when: a record for different bytes
+		expect(verify(dir, "report.inline.html", ["--out", join(dir, "fidelity-inline.json")]).code).toBe(0)
+		const inline = readFileSync(join(dir, "report.inline.html"), "utf8")
+		writeFileSync(join(dir, "report.inline.html"), inline.replace("320,000 mm", "330,000 mm"))
+		await run(["outcome", "set", "pdf", "delivered", "--path", join(dir, "report.inline.html"), "--verified-by", join(dir, "fidelity-inline.json"), "--session-dir", dir])
+		const altered = await problems()
+		// when: restored to the verified bytes
+		writeFileSync(join(dir, "report.inline.html"), inline)
+		const matched = await problems()
+		// then
+		expect(missing).toEqual({ exitCode: 1, codes: ["edition_unverified"] })
+		expect(altered).toEqual({ exitCode: 1, codes: ["edition_unverified"] })
+		expect(matched).toEqual({ exitCode: 0, codes: [] })
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/sentence-split.mjs

@@ -0,0 +1,77 @@
+// sentence-split.mjs - deterministic sentence index for snapshot text.
+//
+// splitSentences(text) returns [{ sid, start, end, text }] with sid "s<k>" (1-based) and
+// start/end as offsets into the raw text, so text.slice(start, end) === record.text.
+// Boundaries: a line break; ". ! ?" followed by whitespace or end of line (known
+// abbreviations such as "e.g." excepted); and the Korean endings da. yo. nida. kka? even
+// with no following space, unless closing punctuation follows (quoted speech such as
+// '...da."rago' then needs whitespace like any other terminator). "no." is an abbreviation
+// only before a number ("No. 5"). Plain Node ESM, no dependencies.
+
+import { normalizeText } from "./text-normalize.mjs"
+
+const TERMINATORS = ".!?"
+const CLOSERS = "\"')]}\u201D\u2019\u00BB\u300D\u300F"
+const KOREAN_PERIOD_ENDINGS = new Set(["\uB2E4", "\uC694"]) // da, yo (nida ends in da)
+const KOREAN_QUESTION_ENDING = "\uAE4C" // kka
+const ABBREVIATIONS = new Set([
+	"e.g", "i.e", "etc", "vs", "cf", "approx", "al", "fig", "no", "mr", "mrs", "ms", "dr", "prof", "inc", "ltd", "jr", "sr",
+])
+const SPACE = /\s/u
+
+function isKoreanEnding(line, at) {
+	const prev = line[at - 1]
+	if (line[at] === ".") return KOREAN_PERIOD_ENDINGS.has(prev)
+	return line[at] === "?" && prev === KOREAN_QUESTION_ENDING
+}
+
+function isAbbreviation(line, from, at) {
+	let k = at
+	while (k > from && !SPACE.test(line[k - 1])) k--
+	const word = line.slice(k, at).replace(/^[("'[]+/u, "").toLowerCase()
+	if (word === "no") return /^\s*\d/u.test(line.slice(at + 1))
+	return ABBREVIATIONS.has(word)
+}
+
+function pushSegment(line, base, from, to, out) {
+	let start = from
+	let end = to
+	while (start < end && SPACE.test(line[start])) start++
+	while (end > start && SPACE.test(line[end - 1])) end--
+	const text = line.slice(start, end)
+	if (normalizeText(text) === "") return
+	out.push({ sid: `s${out.length + 1}`, start: base + start, end: base + end, text })
+}
+
+function splitLine(line, base, out) {
+	let from = 0
+	for (let i = 0; i < line.length; i++) {
+		if (!TERMINATORS.includes(line[i])) continue
+		let j = i + 1
+		while (j < line.length && (TERMINATORS.includes(line[j]) || CLOSERS.includes(line[j]))) j++
+		const atBreak = j >= line.length || SPACE.test(line[j])
+		const closed = [...line.slice(i + 1, j)].some((c) => CLOSERS.includes(c))
+		const korean = !closed && isKoreanEnding(line, i)
+		const abbreviation = line[i] === "." && !korean && isAbbreviation(line, from, i)
+		if ((atBreak || korean) && !abbreviation) {
+			pushSegment(line, base, from, j, out)
+			from = j
+		}
+		i = j - 1
+	}
+	pushSegment(line, base, from, line.length, out)
+}
+
+export function splitSentences(text) {
+	const source = String(text ?? "")
+	const out = []
+	let base = 0
+	while (base <= source.length) {
+		const newline = source.indexOf("\n", base)
+		const stop = newline === -1 ? source.length : newline
+		splitLine(source.slice(base, stop), base, out)
+		if (newline === -1) break
+		base = newline + 1
+	}
+	return out
+}