lazycodex-ai 5.1.44 → 5.1.46

package/packages/shared-skills/skills/ulw-research/scripts/claim-kinds.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, test } from "bun:test"
+import { spawnSync } from "node:child_process"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { CLAIM_ATTRIBUTE, CLAIM_KINDS, CLAIM_TABLE_BEGIN, CLAIM_TABLE_END, renderClaimKindTable, unmarkedKinds } from "./claim-kinds.mjs"
+import { DEFECT_CODES } from "./contracts.mjs"
+import { valueChecks } from "./fidelity-values.mjs"
+import { buildContext } from "./gates-static.mjs"
+import { parseHtml } from "./html-lite.mjs"
+
+// Protects the claim-kind contract the writer (fill) and the gate share: a fact marked with a
+// claim kind must cite a row that kind accepts, a mark binds only the facts it owns, and the doc
+// table writers read is rendered from CLAIM_KINDS. Expectations come from ORACLE below, written by
+// hand from the design, never from the table under test.
+
+type Defect = { code: string; severity: string }
+type Row = Record<string, unknown> & { fact_id: string; kind: string; source_id: string | null; raw?: string; quote?: string }
+
+const FIX = join(import.meta.dir, "tests", "fixtures", "fidelity")
+const BASE: { rows: Row[] } = JSON.parse(readFileSync(join(FIX, "ledger-verify.json"), "utf8"))
+const byId = (id: string) => BASE.rows.find((row) => row.fact_id === id) as Row
+const [F1, F7, F8, Q1] = ["F1", "F7", "F8", "Q1"].map(byId) as [Row, Row, Row, Row]
+const plain = { render: null, operation: null, operands: [], derived_from: [], formula: null, factor: null }
+const F9: Row = { ...F8, ...plain, fact_id: "F9", kind: "assumed", label: "growth_rate", raw: "15%", value: "15", unit: "%", exact: { num: "15", den: "1" }, rationale: "planning assumption" }
+const F10: Row = { ...F8, ...plain, fact_id: "F10", kind: "derived", label: "share_sum", raw: "39%", value: "39", unit: "%", exact: { num: "39", den: "1" }, operation: "sum", operands: ["F5", "F6"] }
+const F11: Row = { ...F7, fact_id: "F11", locator: null }
+const F12: Row = { ...F7, fact_id: "F12", locator: { artifact: "missing.txt", char_start: 0, char_end: 9 } }
+const F13: Row = { ...F7, fact_id: "F13", locator: { artifact: "../S4/text.txt", char_start: 0, char_end: 9 } }
+const LEDGER = { ...BASE, rows: [...BASE.rows, F9, F10, F11, F12, F13] }
+const SUBJECTS = [F1, F7, F8, F9, F10, F11, F12, F13, Q1]
+
+/** Hand-written oracle: the ledger row kinds each claim kind accepts, and whether the cited row must be command-backed. */
+const ORACLE: Record<string, { rows: string[]; command: boolean }> = {
+	fact: { rows: ["measured", "converted", "derived"], command: false },
+	quote: { rows: ["quote"], command: false },
+	verified: { rows: ["measured", "quote"], command: true },
+	derived: { rows: ["derived", "converted"], command: false },
+	assumed: { rows: ["assumed"], command: false },
+}
+/** Rows an unmarked element refuses (an unmarked numeral reads as a fact, so an assumption needs its A mark). */
+const UNMARKED_REFUSED = new Set(["F9"])
+/** Rows whose own locator artifact sits in a snapshot whose meta.json kind is command (S5/text.txt). */
+const COMMAND_BACKED = new Set(["F7"])
+const MAJOR_FOR: Record<string, string> = { fact: "claim_kind_mismatch", quote: "claim_kind_mismatch", verified: "unsupported_verification", derived: "claim_kind_mismatch", assumed: "claim_kind_mismatch" }
+const expected = (kind: string, row: Row) => {
+	const rule = ORACLE[kind] as { rows: string[]; command: boolean }
+	return rule.rows.includes(row.kind) && (!rule.command || COMMAND_BACKED.has(row.fact_id)) ? [] : [MAJOR_FOR[kind] as string]
+}
+
+const CLAIM_CODES = new Set(["claim_kind_mismatch", "unsupported_verification", "verification_claim_unmarked"])
+const run = (body: string) => valueChecks(buildContext(parseHtml(`<h2>Findings</h2>\n${body}`), { baseDir: FIX }), LEDGER, null, join(FIX, "sources"), {}) as Defect[]
+const claims = (body: string) => run(body).filter((d) => CLAIM_CODES.has(d.code))
+const codes = (body: string) => claims(body).map((d) => d.code).sort()
+
+const value = (row: Row, kind?: string) => {
+	const mark = kind ? ` ${CLAIM_ATTRIBUTE}="${kind}"` : ""
+	return row.kind === "quote" ? `<q data-fact="${row.fact_id}"${mark} data-quote-sel="full">${row.quote}</q>` : `<data class="fact"${mark} data-fact="${row.fact_id}">${row.raw}</data>`
+}
+const prose = (inner: string, lead = "The figure is") => `<p>${lead} ${inner} [S4].</p>`
+const cell = (inner: string) => `<table><tr><th>Item</th><td>${inner}</td></tr></table>`
+
+describe("every claim kind against the hand-written oracle", () => {
+	for (const kind of Object.keys(ORACLE)) {
+		for (const row of SUBJECTS) {
+			const want = expected(kind, row)
+			const label = want.length === 0 ? "no claim defect" : `${want[0]} major`
+			test(`#given ${kind} marked on ${row.fact_id} (${row.kind}) in prose and in a table cell #then ${label}`, () => {
+				for (const body of [prose(value(row, kind)), cell(value(row, kind))]) {
+					expect(codes(body)).toEqual(want)
+					for (const defect of claims(body)) expect(defect.severity).toBe("major")
+				}
+			})
+			test(`#given ${kind} marked on an enclosing element over ${row.fact_id} #then the parent's mark binds it: ${label}`, () => {
+				expect(codes(`<p><span ${CLAIM_ATTRIBUTE}="${kind}">The figure is ${value(row)}</span> [S4].</p>`)).toEqual(want)
+			})
+			test(`#given ${kind} marked on ${row.fact_id} beside an unmarked command row #then the neighbour never satisfies it: ${label}`, () => {
+				expect(codes(prose(`${value(row, kind)}, and the suite reported ${value(F7)}`))).toEqual(want)
+			})
+			for (const inner of Object.keys(ORACLE).filter((other) => other !== kind)) {
+				test(`#given ${inner} nested inside ${kind} over ${row.fact_id} #then mismatch, the parent owns nothing, and the inner kind is still checked`, () => {
+					const body = `<p><span ${CLAIM_ATTRIBUTE}="${kind}">The figure is ${value(row, inner)}</span> [S4].</p>`
+					expect(codes(body)).toEqual(["claim_kind_mismatch", MAJOR_FOR[kind] as string, ...expected(inner, row)].sort())
+				})
+			}
+		}
+	}
+
+	for (const row of SUBJECTS) {
+		const refused = UNMARKED_REFUSED.has(row.fact_id) ? ["claim_kind_mismatch:major"] : []
+		const refusedLabel = refused.length ? "claim_kind_mismatch major" : "no claim code"
+		test(`#given ${row.fact_id} unmarked in a first-person run sentence #then the minor verification_claim_unmarked, plus ${refusedLabel}`, () => {
+			const found = claims(prose(value(row), "We ran the check and it reported"))
+			expect(found.map((d) => `${d.code}:${d.severity}`).sort()).toEqual([...refused, "verification_claim_unmarked:minor"].sort())
+		})
+		test(`#given ${row.fact_id} unmarked in a plain sentence in prose and in a table cell #then ${refusedLabel}`, () => {
+			for (const body of [prose(value(row)), cell(value(row))]) expect(claims(body).map((d) => `${d.code}:${d.severity}`)).toEqual(refused)
+		})
+	}
+
+	test("#given an unknown claim kind #then claim_kind_mismatch", () => {
+		expect(codes(prose(value(F1, "rumoured")))).toEqual(["claim_kind_mismatch"])
+	})
+
+	test("#given every defect and warning code the table names #then contracts defines it, and warnings are never major", () => {
+		for (const entry of Object.values(CLAIM_KINDS) as { defect: string; unmarked: { code: string } | null }[]) {
+			expect(DEFECT_CODES[entry.defect]).toBeDefined()
+			if (entry.unmarked) expect(DEFECT_CODES[entry.unmarked.code].severity).toBe("minor")
+		}
+	})
+})
+
+describe("design-check regressions", () => {
+	test("#given verified wrapping a fact-marked page row (F1 shadowing) #then the parent is unsupported and the nesting is a mismatch", () => {
+		expect(codes(`<p><span ${CLAIM_ATTRIBUTE}="verified">The inspection put the span at ${value(F1, "fact")}</span> [S4].</p>`)).toEqual(["claim_kind_mismatch", "unsupported_verification"])
+	})
+
+	test("#given one verified value and an unmarked value in the same run sentence (F2) #then the unmarked one still warns", () => {
+		expect(codes(prose(`${value(F7, "verified")}, and the span is ${value(F1)}`, "We ran the suite and it reported"))).toEqual(["verification_claim_unmarked"])
+	})
+
+	test("#given a truthful converted and derived value marked fact (F3) #then no stricter than unmarked", () => {
+		for (const row of [F8, F9, F10]) expect(codes(prose(value(row, "fact")))).toEqual(codes(prose(value(row))))
+		expect(codes(prose(value(F8, "fact")))).toEqual([])
+	})
+
+	test("#given the assumed row F9 unmarked or marked fact #then both refuse it, and the unmarked message names the A mark", () => {
+		expect(codes(prose(value(F9)))).toEqual(["claim_kind_mismatch"])
+		expect(codes(prose(value(F9, "fact")))).toEqual(["claim_kind_mismatch"])
+		expect(JSON.stringify(claims(prose(value(F9))))).toContain("{{A:F9}}")
+	})
+
+	test("#given the assumed row F9 marked {{A:F9}} (data-claim-kind=assumed) #then no claim defect", () => {
+		expect(codes(prose(value(F9, "assumed")))).toEqual([])
+		expect(codes(cell(value(F9, "assumed")))).toEqual([])
+	})
+
+	test("#given verified citing a command-sourced row with no, a missing, or an escaping locator artifact (F4) #then unsupported_verification", () => {
+		for (const row of [F11, F12, F13]) expect(codes(prose(value(row, "verified")))).toEqual(["unsupported_verification"])
+	})
+})
+
+describe("unmarked phrases", () => {
+	const fires = [
+		"We verified the span by running the measurement script.",
+		"We ran the suite twice.",
+		"We executed the export.",
+		"We verified by hand-counting the rows.",
+		"We have run the tests.",
+		"I ran the suite.",
+		"Our numbers were obtained by running the script.",
+		"우리가 실행해 확인한 길이",
+		"저희가 스크립트를 실행하여 검증한 값",
+		"저희가 테스트를 돌렸다",
+		"우리 팀이 벤치마크를 돌려 얻은 값",
+		"그래서 우리는 스크립트를 실행했다",
+		"직접 실행한 결과",
+	]
+	const quiet = [
+		"The tests showed a 12 % drop.",
+		"The bridge, which ran across the river, spans 320 m.",
+		"The span, as confirmed with the annual inspection report, is 320 m.",
+		"Clinical tests confirmed the diagnosis.",
+		"The authors obtained estimates by running simulations.",
+		"We ran out of time.",
+		"확인된 길이는 최대 320 m",
+		"개발자가 직접 실행한 결과를 보고했다",
+		"실행해 확인한 길이",
+		"우리나라에서 실행된 정책은 320개다",
+		"우리 정부가 실행한 예산",
+		"우리가 의뢰한 업체가 테스트를 돌렸다",
+		"우리는 결과를 확인했다",
+	]
+	for (const text of fires) test(`#given "${text}" #then verified`, () => expect(unmarkedKinds(text)).toEqual(["verified"]))
+	for (const text of quiet) test(`#given "${text}" #then nothing`, () => expect(unmarkedKinds(text)).toEqual([]))
+})
+
+describe("references/fidelity-claim-kinds.md is rendered from CLAIM_KINDS", () => {
+	const doc = readFileSync(join(import.meta.dir, "..", "references", "fidelity-claim-kinds.md"), "utf8")
+
+	test("the committed table section equals renderClaimKindTable() byte for byte", () => {
+		const [begin, end] = [doc.indexOf(CLAIM_TABLE_BEGIN), doc.indexOf(CLAIM_TABLE_END)]
+		expect(begin).toBeGreaterThanOrEqual(0)
+		expect(end).toBeGreaterThan(begin)
+		expect(doc.slice(begin + CLAIM_TABLE_BEGIN.length + 1, end)).toBe(renderClaimKindTable())
+	})
+
+	test("node claim-kinds.mjs --render-doc prints the same table", () => {
+		const result = spawnSync("node", [join(import.meta.dir, "claim-kinds.mjs"), "--render-doc"], { encoding: "utf8" })
+		expect(result.status).toBe(0)
+		expect(result.stdout).toBe(renderClaimKindTable())
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/claims-index.mjs

@@ -0,0 +1,125 @@
+// claims-index.mjs - deterministic index of claim-graph.md: the one Markdown table whose header
+// names claim_id, statement, risk tier, and status, plus the ids listed under the
+// `## verified-claims` digest. Pure function of the text; node: builtins only.
+
+const CLAIM_ID = /^C\d+$/
+const REQUIRED_COLUMNS = Object.freeze({ claim_id: "claim_id", statement: "statement", risk: "risk tier", status: "status" })
+
+/** Split one table line on unescaped pipes; drops the leading and trailing border cells. */
+function splitRow(line) {
+	const cells = []
+	let current = ""
+	for (let index = 0; index < line.length; index += 1) {
+		const char = line[index]
+		if (char === "\\" && line[index + 1] === "|") {
+			current += "|"
+			index += 1
+		} else if (char === "|") {
+			cells.push(current)
+			current = ""
+		} else current += char
+	}
+	cells.push(current)
+	const trimmed = cells.map((value) => value.trim())
+	if (line.trim().startsWith("|")) trimmed.shift()
+	if (line.trim().endsWith("|")) trimmed.pop()
+	return trimmed
+}
+
+function normalizeHeader(value) {
+	return value.replace(/`/g, "").trim().toLowerCase().replace(/[\s_-]+/g, " ")
+}
+
+function columnIndexes(header) {
+	const names = header.map(normalizeHeader)
+	const indexes = {}
+	for (const [key, name] of Object.entries(REQUIRED_COLUMNS)) indexes[key] = names.indexOf(normalizeHeader(name))
+	return Object.values(indexes).every((index) => index >= 0) ? indexes : null
+}
+
+function isSeparator(line) {
+	return /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$/.test(line)
+}
+
+const DIGEST_HEADING = normalizeHeader("verified-claims")
+
+/** `offset` is the index of `lines[0]` in the document, for line numbers in errors. */
+function verifiedIds(lines, offset, errors) {
+	const ids = []
+	let inside = false
+	for (const [index, line] of lines.entries()) {
+		const heading = /^(#{1,6})\s+(.*)$/.exec(line)
+		if (heading) {
+			const name = normalizeHeader(heading[2])
+			inside = name === DIGEST_HEADING
+			if (!inside && name.startsWith(DIGEST_HEADING)) {
+				errors.push(`line ${offset + index + 1}: heading "${line.trim()}" is not the digest heading "## verified-claims"; drop the suffix so its entries are read`)
+			}
+			continue
+		}
+		if (!inside) continue
+		// An entry is a list item or a table row; prose lines never verify. Only the id an entry
+		// starts with is verified; ids mentioned later in the line are not.
+		const leading = /^\s*(?:(?:[-*+]|\d+[.)])\s+|\|\s*)`?(C\d+)\b/.exec(line)
+		if (leading && !ids.includes(leading[1])) ids.push(leading[1])
+	}
+	return ids
+}
+
+/** Blank every line of a fenced code block (``` or ~~~, fences included) so nothing in it is read. */
+function unfenced(lines) {
+	let fence = null
+	return lines.map((line) => {
+		const marker = /^\s{0,3}(`{3,}|~{3,})/.exec(line)
+		if (fence === null) {
+			if (marker) fence = marker[1]
+			return marker ? "" : line
+		}
+		const closes = marker && marker[1][0] === fence[0] && marker[1].length >= fence.length && line.trim() === marker[1]
+		if (closes) fence = null
+		return ""
+	})
+}
+
+/** @returns {{ claims: { claim_id: string, statement: string, risk: string, status: string, in_verified: boolean }[], errors: string[] }} */
+export function indexClaims(markdown) {
+	const lines = unfenced(markdown.split(/\r?\n/))
+	const errors = []
+	const headerAt = lines.findIndex((line) => line.trim().startsWith("|") && columnIndexes(splitRow(line)) !== null)
+	if (headerAt < 0) {
+		return { claims: [], errors: ["no claim table: a Markdown table with claim_id, statement, risk tier, and status columns is required"] }
+	}
+	const header = splitRow(lines[headerAt])
+	const columns = columnIndexes(header)
+	const hasSeparator = isSeparator(lines[headerAt + 1] ?? "")
+	if (!hasSeparator) errors.push(`line ${headerAt + 2}: claim table header must be followed by a separator row`)
+	const firstRow = headerAt + (hasSeparator ? 2 : 1)
+	const rows = []
+	let tableEnd = firstRow
+	for (let index = firstRow; index < lines.length && lines[index].trim().startsWith("|"); index += 1) {
+		tableEnd = index + 1
+		const cells = splitRow(lines[index])
+		const at = `line ${index + 1}`
+		if (cells.length !== header.length) {
+			errors.push(`${at}: expected ${header.length} cells, found ${cells.length}`)
+			continue
+		}
+		const claimId = cells[columns.claim_id].replace(/`/g, "")
+		if (!CLAIM_ID.test(claimId)) {
+			errors.push(`${at}: claim_id "${claimId}" must match C<n>`)
+			continue
+		}
+		if (rows.some((row) => row.claim_id === claimId)) {
+			errors.push(`${at}: duplicate claim_id ${claimId}`)
+			continue
+		}
+		rows.push({ claim_id: claimId, statement: cells[columns.statement], risk: cells[columns.risk], status: cells[columns.status] })
+	}
+	// The digest section ends at the claim table: scan each side on its own so it cannot carry across.
+	const verified = [...new Set([...verifiedIds(lines.slice(0, headerAt), 0, errors), ...verifiedIds(lines.slice(tableEnd), tableEnd, errors)])]
+	for (const id of verified) {
+		if (!rows.some((row) => row.claim_id === id)) errors.push(`verified-claims lists ${id}, which has no claim row`)
+	}
+	const claims = rows.map((row) => ({ ...row, in_verified: verified.includes(row.claim_id) }))
+	return { claims, errors }
+}

package/packages/shared-skills/skills/ulw-research/scripts/claims-index.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { indexClaims } from "./claims-index.mjs"
+
+const FIXTURE = join(import.meta.dir, "tests", "fixtures", "fidelity", "claim-graph.md")
+
+describe("indexClaims", () => {
+	test("indexes the fixture claim graph", () => {
+		const { claims, errors } = indexClaims(readFileSync(FIXTURE, "utf8"))
+		expect(errors).toEqual([])
+		expect(claims.map((claim: { claim_id: string; in_verified: boolean }) => claim.claim_id)).toEqual(["C1", "C2", "C3"])
+		expect(claims.filter((claim: { claim_id: string; in_verified: boolean }) => claim.in_verified).map((claim: { claim_id: string; in_verified: boolean }) => claim.claim_id)).toEqual(["C1"])
+		expect(claims[0]).toEqual({
+			claim_id: "C1",
+			statement: "The bridge span is up to 320 m.",
+			risk: "high",
+			status: "supported",
+			in_verified: true,
+		})
+		expect(claims[2].status).toBe("refuted")
+	})
+
+	test("a malformed table returns errors", () => {
+		const bad = [
+			"| claim_id | statement | risk tier | status |",
+			"|---|---|---|---|",
+			"| X1 | bad id | high | supported |",
+			"| C2 | too few cells |",
+		].join("\n")
+		const { errors } = indexClaims(bad)
+		expect(errors.length).toBeGreaterThanOrEqual(2)
+	})
+
+	test("fenced code blocks are skipped: a fenced heading does not end the digest and a fenced entry does not verify", () => {
+		const text = [
+			"| claim_id | statement | risk tier | status |",
+			"|---|---|---|---|",
+			"| C1 | one | high | supported |",
+			"| C2 | two | low | supported |",
+			"",
+			"## verified-claims",
+			"```",
+			"# not a heading",
+			"- C2",
+			"```",
+			"- C1",
+		].join("\n")
+		const { claims, errors } = indexClaims(text)
+		expect(errors).toEqual([])
+		expect(claims.map((claim: { in_verified: boolean }) => claim.in_verified)).toEqual([true, false])
+	})
+
+	test("a document without the claim table returns an error", () => {
+		const { claims, errors } = indexClaims("# claim graph\n\nno table here\n")
+		expect(claims).toEqual([])
+		expect(errors.length).toBe(1)
+	})
+
+	test("a verified id with no claim row is an error", () => {
+		const text = "## verified-claims\n\n- C9\n\n| claim_id | statement | risk tier | status |\n|---|---|---|---|\n| C1 | a | high | supported |\n"
+		expect(indexClaims(text).errors.some((e: string) => e.includes("C9"))).toBe(true)
+	})
+
+	test("only the leading claim id of a verified entry is verified", () => {
+		const text = [
+			"## verified-claims",
+			"",
+			"- C1 (merged from C2)",
+			"",
+			"| claim_id | statement | risk tier | status |",
+			"|---|---|---|---|",
+			"| C1 | a, see C2 | high | supported |",
+			"| C2 | b | high | unresolved |",
+		].join("\n")
+		const { claims, errors } = indexClaims(text)
+		expect(errors).toEqual([])
+		expect(claims.map((claim: { claim_id: string; in_verified: boolean }) => [claim.claim_id, claim.in_verified])).toEqual([
+			["C1", true],
+			["C2", false],
+		])
+	})
+
+	test("a verified-claims line verifies only as a list item or a table row, never as prose", () => {
+		const text = [
+			"## verified-claims",
+			"",
+			"- C1",
+			"C2 is pending review",
+			"1) C3",
+			"| C4 | merged |",
+			"",
+			"| claim_id | statement | risk tier | status |",
+			"|---|---|---|---|",
+			"| C1 | a | high | supported |",
+			"| C2 | b | high | unresolved |",
+			"| C3 | c | high | supported |",
+			"| C4 | d | high | supported |",
+		].join("\n")
+		const { claims, errors } = indexClaims(text)
+		expect(errors).toEqual([])
+		expect(claims.map((claim: { claim_id: string; in_verified: boolean }) => [claim.claim_id, claim.in_verified])).toEqual([
+			["C1", true],
+			["C2", false],
+			["C3", true],
+			["C4", true],
+		])
+	})
+
+	test("the SKILL.md synthesis heading 'Verified claims' is recognized", () => {
+		const text = "## Verified claims\n\n- C1\n\n| claim_id | statement | risk tier | status |\n|---|---|---|---|\n| C1 | a | high | supported |\n"
+		expect(indexClaims(text).claims[0].in_verified).toBe(true)
+	})
+
+	test("a digest heading with a suffix is an error naming the heading, not a silently empty digest", () => {
+		const text = "## Verified claims (2)\n\n- C1\n\n| claim_id | statement | risk tier | status |\n|---|---|---|---|\n| C1 | a | high | supported |\n"
+		const { claims, errors } = indexClaims(text)
+		expect(claims[0].in_verified).toBe(false)
+		expect(errors.some((e: string) => e.startsWith("line 1:") && e.includes('"## Verified claims (2)"'))).toBe(true)
+	})
+
+	test("the verified-claims section ends at the claim table", () => {
+		const text = [
+			"## verified-claims",
+			"- C1",
+			"",
+			"| claim_id | statement | risk tier | status |",
+			"|---|---|---|---|",
+			"| C1 | a | high | supported |",
+			"| C2 | b | high | unresolved |",
+			"",
+			"C2 still pending",
+		].join("\n")
+		const { claims, errors } = indexClaims(text)
+		expect(errors).toEqual([])
+		expect(claims.map((claim: { claim_id: string; in_verified: boolean }) => [claim.claim_id, claim.in_verified])).toEqual([
+			["C1", true],
+			["C2", false],
+		])
+	})
+
+	test("a GFM two-dash separator row is accepted and the first data row is read", () => {
+		const text = "| claim_id | statement | risk tier | status |\n|--|--|--|--|\n| C1 | a | high | supported |\n| C2 | b | normal | unresolved |\n"
+		const { claims, errors } = indexClaims(text)
+		expect(errors).toEqual([])
+		expect(claims.map((claim: { claim_id: string }) => claim.claim_id)).toEqual(["C1", "C2"])
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/cli-support.mjs

@@ -1,7 +1,8 @@
 // cli-support.mjs - argument parsing, typed usage errors, exit-code mapping, and JSON file IO
 // shared by every report-tools subcommand. node: builtins only.
 
-import { readFileSync, renameSync, writeFileSync } from "node:fs"
+import { createHash } from "node:crypto"
+import { readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
 import { basename, dirname, join } from "node:path"
 
 /** A usage or input error: always exit code 2. */
@@ -87,11 +88,24 @@ export function readJsonFile(path) {
 	}
 }
 
-/** Write JSON through a sibling temp file + rename, so a crash never leaves a half-written file. */
-export function writeJsonAtomic(path, value) {
+/** The sha256 hex digest of a string or bytes: the one hash every record and receipt carries. */
+export const sha256Of = (content) => createHash("sha256").update(content).digest("hex")
+
+/** Write text through a sibling temp file + rename; a failed write removes the temp file. */
+export function writeTextAtomic(path, text) {
 	const temp = join(dirname(path), `.${basename(path)}.${process.pid}.${Date.now()}.tmp`)
-	writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`)
-	renameSync(temp, path)
+	try {
+		writeFileSync(temp, text)
+		renameSync(temp, path)
+	} catch (error) {
+		rmSync(temp, { force: true })
+		throw error
+	}
+}
+
+/** Write JSON through writeTextAtomic, so a crash never leaves a half-written file. */
+export function writeJsonAtomic(path, value) {
+	writeTextAtomic(path, `${JSON.stringify(value, null, 2)}\n`)
 }
 
 /** Print a result: JSON on stdout, one summary line on stderr. */

package/packages/shared-skills/skills/ulw-research/scripts/cli-support.test.ts

@@ -1,10 +1,10 @@
 import { describe, expect, onTestFinished, test } from "bun:test"
-import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { pathToFileURL } from "node:url"
 
-import { CliError, exitCodeFor, parseArgs, readJsonFile, writeJsonAtomic } from "./cli-support.mjs"
+import { CliError, exitCodeFor, parseArgs, readJsonFile, writeJsonAtomic, writeTextAtomic } from "./cli-support.mjs"
 import { isCliEntry } from "./entry-guard.mjs"
 
 function tempDir() {
@@ -65,6 +65,17 @@ describe("JSON files", () => {
 		expect(leftovers).toEqual([])
 	})
 
+	test("#given a target the rename cannot replace #when written atomically #then the write throws and no temp file is left", () => {
+		// given: a non-empty directory where the file should go
+		const dir = tempDir()
+		const target = join(dir, "calibration.jsonl")
+		mkdirSync(target)
+		writeFileSync(join(target, "keep"), "x")
+		// when / then
+		expect(() => writeTextAtomic(target, "line\n")).toThrow()
+		expect(readdirSync(dir)).toEqual(["calibration.jsonl"])
+	})
+
 	test("#given a missing or malformed file #when read #then a CliError names the path", () => {
 		const dir = tempDir()
 		expect(() => readJsonFile(join(dir, "missing.json"))).toThrow(CliError)