lazycodex-ai 5.1.44 → 5.1.45

package/packages/shared-skills/skills/ulw-research/scripts/fact-ledger.test.ts

@@ -0,0 +1,252 @@
+import { describe, expect, onTestFinished, test } from "bun:test"
+import { mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import {
+	LEDGER_FILENAME,
+	LEDGER_SCHEMA_VERSION,
+	addRow,
+	emptyLedger,
+	nextId,
+	readLedger,
+	renderLedgerMarkdown,
+	retractRow,
+	supersedeRow,
+	validateLedger,
+	writeLedger,
+} from "./fact-ledger.mjs"
+
+const HASH = "a".repeat(64)
+
+function tempDir(): string {
+	const dir = mkdtempSync(join(tmpdir(), "ulw-ledger-"))
+	onTestFinished(() => rmSync(dir, { recursive: true, force: true }))
+	return dir
+}
+
+function measured(label: string, value = "320") {
+	return {
+		kind: "measured",
+		value,
+		unit: "m",
+		raw: `${value} m`,
+		quote: `The span is ${value} m.`,
+		value_span: [12, 12 + value.length],
+		source_id: "S1",
+		locator: { artifact: "sources/S1/text.txt", line: 3, char_start: 40, char_end: 62 },
+		snapshot_sha256: HASH,
+		extracted_by: "fact add --find",
+		observed_at: "2026-10-23T08:00:00Z",
+		label,
+	}
+}
+
+function quoteRow(label: string) {
+	return { ...measured(label), kind: "quote", value: null, unit: null, value_span: null }
+}
+
+function ledgerWith(...rows: object[]) {
+	const ledger = emptyLedger()
+	for (const row of rows) addRow(ledger, row)
+	return ledger
+}
+
+describe("validateLedger", () => {
+	test("accepts a ledger built by addRow", () => {
+		expect(validateLedger(ledgerWith(measured("span"), quoteRow("claim")))).toEqual([])
+	})
+
+	test("rejects a row missing label", () => {
+		const ledger = ledgerWith(measured("span"))
+		delete (ledger.rows[0] as Record<string, unknown>).label
+		expect(validateLedger(ledger).some((e: string) => e.includes("label"))).toBe(true)
+	})
+
+	test("rejects a duplicate label", () => {
+		const ledger = ledgerWith(measured("span"))
+		ledger.rows.push({ ...ledger.rows[0], fact_id: "F2" })
+		expect(validateLedger(ledger).some((e: string) => e.includes("duplicate label"))).toBe(true)
+	})
+
+	test("rejects an assumed row without rationale", () => {
+		const ledger = ledgerWith(measured("span"))
+		ledger.rows[0].kind = "assumed"
+		expect(validateLedger(ledger).some((e: string) => e.includes("rationale"))).toBe(true)
+	})
+
+	test("rejects a value row with a non-decimal value", () => {
+		const ledger = ledgerWith(measured("span"))
+		ledger.rows[0].value = "320m"
+		expect(validateLedger(ledger).some((e: string) => e.includes("value"))).toBe(true)
+	})
+
+	test("rejects an exact with a non-string num", () => {
+		const ledger = ledgerWith(measured("span"))
+		ledger.rows[0].exact = { num: 1, den: "3" }
+		expect(validateLedger(ledger).some((e: string) => e.includes("exact"))).toBe(true)
+	})
+
+	test("rejects operands and derived_from ids with no ledger row", () => {
+		const ledger = ledgerWith(measured("span"))
+		ledger.rows.push({ ...ledger.rows[0], fact_id: "F2", kind: "derived", label: "ratio", operation: "ratio", operands: ["F9"], derived_from: ["F1", "Q7"] })
+		const errors = validateLedger(ledger)
+		expect(errors.some((e: string) => e.includes("operands") && e.includes("F9"))).toBe(true)
+		expect(errors.some((e: string) => e.includes("derived_from") && e.includes("Q7"))).toBe(true)
+		expect(errors.some((e: string) => e.includes("F1"))).toBe(false)
+	})
+
+	test("a bare row with only fact_id returns at least three errors", () => {
+		expect(validateLedger({ rows: [{ fact_id: "F1" }] }).length).toBeGreaterThanOrEqual(3)
+	})
+})
+
+describe("ids and status", () => {
+	test("nextId sequences F1, F2 then Q1, and a derived row gets F3", () => {
+		const ledger = emptyLedger()
+		expect(addRow(ledger, measured("a")).fact_id).toBe("F1")
+		expect(addRow(ledger, measured("b")).fact_id).toBe("F2")
+		expect(addRow(ledger, quoteRow("c")).fact_id).toBe("Q1")
+		expect(nextId(ledger, "derived")).toBe("F3")
+		const derived = addRow(ledger, {
+			kind: "derived",
+			value: "0.333",
+			unit: null,
+			raw: "0.333",
+			quote: "",
+			extracted_by: "fact derive",
+			observed_at: "2026-10-23T08:00:00Z",
+			label: "ratio",
+			operation: "ratio",
+			operands: ["F1", "F2"],
+			derived_from: ["F1", "F2"],
+			exact: { num: "1", den: "3" },
+		})
+		expect(derived.fact_id).toBe("F3")
+		expect(nextId(ledger, "quote")).toBe("Q2")
+	})
+
+	test("measured rows store exact from their decimal", () => {
+		const ledger = ledgerWith(measured("span", "12.50"))
+		expect(ledger.rows[0].exact).toEqual({ num: "25", den: "2" })
+	})
+
+	test("retractRow keeps the row with status retracted", () => {
+		const ledger = ledgerWith(measured("a"), measured("b"))
+		retractRow(ledger, "F1", "wrong page")
+		expect(ledger.rows).toHaveLength(2)
+		expect(ledger.rows[0].status).toBe("retracted")
+		expect(ledger.events[0]).toMatchObject({ fact_id: "F1", to: "retracted", reason: "wrong page" })
+		expect(validateLedger(ledger)).toEqual([])
+		expect(() => retractRow(ledger, "F9", "x")).toThrow()
+	})
+
+	test("supersedeRow points at the replacement", () => {
+		const ledger = ledgerWith(measured("a"), measured("b"))
+		supersedeRow(ledger, "F1", "F2", "newer filing")
+		expect(ledger.rows[0].status).toBe("superseded")
+		expect(ledger.events[0]).toMatchObject({ fact_id: "F1", replacement: "F2" })
+		expect(validateLedger(ledger)).toEqual([])
+	})
+
+	test("supersedeRow refuses a replacement that is not active", () => {
+		const ledger = ledgerWith(measured("a"), measured("b"))
+		retractRow(ledger, "F2", "wrong page")
+		expect(() => supersedeRow(ledger, "F1", "F2", "newer filing")).toThrow(/F2 is retracted/)
+		expect(ledger.rows[0].status).toBe("active")
+		expect(ledger.events).toHaveLength(1)
+	})
+
+	test("supersedeRow without a replacement throws and points at retract", () => {
+		const ledger = ledgerWith(measured("a"))
+		expect(() => supersedeRow(ledger, "F1", null, "newer filing")).toThrow(/supersede F1 needs a replacement row; use retract/)
+		expect(ledger.rows[0].status).toBe("active")
+		expect(ledger.events).toHaveLength(0)
+	})
+})
+
+describe("read and write", () => {
+	test("write then read round-trips byte-identically", () => {
+		const dir = tempDir()
+		const ledger = ledgerWith(measured("span"), quoteRow("claim"))
+		writeLedger(dir, ledger)
+		const first = readFileSync(join(dir, LEDGER_FILENAME), "utf8")
+		const loaded = readLedger(dir)
+		expect(loaded).toEqual(ledger)
+		writeLedger(dir, loaded)
+		expect(readFileSync(join(dir, LEDGER_FILENAME), "utf8")).toBe(first)
+		expect(readdirSync(dir)).toEqual([LEDGER_FILENAME])
+		expect(loaded.schemaVersion).toBe(LEDGER_SCHEMA_VERSION)
+	})
+
+	test("a derived row with an exact rational round-trips and validates", () => {
+		const dir = tempDir()
+		const ledger = ledgerWith(measured("a"), measured("b"))
+		addRow(ledger, {
+			kind: "derived",
+			value: "0.333",
+			raw: "0.333",
+			quote: "",
+			extracted_by: "fact derive",
+			observed_at: "2026-10-23T08:00:00Z",
+			label: "third",
+			operation: "ratio",
+			operands: ["F1", "F2"],
+			derived_from: ["F1", "F2"],
+			exact: { num: "1", den: "3" },
+		})
+		writeLedger(dir, ledger)
+		const loaded = readLedger(dir)
+		expect(loaded.rows[2].exact).toEqual({ num: "1", den: "3" })
+		expect(loaded.rows[2].value).toBe("0.333")
+		expect(validateLedger(loaded)).toEqual([])
+	})
+
+	test("readLedger of a missing file is an empty ledger; writeLedger refuses an invalid one", () => {
+		const dir = tempDir()
+		expect(readLedger(dir)).toEqual(emptyLedger())
+		const ledger = ledgerWith(measured("a"))
+		ledger.rows[0].value = "abc"
+		expect(() => writeLedger(dir, ledger)).toThrow()
+		expect(readdirSync(dir)).toEqual([])
+	})
+
+	test("renderLedgerMarkdown lists every row", () => {
+		const text = renderLedgerMarkdown(ledgerWith(measured("span"), quoteRow("claim")))
+		expect(text).toContain("| F1 | measured | span |")
+		expect(text).toContain("| Q1 | quote | claim |")
+	})
+})
+
+describe("validateLedger checks events against rows", () => {
+	test("a retracted event that carries a replacement is an error", () => {
+		const ledger = ledgerWith(measured("a"), measured("b"))
+		retractRow(ledger, "F1", "wrong page")
+		ledger.events[0].replacement = "F2"
+		expect(validateLedger(ledger).some((e: string) => /F1 is retracted but names replacement F2/.test(e))).toBe(true)
+	})
+
+	test("the last event for a fact must match its row status", () => {
+		const ledger = ledgerWith(measured("a"), measured("b"))
+		retractRow(ledger, "F1", "wrong page")
+		ledger.rows[0].status = "active"
+		expect(validateLedger(ledger).some((e: string) => /F1 has status active but its last event moves it to retracted/.test(e))).toBe(true)
+	})
+
+	test("a non-active row with no event is an error", () => {
+		const ledger = ledgerWith(measured("a"))
+		ledger.rows[0].status = "superseded"
+		expect(validateLedger(ledger).some((e: string) => /F1 is superseded but has no status event/.test(e))).toBe(true)
+	})
+
+	test("an event with an invalid from or to status is an error naming the fact", () => {
+		const ledger = ledgerWith(measured("a"))
+		retractRow(ledger, "F1", "wrong page")
+		ledger.events[0].from = "gone"
+		const errors = validateLedger(ledger)
+		expect(errors.some((e: string) => /events\[0\]: F1 is active, but the event moves it from gone/.test(e))).toBe(true)
+		ledger.events[0].from = "active"
+		ledger.events[0].to = "active"
+		expect(validateLedger(ledger).some((e: string) => /events\[0\]: F1 cannot move from active to active/.test(e))).toBe(true)
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/fidelity-brief.mjs

@@ -0,0 +1,145 @@
+// fidelity-brief.mjs - parse the `## Fidelity` block of brief.md and decide whether it is locked.
+//
+// Grammar (fable-interview.md section 3, "Parser contract"): the block starts at a line
+// `## Fidelity` and ends at the next `## ` heading. It holds the seven field lines below, in any
+// order, each `<field>: <value> (answered_by: user|default|request|pending)`, plus an optional
+// `asked: <field>, <field>` history line. Values carry no parentheses, and `answered_by: pending`
+// is legal only with the value `pending`. Trailing whitespace on a line is ignored; a second
+// `## Fidelity` block is a parse error. This module parses; it never interprets a value, which
+// is each consumer's job. Plain Node ESM, node: builtins only.
+
+import { readFileSync } from "node:fs"
+
+export const FIDELITY_FIELDS = Object.freeze([
+	"as of",
+	"meaning check",
+	"source floor",
+	"derived numbers",
+	"languages",
+	"identifier classes",
+	"fallback",
+])
+export const FIDELITY_ANSWERED_BY = Object.freeze(["user", "default", "request", "pending"])
+const LOCKED_ANSWERED_BY = new Set(["user", "default", "request"])
+
+export const FIDELITY_INCOMPLETE = "fidelity_interview_incomplete"
+const INCOMPLETE_HINT =
+	"A fidelity field is pending or missing in brief.md; answer the open question or record its default, then rerun."
+
+const BLOCK_HEADING = /^## Fidelity\s*$/
+const NEXT_HEADING = /^## /
+const FIELD_LINE = /^([a-z][a-z ]*[a-z]): ([^()]+) \(answered_by: (user|default|request|pending)\)$/
+const ASKED_LINE = /^asked:(.*)$/
+
+function blockLines(markdown) {
+	const lines = String(markdown)
+		.split(/\r?\n/)
+		.map((line) => line.trimEnd())
+	const headings = lines.flatMap((line, index) => (BLOCK_HEADING.test(line) ? [index] : []))
+	if (headings.length === 0) return null
+	const [start, ...duplicates] = headings
+	const body = []
+	for (let index = start + 1; index < lines.length; index += 1) {
+		if (NEXT_HEADING.test(lines[index])) break
+		body.push({ text: lines[index], line: index + 1 })
+	}
+	return { body, duplicates: duplicates.map((index) => index + 1) }
+}
+
+function parseAsked(rest, line, text, errors) {
+	const names = rest
+		.split(",")
+		.map((name) => name.trim())
+		.filter(Boolean)
+	const unknown = names.filter((name) => !FIDELITY_FIELDS.includes(name))
+	if (unknown.length > 0) {
+		errors.push(`line ${line}: malformed asked line, unknown field ${unknown.join(", ")}: ${text}`)
+		return []
+	}
+	return names
+}
+
+function parseFieldLine({ text, line }, parsed, errors) {
+	const match = FIELD_LINE.exec(text)
+	if (!match) return errors.push(`line ${line}: malformed fidelity line: ${text}`)
+	const [, field, rawValue, answeredBy] = match
+	const value = rawValue.trim()
+	if (!FIDELITY_FIELDS.includes(field)) return errors.push(`line ${line}: malformed fidelity line, unknown field "${field}": ${text}`)
+	if (Object.hasOwn(parsed.fields, field)) return errors.push(`line ${line}: malformed fidelity line, duplicate field "${field}": ${text}`)
+	if ((answeredBy === "pending") !== (value === "pending")) {
+		return errors.push(`line ${line}: malformed fidelity line, value pending and answered_by: pending go together: ${text}`)
+	}
+	parsed.fields[field] = value
+	parsed.answered_by[field] = answeredBy
+}
+
+/**
+ * @param {string} briefMd the whole brief.md text
+ * @returns {{ present: boolean, fields: Record<string, string>, answered_by: Record<string, string>,
+ *   asked: string[], missing: string[], pending: string[], errors: string[] }}
+ */
+export function parseFidelityBlock(briefMd) {
+	const parsed = { present: false, fields: {}, answered_by: {}, asked: [], missing: [], pending: [], errors: [] }
+	const block = blockLines(briefMd)
+	if (block !== null) {
+		const { body, duplicates } = block
+		parsed.present = true
+		for (const line of duplicates) parsed.errors.push(`line ${line}: duplicate ## Fidelity block, only one is allowed`)
+		let sawAsked = false
+		for (const entry of body) {
+			if (entry.text.trim() === "") continue
+			const asked = ASKED_LINE.exec(entry.text)
+			if (!asked) {
+				parseFieldLine(entry, parsed, parsed.errors)
+				continue
+			}
+			if (sawAsked) parsed.errors.push(`line ${entry.line}: malformed asked line, duplicate: ${entry.text}`)
+			else parsed.asked = parseAsked(asked[1], entry.line, entry.text, parsed.errors)
+			sawAsked = true
+		}
+	}
+	parsed.missing = FIDELITY_FIELDS.filter((field) => !Object.hasOwn(parsed.fields, field))
+	parsed.pending = FIDELITY_FIELDS.filter((field) => parsed.answered_by[field] === "pending")
+	return parsed
+}
+
+/** Locked = no parse error and all seven fields present with answered_by user, default, or request. */
+export function isLocked(parsed) {
+	if (!parsed || parsed.errors.length > 0) return false
+	return FIDELITY_FIELDS.every((field) => Object.hasOwn(parsed.fields, field) && LOCKED_ANSWERED_BY.has(parsed.answered_by[field]))
+}
+
+function incompleteDefect(briefPath, parsed) {
+	const reasons = []
+	if (!parsed.present) reasons.push("no ## Fidelity block")
+	else if (parsed.missing.length > 0) reasons.push(`missing: ${parsed.missing.join(", ")}`)
+	if (parsed.pending.length > 0) reasons.push(`pending: ${parsed.pending.join(", ")}`)
+	return {
+		code: FIDELITY_INCOMPLETE,
+		severity: "blocker",
+		integrity: true,
+		selector: null,
+		line: null,
+		message: `${briefPath}: fidelity interview incomplete (${reasons.join("; ")})`,
+		hint: INCOMPLETE_HINT,
+	}
+}
+
+/**
+ * The lock check the reader-facing CLI stages run before writing anything.
+ * exitCode 0 = locked; 1 = pending, missing, or no brief (one `fidelity_interview_incomplete`
+ * defect); 2 = malformed block (usage error, `errors` name the lines, no defect).
+ * @param {string} briefPath
+ */
+export function requireLockedBrief(briefPath) {
+	let markdown = ""
+	try {
+		markdown = readFileSync(briefPath, "utf8")
+	} catch (error) {
+		if (error?.code !== "ENOENT") throw error
+	}
+	const parsed = parseFidelityBlock(markdown)
+	if (parsed.errors.length > 0) return { locked: false, exitCode: 2, defects: [], errors: parsed.errors, parsed }
+	if (isLocked(parsed)) return { locked: true, exitCode: 0, defects: [], errors: [], parsed }
+	return { locked: false, exitCode: 1, defects: [incompleteDefect(briefPath, parsed)], errors: [], parsed }
+}

package/packages/shared-skills/skills/ulw-research/scripts/fidelity-brief.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, test } from "bun:test"
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { FIDELITY_FIELDS, isLocked, parseFidelityBlock, requireLockedBrief } from "./fidelity-brief.mjs"
+
+const fixture = (name: string) => join(import.meta.dir, "tests", "fixtures", name)
+const lockedMd = await Bun.file(fixture("fidelity-brief-locked.md")).text()
+const pendingMd = await Bun.file(fixture("fidelity-brief-pending.md")).text()
+
+function withoutLine(markdown: string, prefix: string): string {
+	return markdown
+		.split("\n")
+		.filter((line) => !line.startsWith(prefix))
+		.join("\n")
+}
+
+describe("parseFidelityBlock", () => {
+	test("#given a complete block #when parsed #then seven fields are read and the brief is locked", () => {
+		// when
+		const parsed = parseFidelityBlock(lockedMd)
+		// then
+		expect(parsed.errors).toEqual([])
+		expect(Object.keys(parsed.fields).sort()).toEqual([...FIDELITY_FIELDS].sort())
+		expect(parsed.fields["as of"]).toBe("latest at run start, 2026-10-23")
+		expect(parsed.fields.languages).toBe("report ko; sources ko, en; quotes original with translation beside")
+		expect(parsed.answered_by["derived numbers"]).toBe("user")
+		expect(parsed.answered_by.fallback).toBe("request")
+		expect(parsed.asked).toEqual(["derived numbers"])
+		expect(isLocked(parsed)).toBe(true)
+	})
+
+	test("#given a block missing as of #when parsed #then it is not locked and the missing field is named", () => {
+		// when
+		const parsed = parseFidelityBlock(withoutLine(lockedMd, "as of:"))
+		// then
+		expect(isLocked(parsed)).toBe(false)
+		expect(parsed.missing).toEqual(["as of"])
+		expect(parsed.errors).toEqual([])
+	})
+
+	test("#given a field answered_by pending #when parsed #then it is not locked and not malformed", () => {
+		// when
+		const parsed = parseFidelityBlock(pendingMd)
+		// then
+		expect(parsed.errors).toEqual([])
+		expect(parsed.answered_by["derived numbers"]).toBe("pending")
+		expect(parsed.pending).toEqual(["derived numbers"])
+		expect(isLocked(parsed)).toBe(false)
+	})
+
+	test("#given a malformed field line #when parsed #then errors name the line as malformed", () => {
+		// given
+		const markdown = lockedMd.replace("meaning check: on (answered_by: default)", "meaning check: on")
+		// when
+		const parsed = parseFidelityBlock(markdown)
+		// then
+		expect(parsed.errors.length).toBe(1)
+		expect(parsed.errors[0]).toContain("malformed")
+		expect(parsed.errors[0]).toContain("meaning check: on")
+		expect(isLocked(parsed)).toBe(false)
+	})
+
+	test("#given grammar violations #when parsed #then each is a malformed error", () => {
+		const cases = [
+			lockedMd.replace("fallback: block-quote (answered_by: request)", "fallback: block-quote (answered_by: someone)"),
+			lockedMd.replace("meaning check: on (answered_by: default)", "meaning check: on (maybe) (answered_by: default)"),
+			lockedMd.replace("meaning check: on (answered_by: default)", "meaning check: on (answered_by: pending)"),
+			lockedMd.replace("asked: derived numbers", "asked: derived numbers\ntone: formal (answered_by: user)"),
+			lockedMd.replace("asked: derived numbers", "asked: derived numbers\nfallback: omit (answered_by: user)"),
+			lockedMd.replace("asked: derived numbers", "asked: tone"),
+		]
+		for (const markdown of cases) expect(parseFidelityBlock(markdown).errors.length).toBe(1)
+	})
+
+	test("#given a brief with no Fidelity block #when parsed #then it is not locked and every field is missing", () => {
+		// when
+		const parsed = parseFidelityBlock("# Brief\n\n## Deliverable\nformat: pdf (answered_by: request)\n")
+		// then
+		expect(parsed.present).toBe(false)
+		expect(parsed.missing).toEqual([...FIDELITY_FIELDS])
+		expect(isLocked(parsed)).toBe(false)
+	})
+
+	test("#given field lines after the next heading #when parsed #then they are outside the block", () => {
+		// given
+		const markdown = withoutLine(lockedMd, "fallback:") + "\nfallback: omit (answered_by: user)\n"
+		// then
+		expect(parseFidelityBlock(markdown).missing).toEqual(["fallback"])
+	})
+
+	test("#given a second Fidelity block #when parsed #then the duplicate is an error", () => {
+		// given
+		const markdown = lockedMd + "\n## Fidelity\nas of: x (answered_by: user)\n"
+		// when
+		const parsed = parseFidelityBlock(markdown)
+		// then
+		expect(parsed.errors.length).toBe(1)
+		expect(parsed.errors[0]).toContain("duplicate")
+		expect(parsed.fields["as of"]).toBe("latest at run start, 2026-10-23")
+		expect(isLocked(parsed)).toBe(false)
+	})
+})
+
+describe("requireLockedBrief", () => {
+	function briefFile(contents: string | null): { path: string; cleanup: () => void } {
+		const dir = mkdtempSync(join(tmpdir(), "fidelity-brief-"))
+		const path = join(dir, "brief.md")
+		if (contents !== null) writeFileSync(path, contents)
+		return { path, cleanup: () => rmSync(dir, { recursive: true, force: true }) }
+	}
+
+	test("#given a locked brief #when required #then exit 0 and no defect", () => {
+		const brief = briefFile(lockedMd)
+		try {
+			expect(requireLockedBrief(brief.path)).toMatchObject({ locked: true, exitCode: 0, defects: [], errors: [] })
+		} finally {
+			brief.cleanup()
+		}
+	})
+
+	test("#given field lines with trailing spaces, a tab, and CRLF endings #when required #then they parse like trimmed lines", () => {
+		// given
+		const markdown = lockedMd
+			.replace("meaning check: on (answered_by: default)", "meaning check: on (answered_by: default)  ")
+			.replace("fallback: block-quote (answered_by: request)", "fallback: block-quote (answered_by: request)\t")
+			.replace("as of: latest at run start, 2026-10-23 (answered_by: default)\n", "as of: latest at run start, 2026-10-23 (answered_by: default)  \r\n")
+		const brief = briefFile(markdown)
+		try {
+			// when
+			const result = requireLockedBrief(brief.path)
+			// then
+			expect(result).toMatchObject({ locked: true, exitCode: 0, defects: [], errors: [] })
+			expect(result.parsed.fields.fallback).toBe("block-quote")
+		} finally {
+			brief.cleanup()
+		}
+	})
+
+	test("#given a second Fidelity block #when required #then exit 2 naming the duplicate", () => {
+		const brief = briefFile(lockedMd + "\n## Fidelity\nas of: x (answered_by: user)\n")
+		try {
+			const result = requireLockedBrief(brief.path)
+			expect(result).toMatchObject({ locked: false, exitCode: 2, defects: [] })
+			expect(result.errors[0]).toContain("duplicate ## Fidelity block")
+		} finally {
+			brief.cleanup()
+		}
+	})
+
+	test("#given a pending, partial, or absent brief #when required #then exit 1 with the single lock defect", () => {
+		for (const contents of [pendingMd, withoutLine(lockedMd, "as of:"), "# Brief\n", null]) {
+			const brief = briefFile(contents)
+			try {
+				const result = requireLockedBrief(brief.path)
+				expect(result.locked).toBe(false)
+				expect(result.exitCode).toBe(1)
+				expect(result.defects.length).toBe(1)
+				expect(result.defects[0]).toMatchObject({ code: "fidelity_interview_incomplete", severity: "blocker", integrity: true })
+				expect(typeof result.defects[0].message).toBe("string")
+				expect(typeof result.defects[0].hint).toBe("string")
+			} finally {
+				brief.cleanup()
+			}
+		}
+	})
+
+	test("#given a malformed brief #when required #then exit 2 with the parse errors and no defect", () => {
+		const brief = briefFile(lockedMd.replace("meaning check: on (answered_by: default)", "meaning check: on"))
+		try {
+			const result = requireLockedBrief(brief.path)
+			expect(result).toMatchObject({ locked: false, exitCode: 2, defects: [] })
+			expect(result.errors[0]).toContain("malformed")
+		} finally {
+			brief.cleanup()
+		}
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/fidelity-state.mjs

@@ -0,0 +1,63 @@
+// fidelity-state.mjs - per-sentence failure counts for the fidelity repair loop. A sentence is
+// keyed by its section slug and the sorted fact ids it cites, so a reworded sentence that
+// cites the same facts keeps its count. node: builtins only.
+
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+
+import { CliError, readJsonFile, writeJsonAtomic } from "./cli-support.mjs"
+
+export const STATE_FILENAME = "fidelity-state.json"
+export const STATE_SCHEMA_VERSION = 1
+
+/** slug + '#' + the fact ids sorted and joined by ','. */
+export function sentenceKey(sectionSlug, factIds) {
+	return `${sectionSlug}#${[...factIds].sort().join(",")}`
+}
+
+function emptyState() {
+	return { schemaVersion: STATE_SCHEMA_VERSION, failures: {}, replaced: [] }
+}
+
+function isValid(state) {
+	return (
+		state !== null &&
+		typeof state === "object" &&
+		state.schemaVersion === STATE_SCHEMA_VERSION &&
+		state.failures !== null &&
+		typeof state.failures === "object" &&
+		!Array.isArray(state.failures) &&
+		Object.values(state.failures).every((count) => Number.isInteger(count) && count >= 0) &&
+		Array.isArray(state.replaced) &&
+		state.replaced.every((key) => typeof key === "string")
+	)
+}
+
+export function readState(dir) {
+	const file = join(dir, STATE_FILENAME)
+	if (!existsSync(file)) return emptyState()
+	const state = readJsonFile(file)
+	if (!isValid(state)) throw new CliError(`${file} is not a valid fidelity state`)
+	return state
+}
+
+export function recordFailure(state, key) {
+	state.failures[key] = (state.failures[key] ?? 0) + 1
+	return state.failures[key]
+}
+
+export function failureCount(state, key) {
+	return state.failures[key] ?? 0
+}
+
+export function markReplaced(state, key) {
+	if (!state.replaced.includes(key)) state.replaced.push(key)
+	return state
+}
+
+export function writeState(dir, state) {
+	if (!isValid(state)) throw new CliError("refusing to write an invalid fidelity state")
+	const file = join(dir, STATE_FILENAME)
+	writeJsonAtomic(file, state)
+	return file
+}

package/packages/shared-skills/skills/ulw-research/scripts/fidelity-state.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, onTestFinished, test } from "bun:test"
+import { mkdtempSync, readdirSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { failureCount, markReplaced, readState, recordFailure, sentenceKey, writeState } from "./fidelity-state.mjs"
+
+function tempDir(): string {
+	const dir = mkdtempSync(join(tmpdir(), "ulw-fidelity-"))
+	onTestFinished(() => rmSync(dir, { recursive: true, force: true }))
+	return dir
+}
+
+describe("fidelity state", () => {
+	test("sentenceKey is order-independent on ids", () => {
+		expect(sentenceKey("findings", ["F3", "Q1", "F12"])).toBe(sentenceKey("findings", ["F12", "F3", "Q1"]))
+		expect(sentenceKey("findings", ["F2", "F1"])).toBe("findings#F1,F2")
+		expect(sentenceKey("findings", ["F1"])).not.toBe(sentenceKey("other", ["F1"]))
+	})
+
+	test("failureCount increments per key", () => {
+		const dir = tempDir()
+		const state = readState(dir)
+		const key = sentenceKey("findings", ["F1"])
+		expect(failureCount(state, key)).toBe(0)
+		recordFailure(state, key)
+		recordFailure(state, key)
+		expect(failureCount(state, key)).toBe(2)
+		expect(failureCount(state, sentenceKey("findings", ["F2"]))).toBe(0)
+	})
+
+	test("markReplaced records the key and survives a write/read", () => {
+		const dir = tempDir()
+		const state = readState(dir)
+		const key = sentenceKey("findings", ["Q1"])
+		recordFailure(state, key)
+		markReplaced(state, key)
+		markReplaced(state, key)
+		expect(state.replaced).toEqual([key])
+		writeState(dir, state)
+		expect(readdirSync(dir)).toEqual(["fidelity-state.json"])
+		const loaded = readState(dir)
+		expect(loaded).toEqual(state)
+		expect(failureCount(loaded, key)).toBe(1)
+	})
+})