oh-my-opencode 5.1.45 → 5.1.47

package/dist/skills/ulw-research/scripts/copy-returns.test.ts

@@ -0,0 +1,183 @@
+// Architecture contract (retention bar): each shared table, list, regex, or classifier has one owner
+// export, so a reintroduced local copy in a consumer fails one of these tests (#11156 sweep).
+import { describe, expect, test } from "bun:test"
+import { readdirSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { sha256Of } from "./cli-support.mjs"
+import { countDefects, DEFECT_CODES, SEVERITIES } from "./contracts.mjs"
+import { meaningStatus, PROMOTION, promotionEligibility } from "./fact-commands-meaning.mjs"
+import { editionFormatOf, MD_HTML_BLOCK_RULES, markdownAsHtml, projectMarkdownInline } from "./fact-commands-verify.mjs"
+import { EXEMPT_KINDS, isExemptKind } from "./fidelity-binding.mjs"
+import { blocksDelivery } from "./gates-fidelity.mjs"
+import { MD_BLOCK_PATTERNS, parseMarkdown } from "./md-lite.mjs"
+import { DRIFT_KINDS, isDriftKind, MODEL_TIERS, VERDICT_SCHEMA, VERDICTS } from "./meaning-check.mjs"
+import { parseRenderedQuote, renderQuote } from "./placeholder.mjs"
+
+const source = (name: string) => readFileSync(join(import.meta.dir, name), "utf8")
+
+describe("severity vocabulary comes from contracts", () => {
+	test("#given DEFECT_CODES #when its severities are collected #then they are exactly SEVERITIES", () => {
+		const used = new Set(Object.values(DEFECT_CODES).map((entry) => entry.severity))
+		expect([...used].sort()).toEqual([...SEVERITIES].sort())
+		expect(Object.isFrozen(SEVERITIES)).toBe(true)
+	})
+
+	test("#given defects of every severity #when counted #then the buckets are SEVERITIES plus total", () => {
+		const defects = SEVERITIES.map((severity) => ({ severity }))
+		expect(Object.keys(countDefects(defects))).toEqual([...SEVERITIES, "total"])
+		expect(countDefects(defects)).toEqual({ ...Object.fromEntries(SEVERITIES.map((severity) => [severity, 1])), total: SEVERITIES.length })
+	})
+
+	test("#given every registry code and an unknown code #when the meaning status is computed #then it follows blocksDelivery", () => {
+		for (const code of [...Object.keys(DEFECT_CODES), "not_a_registered_code"]) {
+			expect(meaningStatus([{ code, severity: "minor" }]), code).toBe(blocksDelivery({ code }) ? "fail" : "pass")
+		}
+		expect(meaningStatus([])).toBe("pass")
+	})
+
+	test("#given the command modules #when read #then none restates the severity buckets, the pair kinds, or a window literal", () => {
+		for (const name of ["fact-commands-meaning.mjs", "fact-commands-verify.mjs"]) {
+			const text = source(name)
+			expect(text, name).not.toMatch(/blocker:\s*0/u)
+			expect(text, name).not.toMatch(/\["quote",\s*"claim",\s*"translation"\]/u)
+			expect(text, name).not.toMatch(/slice\(-\d+\)/u)
+			expect(text, name).not.toMatch(/counts\.blocker \+ counts\.major/u)
+		}
+	})
+})
+
+describe("one sha256 helper", () => {
+	test("#given every runtime module #when read #then only cli-support builds a hash, so records and receipts share sha256Of", () => {
+		const modules = readdirSync(import.meta.dir).filter((name) => name.endsWith(".mjs") && name !== "cli-support.mjs")
+		expect(modules.length).toBeGreaterThan(0)
+		for (const name of modules) expect(source(name), name).not.toMatch(/createHash\(/u)
+		expect(sha256Of("abc")).toBe("ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad")
+		expect(sha256Of(Buffer.from("abc"))).toBe(sha256Of("abc"))
+	})
+})
+
+describe("calibration policy is the exported PROMOTION", () => {
+	const confirmedRun = (run: string, disputed: boolean) => ({ run_id: run, confirmed: true, disputed })
+
+	test("#given false blocks only before the window #when eligibility is computed #then they are not counted", () => {
+		const window = PROMOTION.false_block_window
+		expect(Number.isInteger(window) && window > 0).toBe(true)
+		const old = [0, 1, 2].map((n) => confirmedRun(`old${n}`, true))
+		const recent = Array.from({ length: window }, (_, n) => confirmedRun(`new${n}`, false))
+		expect(promotionEligibility([...old, ...recent]).report_false_blocks_in_window).toBe(0)
+		expect(promotionEligibility([...recent, ...old]).report_false_blocks_in_window).toBe(3)
+	})
+
+	test("#given false blocks at the policy maximum #when eligibility is computed #then the threshold read from PROMOTION decides", () => {
+		const limit = PROMOTION.max_report_false_blocks_in_window
+		const clean = Array.from({ length: PROMOTION.min_runs * 20 }, (_, n) => confirmedRun(`c${n}`, false))
+		const blocks = (count: number) => Array.from({ length: count }, (_, n) => confirmedRun(`b${n}`, true))
+		expect(promotionEligibility([...clean, ...blocks(limit)]).eligible).toBe(true)
+		expect(promotionEligibility([...clean, ...blocks(limit + 1)]).eligible).toBe(false)
+	})
+})
+
+describe("verdict schema comes from the meaning-check registries", () => {
+	test("#given VERDICT_SCHEMA #when read #then its vocabularies are the owner exports", () => {
+		expect(VERDICT_SCHEMA.verdict).toBe(VERDICTS)
+		expect(VERDICT_SCHEMA.model_tier).toBe(MODEL_TIERS)
+		expect(VERDICT_SCHEMA.drift_kind).toBe(DRIFT_KINDS)
+		expect(Object.isFrozen(VERDICTS)).toBe(true)
+	})
+
+	test("#given every drift kind and a stranger #when checked #then isDriftKind is membership in DRIFT_KINDS", () => {
+		for (const kind of DRIFT_KINDS) expect(isDriftKind(kind)).toBe(true)
+		expect(isDriftKind("not_a_kind")).toBe(false)
+		expect(source("meaning-check.mjs")).not.toMatch(/new Set\(DRIFT_KINDS\)|new Set\(\["drift"/u)
+	})
+})
+
+describe("inherited lexical tables come from their owners", () => {
+	test("#given fact-pairs #when read #then it holds no Hangul range, exempt-kind set, or hand-built hedge regex", () => {
+		const text = source("fact-pairs.mjs")
+		expect(text).not.toMatch(/\\uAC00-\\uD7A3/u)
+		expect(text).not.toMatch(/\["opinion",\s*"recommendation"\]/u)
+		expect(text).not.toMatch(/new RegExp\(/u)
+	})
+
+	test("#given EXEMPT_KINDS #when checked #then isExemptKind is membership in it", () => {
+		for (const kind of EXEMPT_KINDS) expect(isExemptKind(kind)).toBe(true)
+		expect(isExemptKind("finding")).toBe(false)
+		expect(isExemptKind(undefined)).toBe(false)
+	})
+
+	test("#given md-lite #when its block grammar is read #then MD_BLOCK_PATTERNS names every block regex", () => {
+		expect(Object.keys(MD_BLOCK_PATTERNS).sort()).toEqual(["BLOCKQUOTE", "CLOSING_HASHES", "FENCE", "HEADING", "LIST_ITEM", "TABLE_SEPARATOR", "THEMATIC_BREAK"])
+		for (const pattern of Object.values(MD_BLOCK_PATTERNS)) expect(pattern).toBeInstanceOf(RegExp)
+		expect(Object.isFrozen(MD_BLOCK_PATTERNS)).toBe(true)
+	})
+})
+
+describe("markdown projection rules", () => {
+	const EVERY_KIND = ["# Title", "", "Para text.", "", "- item", "", "> quoted", "", "| a | b |", "| - | - |", "| 1 | 2 |", "", "```", "code", "```", ""].join("\n")
+
+	test("#given every block kind md-lite emits #when projected #then each kind has a projection rule", () => {
+		const kinds = [...new Set(parseMarkdown(EVERY_KIND).blocks.map((block: { kind: string }) => block.kind))].sort()
+		expect(kinds).toEqual(["blockquote", "code", "heading", "list_item", "paragraph", "table_row"])
+		for (const kind of kinds) expect(Object.hasOwn(MD_HTML_BLOCK_RULES, kind), kind).toBe(true)
+		expect(Object.keys(MD_HTML_BLOCK_RULES).sort()).toEqual(kinds)
+		const { html } = markdownAsHtml(EVERY_KIND, [], { rows: [] })
+		expect(html).toContain("<h1>Title</h1>")
+		expect(html).toContain("<ul><li>item</li></ul>")
+		expect(html).toMatch(/<table><tr><td>a<\/td><td>b<\/td><\/tr>\s*<tr><td>1<\/td><td>2<\/td><\/tr><\/table>/u)
+	})
+
+	test("#given an unterminated fence #when projected #then it is refused naming the line", () => {
+		expect(() => markdownAsHtml("Intro.\n\n```\nno close\n", [], { rows: [] })).toThrow(/unterminated_fence at line 3/u)
+	})
+
+	test("#given inline links and code #when projected #then they stay elements and the rest is escaped", () => {
+		expect(projectMarkdownInline("a <b> [x](https://e.x) `c`")).toBe('a &lt;b&gt; <a href="https://e.x">x</a> <code>c</code>')
+	})
+
+	test("#given a fill map with quotes in translates and fact_id #when projected #then the attributes are escaped", () => {
+		const md = "Before X after.\n\n> Quoted block.\n"
+		const span = { fact_id: 'F"1', start: 7, end: 8, rendered: "X", translates: 'T"1' }
+		const block = { fact_id: 'Q"2', start: md.indexOf(">"), end: md.length - 1, rendered: "", replaced: "a" }
+		const { html } = markdownAsHtml(md, [span, block], { rows: [] })
+		expect(html).toContain('data-translates="T&quot;1"')
+		expect(html).toContain('data-fact="Q&quot;2"')
+		expect(markdownAsHtml("Before X after.\n", [{ ...span, translates: undefined }], { rows: [] }).html).toContain('data-fact="F&quot;1"')
+		expect(html).not.toMatch(/="[^"]*"1"/u)
+	})
+
+	test("#given paths of each case #when the format is inferred #then md and markdown are Markdown and a flag wins", () => {
+		expect(["r.md", "R.MD", "r.markdown", "r.html", "r.txt"].map((path) => editionFormatOf(path, undefined))).toEqual(["md", "md", "md", "html", "html"])
+		expect(editionFormatOf("r.md", "html")).toBe("html")
+	})
+})
+
+describe("rendered quotes round-trip through the placeholder owner", () => {
+	const row = { fact_id: "Q1", kind: "quote", source_id: "S4", quote: "We estimate completion no earlier than 2027." }
+	const selections = [
+		["full", row.quote],
+		["lead=2", "We estimate"],
+		["from=completion,to=2027", "completion no earlier than 2027"],
+	]
+
+	for (const [selector, text] of selections) {
+		test(`#given a ${selector} quote rendered for md #when projected #then the quote element and marker survive`, () => {
+			const rendered = renderQuote(row, selector, text, "md")
+			expect(parseRenderedQuote(rendered)).toEqual({ text, marker: "[S4]" })
+			const md = `The operator wrote ${rendered}.\n`
+			const entry = { fact_id: "Q1", start: md.indexOf(rendered), end: md.indexOf(rendered) + rendered.length, rendered, selector }
+			const projected = markdownAsHtml(md, [entry], { rows: [row] })
+			expect(projected.html).toContain(renderQuote(row, selector, text, "html"))
+			expect(projected.stale).toEqual([])
+			const edited = md.replace(text, `${text} indeed`)
+			const stale = markdownAsHtml(edited, [{ ...entry, end: entry.end + " indeed".length }], { rows: [row] })
+			expect(stale.html).not.toContain("<q ")
+			expect(stale.stale).toHaveLength(1)
+		})
+	}
+
+	test("#given bytes that are not the md quote layout #when parsed #then null", () => {
+		expect(parseRenderedQuote("plain text [S4]")).toBeNull()
+	})
+})

package/dist/skills/ulw-research/scripts/delivery-barrier.test.ts

@@ -0,0 +1,245 @@
+import { describe, expect, onTestFinished, test } from "bun:test"
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { sha256Of } from "./cli-support.mjs"
+import { DEFECT_CODES } from "./contracts.mjs"
+import { FIDELITY_RECORDS, MEANING_RECORD, RECORD_ENVELOPE, writeFidelityRecord } from "./fidelity-records.mjs"
+import { blocksDelivery } from "./gates-fidelity.mjs"
+import { run } from "./report-tools.mjs"
+
+async function delivered(format = "html", codes: string[] | null = null) {
+	const root = mkdtempSync(join(tmpdir(), "delivery-barrier-"))
+	onTestFinished(() => rmSync(root, { recursive: true, force: true }))
+	const dir = join(root, "20260101-120000")
+	mkdirSync(dir)
+	const path = join(dir, `report.${format}`)
+	const record = join(dir, "fidelity-defects.json")
+	writeFileSync(path, "<p>Report</p>")
+	if (codes !== null) writeFidelityRecord(record, "fidelity", { artifact_sha256: sha256Of(readFileSync(path)), report: path, defects: codes.map((code) => ({ code, severity: "minor", message: code })) })
+	const invoke = (args: string[]) => run(["outcome", ...args, "--session-dir", dir])
+	await invoke(["init", "--promised", format])
+	expect((await invoke(["set", format, "delivered", "--path", path, ...(codes === null ? [] : ["--verified-by", record])])).exitCode).toBe(0)
+	return { dir, path, record, invoke }
+}
+
+// Enumerate the source registry, not a second list of today's fidelity codes.
+for (const [code, entry] of Object.entries(DEFECT_CODES)) {
+	if (!entry.integrity && entry.severity === "minor") continue
+	test(`#given registry blocker ${code} #when verified and finished #then delivery refuses despite a demoted row`, async () => {
+		const { dir, invoke } = await delivered("html", [code])
+		for (const command of ["verify", "finish"]) {
+			const result = await invoke([command])
+			expect(result.exitCode).toBe(1)
+			expect(result.json.problems).toContainEqual(expect.objectContaining({ code: "fidelity_unresolved", codes: [code] }))
+		}
+		expect(JSON.parse(readFileSync(join(dir, "outcome.json"), "utf8")).finishedAt).toBeNull()
+	})
+}
+
+test("#given an unknown defect code #when verified or finished #then delivery refuses with its reason", async () => {
+	const { invoke } = await delivered("html", ["future_fidelity_defect"])
+	for (const command of ["verify", "finish"]) {
+		const result = await invoke([command])
+		expect(result.exitCode).toBe(1)
+		expect(JSON.stringify(result.json.problems)).toContain("unknown defect code future_fidelity_defect")
+	}
+})
+
+test("#given a registry non-blocker #when verified and finished #then delivery passes", async () => {
+	const entry = Object.entries(DEFECT_CODES).find(([, value]) => !value.integrity && value.severity === "minor")
+	if (!entry) throw new Error("registry must have a non-blocking entry")
+	const { invoke } = await delivered("html", [entry[0]])
+	expect((await invoke(["verify"])).exitCode).toBe(0)
+	expect((await invoke(["finish"])).exitCode).toBe(0)
+})
+
+for (const format of ["html", "pdf", "docx"]) {
+	test(`#given delivered ${format} without any ledger or gate record #when verified and finished #then both refuse`, async () => {
+		const { invoke } = await delivered(format)
+		for (const command of ["verify", "finish"]) {
+			const result = await invoke([command])
+			expect(result.exitCode).toBe(1)
+			expect(JSON.stringify(result.json.problems)).toContain("fidelity gate not run")
+		}
+	})
+}
+
+test("#given a missing gate #when explicitly skipped with a reason #then the logged choice permits delivery", async () => {
+	const { dir, invoke } = await delivered()
+	const now = "2026-01-01T12:01:00.000Z"
+	await invoke(["gate", "fidelity", "not_run", "--reason", "No factual content in this edition", "--now", now])
+	const manifest = JSON.parse(readFileSync(join(dir, "outcome.json"), "utf8"))
+	expect(manifest.gateHistory).toContainEqual({ gate: "fidelity", status: "not_run", reason: "No factual content in this edition", at: now })
+	expect((await invoke(["verify"])).exitCode).toBe(0)
+	expect((await invoke(["finish"])).exitCode).toBe(0)
+	await invoke(["gate", "fidelity", "pass"])
+	expect((await invoke(["verify"])).exitCode).toBe(1)
+})
+
+test("#given a missing gate #when skipped without a meaningful reason #then the command refuses", async () => {
+	const { invoke } = await delivered()
+	for (const reason of [[], ["--reason", "   "]]) {
+		await expect(invoke(["gate", "fidelity", "not_run", ...reason])).rejects.toThrow("reason")
+	}
+})
+
+test("#given a fact ledger and an unverified edition #when the gate is skipped with a reason #then delivery still refuses", async () => {
+	const { dir, invoke } = await delivered()
+	writeFileSync(join(dir, "fact-ledger.json"), JSON.stringify({ version: 1, facts: [] }))
+	await invoke(["gate", "fidelity", "not_run", "--reason", "This harness has no verifier"])
+	for (const command of ["verify", "finish"]) {
+		const result = await invoke([command])
+		expect(result.exitCode).toBe(1)
+		expect(JSON.stringify(result.json.problems)).toContain("fidelity gate not run")
+	}
+})
+
+test("#given a stale fidelity record nobody attached #when the gate is skipped with a reason #then delivery still refuses", async () => {
+	const { dir, path, invoke } = await delivered()
+	writeFidelityRecord(join(dir, "fidelity-defects.json"), "fidelity", { artifact_sha256: "0".repeat(64), report: path, defects: [] })
+	await invoke(["gate", "fidelity", "not_run", "--reason", "This harness has no verifier"])
+	for (const command of ["verify", "finish"]) {
+		const result = await invoke([command])
+		expect(result.exitCode).toBe(1)
+		expect(JSON.stringify(result.json.problems)).toContain("fidelity gate not run")
+	}
+})
+
+test("#given an explicit skip and an existing blocker #when verified #then the skip cannot release the blocker", async () => {
+	const { invoke } = await delivered("html", ["claim_status_invalid"])
+	await invoke(["gate", "fidelity", "not_run", "--reason", "Unsupported edition"])
+	expect((await invoke(["verify"])).exitCode).toBe(1)
+})
+
+const LOCKED_BRIEF = readFileSync(join(import.meta.dir, "tests", "fixtures", "fidelity-brief-locked.md"), "utf8")
+const BLOCKER = Object.keys(DEFECT_CODES).find((code) => blocksDelivery({ code })) as string
+
+/**
+ * A delivered html edition whose locked brief requires every table record, each present, fresh for
+ * the delivered bytes, and clean. recordPath is where the session keeps each row's record; a table
+ * row with no entry here fails the coverage test below, so a new row brings its own cases.
+ */
+async function fullyRecorded(brief = LOCKED_BRIEF) {
+	const session = await delivered("html", [])
+	writeFileSync(join(session.dir, "brief.md"), brief)
+	const recordPath: Record<string, string> = { fidelity: session.record, meaning: join(session.dir, MEANING_RECORD) }
+	const write = (kind: string, fields: Record<string, unknown> = {}) =>
+		writeFidelityRecord(recordPath[kind], kind, { artifact_sha256: sha256Of(readFileSync(session.path)), report: session.path, defects: [], ...fields })
+	write("meaning")
+	const outcomes = async () => Promise.all(["verify", "finish"].map((command) => session.invoke([command])))
+	return { ...session, recordPath, write, outcomes }
+}
+
+async function expectRefused(session: Awaited<ReturnType<typeof fullyRecorded>>, problem: Record<string, unknown>) {
+	for (const result of await session.outcomes()) {
+		expect(result.exitCode).toBe(1)
+		expect(result.json.problems).toContainEqual(expect.objectContaining(problem))
+	}
+}
+
+test("#given the record table #when every row is read #then each row has every rule column and an arranged session path", async () => {
+	const { recordPath } = await fullyRecorded()
+	expect(Object.keys(recordPath).sort()).toEqual(FIDELITY_RECORDS.map((entry) => entry.kind).sort())
+	for (const entry of FIDELITY_RECORDS) {
+		for (const column of ["targets", "requiredWhen", "remedy", "blocking"] as const) expect(typeof entry[column], `${entry.kind}.${column}`).toBe("function")
+		expect(RECORD_ENVELOPE).toContain(entry.bindsTo)
+	}
+})
+
+// The table is the barrier's spec: every row gets the same five cases.
+for (const entry of FIDELITY_RECORDS) {
+	describe(`record row ${entry.kind}`, () => {
+		test("#given the record is missing while required #when verified and finished #then delivery refuses", async () => {
+			const session = await fullyRecorded()
+			unlinkSync(session.recordPath[entry.kind])
+			await expectRefused(session, { code: "edition_unverified", path: session.recordPath[entry.kind] })
+		})
+
+		test("#given the record is for other bytes #when verified and finished #then delivery refuses: a different edition", async () => {
+			const session = await fullyRecorded()
+			session.write(entry.kind, { artifact_sha256: sha256Of("an earlier draft") })
+			await expectRefused(session, { code: "edition_unverified", path: session.recordPath[entry.kind], message: expect.stringContaining("is for a different edition") })
+		})
+
+		test("#given a fresh record with a blocking defect #when verified and finished #then delivery refuses", async () => {
+			const session = await fullyRecorded()
+			session.write(entry.kind, { defects: [{ code: BLOCKER, severity: "minor", message: BLOCKER }] })
+			await expectRefused(session, { code: "fidelity_unresolved", codes: [BLOCKER], path: session.recordPath[entry.kind] })
+		})
+
+		test("#given a fresh clean record #when verified and finished #then delivery passes", async () => {
+			const session = await fullyRecorded()
+			expect((await session.outcomes()).map((result) => result.exitCode)).toEqual([0, 0])
+		})
+
+		for (const [name, mutate] of [
+			["a missing envelope field", (record: Record<string, unknown>) => delete record.written_at],
+			["an unknown field", (record: Record<string, unknown>) => Object.assign(record, { verified_elsewhere: true })],
+			["another record kind", (record: Record<string, unknown>) => Object.assign(record, { record_kind: "not_a_record_kind" })],
+		] as const) {
+			test(`#given a record with ${name} #when verified and finished #then delivery refuses it as malformed`, async () => {
+				const session = await fullyRecorded()
+				const path = session.recordPath[entry.kind]
+				const record = JSON.parse(readFileSync(path, "utf8"))
+				mutate(record)
+				writeFileSync(path, JSON.stringify(record))
+				await expectRefused(session, { code: "edition_unverified", path, message: expect.stringContaining("is malformed") })
+			})
+		}
+	})
+}
+
+test("#given a record kind outside the table or a malformed envelope #when written #then the writer refuses", () => {
+	const dir = mkdtempSync(join(tmpdir(), "delivery-barrier-writer-"))
+	onTestFinished(() => rmSync(dir, { recursive: true, force: true }))
+	const fields = { artifact_sha256: sha256Of("x"), report: join(dir, "report.html"), defects: [] }
+	expect(() => writeFidelityRecord(join(dir, "a.json"), "not_a_record_kind", fields)).toThrow("unknown fidelity record kind")
+	expect(() => writeFidelityRecord(join(dir, "b.json"), "meaning", { ...fields, artifact_sha256: "draft" })).toThrow("malformed")
+	expect(() => writeFidelityRecord(join(dir, "c.json"), "meaning", { ...fields, gatesRun: [] })).toThrow("unknown field")
+})
+
+/** A delivered, fidelity-verified html edition in a session whose locked brief sets `meaning check`. */
+async function meaningSession(meaning: "on" | "off", codes: string[] | null) {
+	const session = await fullyRecorded(LOCKED_BRIEF.replace("meaning check: on", `meaning check: ${meaning}`))
+	if (codes === null) unlinkSync(session.recordPath.meaning)
+	else session.write("meaning", { defects: codes.map((code) => ({ code, severity: "major", message: code })) })
+	return session
+}
+
+for (const code of ["meaning_drift_confirmed", "meaning_unverified"]) {
+	test(`#given a meaning record with ${code} #when verified and finished #then delivery refuses`, async () => {
+		const session = await meaningSession("on", [code])
+		await expectRefused(session, { code: "fidelity_unresolved", codes: [code], path: join(session.dir, MEANING_RECORD) })
+	})
+}
+
+test("#given the brief says meaning check on and the meaning step was skipped #when verified and finished #then delivery refuses: meaning gate not run", async () => {
+	const session = await meaningSession("on", null)
+	await expectRefused(session, { message: expect.stringContaining("meaning gate not run") })
+})
+
+test("#given a malformed ## Fidelity block that tries to turn meaning check off #when no meaning record exists #then delivery refuses: meaning gate not run", async () => {
+	const malformed = LOCKED_BRIEF.replace("meaning check: on (answered_by: default)", "meaning check: on (answered_by: default)\nmeaning check: off (answered_by: user)")
+	const session = await fullyRecorded(malformed)
+	unlinkSync(session.recordPath.meaning)
+	await expectRefused(session, { message: expect.stringContaining("meaning gate not run") })
+})
+
+test("#given the brief says meaning check off and no meaning record #when verified and finished #then delivery passes", async () => {
+	const session = await meaningSession("off", null)
+	expect((await session.outcomes()).map((result) => result.exitCode)).toEqual([0, 0])
+})
+
+test("#given a clean meaning record (warn only) under meaning check on #when verified #then delivery passes", async () => {
+	const { invoke } = await meaningSession("on", ["meaning_drift_warn"])
+	expect((await invoke(["verify"])).exitCode).toBe(0)
+})
+
+test("#given meaning check on, no fidelity evidence, and an explicit fidelity not_run #when verified #then the logged exemption covers the meaning step too", async () => {
+	const { dir, invoke } = await delivered()
+	writeFileSync(join(dir, "brief.md"), LOCKED_BRIEF)
+	await invoke(["gate", "fidelity", "not_run", "--reason", "No factual content in this edition"])
+	expect((await invoke(["verify"])).exitCode).toBe(0)
+})

package/dist/skills/ulw-research/scripts/fact-commands-meaning.mjs

@@ -0,0 +1,176 @@
+// fact-commands-meaning.mjs - `fact pairs` and `fact meaning-check`, the script half of the
+// separate-session meaning verifier. fact pairs writes the (source, report sentence) pairs a
+// reader lane gets and nothing else (with --changed-since, only the pairs whose sentence polish
+// rewrote); it honours the brief's `meaning check` field and writes
+// `{ skipped: true }` when it is off. fact meaning-check ingests the readers' verdict files
+// (meaning-check.mjs), writes fidelity-meaning-defects.json (a fidelity record bound to the pairs'
+// artifact_sha256 and report, through writeFidelityRecord), and records the run in
+// fidelity-calibration.jsonl: a header with the promotion criterion on first write, then per run
+// one run line plus one line per flagged pair. The run id hashes the inputs only, so a rerun or a
+// --dispute rerun of the same inputs replaces that run's lines in place (disputes carry forward)
+// instead of counting a second run. Neither command calls a model or the network.
+
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+
+import { CliError, parseArgs, readJsonFile, sha256Of, writeJsonAtomic, writeTextAtomic } from "./cli-support.mjs"
+import { countDefects } from "./contracts.mjs"
+import { ledgerFrom, markdownAsHtml, readEdition, sessionOf } from "./fact-commands-verify.mjs"
+import { pairsChangedSince } from "./fact-commands-polish.mjs"
+import { extractPairs, PAIR_KINDS } from "./fact-pairs.mjs"
+import { FIDELITY_INCOMPLETE, meaningCheckEnabled, requireLockedBrief } from "./fidelity-brief.mjs"
+import { MEANING_RECORD, writeFidelityRecord } from "./fidelity-records.mjs"
+import { blocksDelivery } from "./gates-fidelity.mjs"
+import { ingestVerdicts, unverifiedDefects, VERDICT_SCHEMA } from "./meaning-check.mjs"
+
+export const PAIRS_FILE = "pairs.json"
+export const CALIBRATION_FILE = "fidelity-calibration.jsonl"
+/** Starting values, recorded in the calibration log header; changed only with evidence. */
+export const PROMOTION = Object.freeze({ code: "meaning_drift_confirmed", to: "integrity", min_runs: 20, max_disputed_to_confirmed: 0.1, false_block_window: 20, max_report_false_blocks_in_window: 2 })
+
+/** The command status: fail when any defect blocks delivery under the registry policy. */
+export const meaningStatus = (defects) => (defects.some(blocksDelivery) ? "fail" : "pass")
+
+const inSession = (session, name, flag) => {
+	if (session === null) throw new CliError(`${flag} is required without --session-dir (or SESSION_DIR)`)
+	return join(session, name)
+}
+
+function briefState(flags, session) {
+	const path = flags.brief ?? inSession(session, "brief.md", "--brief")
+	const lock = requireLockedBrief(path)
+	if (lock.exitCode === 2) throw new CliError(`${path}: malformed ## Fidelity block: ${lock.errors.join("; ")}`)
+	return { path, locked: lock.locked, off: !meaningCheckEnabled(lock.parsed) }
+}
+
+function runPairs(args) {
+	const [report] = args.positionals
+	const { flags } = args
+	if (!report) throw new CliError("usage: fact pairs <report> [--format html|md] [--ledger F] [--claims claims.json] [--changed-since <fill-map.json>] [--brief brief.md] [--out pairs.json]")
+	const session = sessionOf(flags)
+	const out = resolve(flags.out ?? inSession(session, PAIRS_FILE, "--out"))
+	const brief = briefState(flags, session)
+	if (!brief.locked) {
+		const json = { command: "fact pairs", status: "fail", exitCode: 1, error: "fidelity_interview_incomplete", message: `${brief.path} has no locked ## Fidelity block` }
+		return { json, summary: `fact pairs: ${json.message}`, exitCode: 1 }
+	}
+	if (brief.off) {
+		const record = { schemaVersion: 1, skipped: true, reason: "meaning check: off", pairs: [] }
+		writeJsonAtomic(out, record)
+		return { json: { command: "fact pairs", status: "skipped", exitCode: 0, data: { out, ...record } }, summary: "fact pairs: skipped (meaning check: off)", exitCode: 0 }
+	}
+	const edition = readEdition(report, flags)
+	const claimsPath = flags.claims ?? (session === null ? null : join(session, "claims.json"))
+	const claims = claimsPath !== null && (flags.claims !== undefined || existsSync(claimsPath)) ? readJsonFile(claimsPath) : null
+	const ledger = ledgerFrom(flags, session)
+	const html = edition.format === "md" ? markdownAsHtml(edition.text, edition.entries, ledger).html : edition.text
+	const all = extractPairs(html, ledger, claims)
+	const pairs = flags["changed-since"] === undefined ? all : pairsChangedSince(all, flags["changed-since"], ledger, claims)
+	const counts = { total: pairs.length, force_strong: pairs.filter((pair) => pair.force_strong).length }
+	for (const kind of PAIR_KINDS) counts[kind] = pairs.filter((pair) => pair.kind === kind).length
+	const record = { schemaVersion: 1, skipped: false, report: resolve(report), format: edition.format, artifact_sha256: sha256Of(edition.text), pairs_sha256: sha256Of(JSON.stringify(pairs)), counts, verdict_schema: VERDICT_SCHEMA, pairs }
+	writeJsonAtomic(out, record)
+	const summary = `fact pairs: ${counts.total} pair(s), ${counts.force_strong} routed to the strong reader`
+	return { json: { command: "fact pairs", status: "pass", exitCode: 0, data: { out, ...record, pairs: undefined } }, summary, exitCode: 0 }
+}
+
+/** Every line of the log after the header, in file order; a corrupt line is a usage error naming path:line. */
+function calibrationRows(path) {
+	if (!existsSync(path)) return []
+	const rows = []
+	for (const [index, line] of readFileSync(path, "utf8").split("\n").entries()) {
+		if (line.trim() === "") continue
+		try {
+			rows.push(JSON.parse(line))
+		} catch (error) {
+			throw new CliError(`${path}:${index + 1}: corrupt calibration log line (${error.message}); repair or move the file`)
+		}
+	}
+	return rows.filter((row) => row.header !== true)
+}
+
+/** The promotion criterion evaluated over the log: runs, disputed-to-confirmed, report-level false blocks. */
+export function promotionEligibility(rows) {
+	const runs = [...new Set(rows.map((row) => row.run_id))]
+	const confirmed = rows.filter((row) => row.run !== true && row.confirmed)
+	const disputed = confirmed.filter((row) => row.disputed).length
+	const ratio = confirmed.length === 0 ? null : disputed / confirmed.length
+	const falseBlocks = runs.slice(-PROMOTION.false_block_window).filter((run) => {
+		const blocking = confirmed.filter((row) => row.run_id === run)
+		return blocking.length > 0 && blocking.every((row) => row.disputed)
+	}).length
+	const eligible = runs.length >= PROMOTION.min_runs && ratio !== null && ratio < PROMOTION.max_disputed_to_confirmed && falseBlocks <= PROMOTION.max_report_false_blocks_in_window
+	return { runs: runs.length, confirmed: confirmed.length, disputed_confirmed: disputed, disputed_to_confirmed: ratio, report_false_blocks_in_window: falseBlocks, eligible }
+}
+
+/**
+ * Writes this run's lines: one run line (so a run with no flagged pair still counts) and one line per
+ * flagged pair. A run id already in the log is replaced in place, keeping its position in the false
+ * block window and any earlier dispute on a pair the new lines do not dispute.
+ */
+function recordCalibration(path, lines, runId, pairsSha) {
+	const before = calibrationRows(path)
+	const previous = before.filter((row) => row.run_id === runId)
+	const disputes = new Map(previous.filter((row) => row.disputed).map((row) => [row.pair_id, row.reason]))
+	const pairRows = lines.map((line) => {
+		const row = { ...JSON.parse(line), run_id: runId, pairs_sha256: pairsSha }
+		return !row.disputed && disputes.has(row.pair_id) ? { ...row, disputed: true, reason: disputes.get(row.pair_id) } : row
+	})
+	const rows = [{ run: true, run_id: runId, pairs_sha256: pairsSha, flagged: pairRows.length }, ...pairRows]
+	const at = previous.length === 0 ? before.length : before.indexOf(previous[0])
+	const after = [...before.slice(0, at).filter((row) => row.run_id !== runId), ...rows, ...before.slice(at).filter((row) => row.run_id !== runId)]
+	const header = { header: true, schemaVersion: 1, promotion: PROMOTION, note: "starting values; change them only with evidence" }
+	writeTextAtomic(path, `${[header, ...after].map((row) => JSON.stringify(row)).join("\n")}\n`)
+	return { written: pairRows.length, replaced: previous.length > 0, rows: after }
+}
+
+/** A `{ skipped: true }` pairs file is accepted only when the locked brief turns the meaning check off. */
+function skippedRefusal(flags, session) {
+	const brief = briefState(flags, session)
+	if (!brief.locked) return { error: FIDELITY_INCOMPLETE, message: `${brief.path} has no locked ## Fidelity block, so a skipped meaning check cannot be accepted` }
+	if (!brief.off) return { error: "meaning_check_required", message: `${flags.pairs} says skipped but ${brief.path} has meaning check on; rerun fact pairs` }
+	return null
+}
+
+function runMeaningCheck(args) {
+	const { flags } = args
+	const usage = "usage: fact meaning-check --pairs pairs.json --verdicts cheap.json [--verdicts strong.json] [--dispute P<n> --reason TEXT] [--run-id ID] [--calibration F] [--out F]"
+	if (flags.pairs === undefined || !Array.isArray(flags.verdicts)) throw new CliError(usage)
+	const session = sessionOf(flags)
+	const pairsText = readFileSync(flags.pairs, "utf8")
+	const pairsDoc = readJsonFile(flags.pairs)
+	if (pairsDoc?.skipped === true) {
+		const refusal = skippedRefusal(flags, session)
+		if (refusal !== null) return { json: { command: "fact meaning-check", status: "fail", exitCode: 1, ...refusal }, summary: `fact meaning-check: ${refusal.message}`, exitCode: 1 }
+		return { json: { command: "fact meaning-check", status: "skipped", exitCode: 0, defects: [] }, summary: JSON.stringify({ command: "fact meaning-check", status: "skipped" }), exitCode: 0 }
+	}
+	if (typeof pairsDoc?.artifact_sha256 !== "string" || typeof pairsDoc.report !== "string") throw new CliError(`${flags.pairs} names no artifact_sha256 and report, so the meaning record cannot be bound to an edition; rerun fact pairs`)
+	for (const file of flags.verdicts) readJsonFile(file)
+	const verdictTexts = flags.verdicts.map((file) => readFileSync(file, "utf8"))
+	const dispute = flags.dispute === undefined ? undefined : { pair_id: flags.dispute, reason: args.required("reason") }
+	let result
+	try {
+		result = ingestVerdicts(pairsDoc, flags.verdicts, dispute ? { dispute } : {})
+	} catch (error) {
+		throw new CliError(`invalid verdict input: ${error.message}`)
+	}
+	const out = resolve(flags.out ?? inSession(session, MEANING_RECORD, "--out"))
+	const calibration = resolve(flags.calibration ?? join(session ?? dirname(out), CALIBRATION_FILE))
+	const runId = flags["run-id"] ?? sha256Of([pairsText, ...verdictTexts].join("\0")).slice(0, 16)
+	const pairsSha = pairsDoc.pairs_sha256 ?? sha256Of(pairsText)
+	const log = recordCalibration(calibration, result.calibrationLines, runId, pairsSha)
+	const defects = [...result.defects, ...unverifiedDefects(result.unverified)]
+	const counts = countDefects(defects)
+	const status = meaningStatus(defects)
+	const exitCode = status === "fail" ? 1 : 0
+	const record = writeFidelityRecord(out, "meaning", { command: "fact meaning-check", status, exitCode, artifact_sha256: pairsDoc.artifact_sha256, report: pairsDoc.report, run_id: runId, pairs_sha256: pairsSha, defects, counts, dropped: result.dropped, unverified: result.unverified, calibration_path: calibration, calibration_written: log.written, calibration_replaced: log.replaced, promotion_eligibility: promotionEligibility(log.rows) })
+	const confirmed = result.defects.filter((defect) => defect.code === "meaning_drift_confirmed").length
+	const summary = JSON.stringify({ command: "fact meaning-check", status, defects: defects.length, confirmed, warn: result.defects.length - confirmed, dropped: result.dropped.length, unverified: result.unverified.length })
+	return { json: { ...record, out }, summary, exitCode }
+}
+
+/** @param {string[]} argv the arguments after `fact pairs` or `fact meaning-check` */
+export function runFactMeaning(sub, argv) {
+	const args = parseArgs(argv, { repeatable: ["verdicts"] })
+	return sub === "pairs" ? runPairs(args) : runMeaningCheck(args)
+}