oh-my-opencode 5.1.45 → 5.1.47

package/dist/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/dist/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/dist/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)

package/dist/skills/ulw-research/scripts/contracts.mjs

@@ -6,6 +6,16 @@
 
 export const SCHEMA_VERSION = 1
 
+/** The severity vocabulary in rank order; every DEFECT_CODES entry uses one of these. */
+export const SEVERITIES = Object.freeze(["blocker", "major", "minor"])
+
+/** Defect counts per severity, then total. */
+export function countDefects(defects) {
+	const counts = Object.fromEntries(SEVERITIES.map((severity) => [severity, 0]))
+	for (const defect of defects) counts[defect.severity] += 1
+	return { ...counts, total: defects.length }
+}
+
 function deepFreeze(value) {
 	if (value === null || typeof value !== "object") return value
 	for (const key of Object.keys(value)) deepFreeze(value[key])
@@ -48,7 +58,7 @@ export const DEFECT_CODES = deepFreeze({
 	pointer_label_mismatch: { severity: "blocker", integrity: true, hint: "The placeholder's label is not the row's label; check the id, then the label." },
 	quote_anchor_unresolved: { severity: "blocker", integrity: true, hint: "A from or to anchor is missing or occurs more than once in the quote; pick unique anchor words." },
 	unit_duplicated: { severity: "blocker", integrity: true, hint: "The unit after the placeholder repeats the row's unit; use :value or remove the unit." },
-	polish_diff_fail: { severity: "blocker", integrity: true, hint: "The polish pass changed numbers, tickers, or table rows; revert to the pre-polish artifact and apply the language fixes only." },
+	polish_diff_fail: { severity: "blocker", integrity: true, hint: "The polish pass changed numbers, tickers, table rows, claim ids, markup, or hidden content; revert to the pre-polish artifact and apply the language fixes only." },
 	fidelity_interview_incomplete: { severity: "blocker", integrity: true, hint: "A fidelity field is pending or missing in brief.md; answer the open question or record its default, then rerun." },
 	derived_not_allowed: { severity: "blocker", integrity: true, hint: "The brief allows no derived or assumed numbers; cite a source row directly or change the brief with the requester." },
 	source_outside_floor: { severity: "blocker", integrity: true, hint: "The row's source is outside the source floor the brief records; use a source the brief allows or remove the fact." },
@@ -57,7 +67,8 @@ export const DEFECT_CODES = deepFreeze({
 	quote_unbound: { severity: "blocker", integrity: true, hint: "A direct quotation has no ledger quote row; register it with fact quote and insert it through its placeholder." },
 	edition_unverified: { severity: "blocker", integrity: true, hint: "The delivered file has no matching fact verify record; run fact verify on that edition and record it with --verified-by." },
 	untraceable_number: { severity: "major", integrity: false, hint: "Replace the typed number with a {{F<n>}} placeholder backed by a ledger row, or register it as assumed with a rationale." },
-	unsupported_verification: { severity: "major", integrity: false, hint: "The sentence claims a tool check that no recorded command output backs; link the recorded output row or remove the claim." },
+	unsupported_verification: { severity: "major", integrity: false, hint: "A sentence marked verified (data-claim-kind=\"verified\") cites a row that is not recorded command output; cite the recorded output row or drop the verified mark." },
+	claim_kind_mismatch: { severity: "major", integrity: false, hint: "An element marked with a claim kind (data-claim-kind) cites a row that kind does not accept, or the kind is unknown; cite a row of that kind or fix the mark (references/fidelity-claim-kinds.md)." },
 	conflicting_readings: { severity: "major", integrity: false, hint: "Two ledger rows with different periods or qualifiers are cited as one fact; split the sentence or retire one row." },
 	hedge_dropped: { severity: "major", integrity: false, hint: "Restore the qualifier the source uses (estimated, about, not yet)." },
 	direction_flipped: { severity: "major", integrity: false, hint: "The source states the opposite direction; rewrite from the quote." },
@@ -65,7 +76,8 @@ export const DEFECT_CODES = deepFreeze({
 	qualifier_dropped: { severity: "major", integrity: false, hint: "The source bounds this value (up to, at least, about); restore the qualifier or use :q." },
 	unbound_sentence: { severity: "major", integrity: false, hint: "Bind the sentence to a fact, a quote, a citation, or a claim-graph node with data-claim." },
 	meaning_drift_confirmed: { severity: "major", integrity: false, hint: "Two independent readers found the same drift; rewrite from the quote or dispute with a reason." },
-	polish_edit_rejected: { severity: "major", integrity: false, hint: "The edit changed a number, a hedge, a qualifier, a link, or a claim id; re-propose the language fix only." },
+	meaning_unverified: { severity: "major", integrity: false, hint: "No meaning reader judged this pair, or no strong reader judged a force_strong pair; run the missing reader on pairs.json and rerun fact meaning-check." },
+	polish_edit_rejected: { severity: "major", integrity: false, hint: "The edit changed a number, a hedge, a qualifier, a link, or a claim id, or contained <, > or &; re-propose the language fix only, narrowed to the words around any entity or tag." },
 	polish_hedging_decreased: { severity: "major", integrity: false, hint: "The polish pass removed qualifiers; restore them." },
 	polish_text_churn: { severity: "major", integrity: false, hint: "More than half the text changed during polish; the pass composed instead of proofreading." },
 	snapshot_mismatch: { severity: "major", integrity: false, hint: "The operands come from different collection windows; use rows from one window or state the windows separately." },
@@ -73,6 +85,7 @@ export const DEFECT_CODES = deepFreeze({
 	quote_stale_version: { severity: "major", integrity: false, hint: "The quoted source revision differs from the revision the report targets; re-snapshot the target revision or date the quote." },
 	quote_fuzzy_match: { severity: "minor", integrity: false, hint: "The source text is OCR-noisy; confirm the snapshot and prefer the raw document." },
 	name_outside_quote: { severity: "minor", integrity: false, hint: "A name in the sentence is not in the cited quote; add the source or remove the name." },
+	verification_claim_unmarked: { severity: "minor", integrity: false, hint: "The sentence reads as a check we ran but carries no verified mark; mark it {{V:F<n>:label}} on a recorded command-output row, or reword it." },
 	scope_widened_warn: { severity: "minor", integrity: false, hint: "The sentence uses a broader scope word than the quote; confirm the scope or narrow it." },
 	particle_unverified: { severity: "minor", integrity: false, hint: "The particle after this value could not be checked; read it aloud and fix it by hand if wrong." },
 	fallback_without_entity: { severity: "minor", integrity: false, hint: "The replacement quote has no entity for attribution; set one on the row." },
@@ -87,10 +100,10 @@ export const FIDELITY_CODES = Object.freeze([
 	"unresolved_placeholder", "value_mismatch", "unit_mismatch", "quote_not_verbatim", "claim_status_invalid",
 	"incompatible_operands", "pointer_label_mismatch", "quote_anchor_unresolved", "unit_duplicated", "polish_diff_fail",
 	"fidelity_interview_incomplete", "derived_not_allowed", "source_outside_floor", "snapshot_hash_mismatch",
-	"chart_value_untraceable", "quote_unbound", "edition_unverified", "untraceable_number", "unsupported_verification",
+	"chart_value_untraceable", "quote_unbound", "edition_unverified", "untraceable_number", "unsupported_verification", "claim_kind_mismatch",
 	"conflicting_readings", "hedge_dropped", "direction_flipped", "causality_added", "qualifier_dropped", "unbound_sentence",
-	"meaning_drift_confirmed", "polish_edit_rejected", "polish_hedging_decreased", "polish_text_churn", "snapshot_mismatch",
-	"join_integrity_fail", "quote_stale_version", "quote_fuzzy_match", "name_outside_quote", "scope_widened_warn",
+	"meaning_drift_confirmed", "meaning_unverified", "polish_edit_rejected", "polish_hedging_decreased", "polish_text_churn", "snapshot_mismatch",
+	"join_integrity_fail", "quote_stale_version", "quote_fuzzy_match", "name_outside_quote", "verification_claim_unmarked", "scope_widened_warn",
 	"particle_unverified", "fallback_without_entity", "meaning_drift_warn", "polish_edit_unlocated", "polish_link_changed",
 	"polish_name_changed",
 ])
@@ -184,6 +197,14 @@ export function validateOutcomeManifest(manifest) {
 	if (isObject(manifest.gates)) {
 		for (const gate of GATE_NAMES) check(errors, GATE_STATUSES.includes(manifest.gates[gate]), `gates.${gate} must be one of ${GATE_STATUSES.join(", ")}`)
 	} else errors.push("gates must be an object")
+	if (manifest.gateHistory !== undefined) {
+		if (!Array.isArray(manifest.gateHistory)) errors.push("gateHistory must be an array")
+		else for (const entry of manifest.gateHistory) {
+			check(errors, isObject(entry) && GATE_NAMES.includes(entry.gate) && GATE_STATUSES.includes(entry.status)
+				&& typeof entry.at === "string" && ISO_DATE.test(entry.at)
+				&& (entry.reason === undefined || typeof entry.reason === "string"), "gateHistory entries must have a known gate, status, timestamp, and optional reason")
+		}
+	}
 	if (Array.isArray(manifest.residualDefects)) manifest.residualDefects.forEach((defect, index) => validateDefect(defect, `residualDefects[${index}]`, errors))
 	else errors.push("residualDefects must be an array")
 	check(errors, manifest.repair === null || isObject(manifest.repair), "repair must be null or an object")

package/dist/skills/ulw-research/scripts/contracts.test.ts

@@ -75,6 +75,7 @@ const FIDELITY_BLOCKERS = [
 const FIDELITY_MAJORS = [
 	"untraceable_number",
 	"unsupported_verification",
+	"claim_kind_mismatch",
 	"conflicting_readings",
 	"hedge_dropped",
 	"direction_flipped",
@@ -82,6 +83,7 @@ const FIDELITY_MAJORS = [
 	"qualifier_dropped",
 	"unbound_sentence",
 	"meaning_drift_confirmed",
+	"meaning_unverified",
 	"polish_edit_rejected",
 	"polish_hedging_decreased",
 	"polish_text_churn",
@@ -92,6 +94,7 @@ const FIDELITY_MAJORS = [
 const FIDELITY_MINORS = [
 	"quote_fuzzy_match",
 	"name_outside_quote",
+	"verification_claim_unmarked",
 	"scope_widened_warn",
 	"particle_unverified",
 	"fallback_without_entity",

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

@@ -0,0 +1,209 @@
+// Architecture contract for the polish command (#11160 sweep): the edit contract, the ledger
+// loader, the edition-format grammar, and the severity buckets each have one owner export, so a
+// reintroduced local copy in fact-commands-polish.mjs fails one of these tests.
+import { afterAll, afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { CliError } from "./cli-support.mjs"
+import { countDefects, DEFECT_CODES, SEVERITIES } from "./contracts.mjs"
+import { runFactMeaning } from "./fact-commands-meaning.mjs"
+import * as polishCommand from "./fact-commands-polish.mjs"
+import { editionFormatOf, ledgerFrom, sessionOf } from "./fact-commands-verify.mjs"
+import { applyEdits, POLISH_EDIT_FIELDS, POLISH_MARKUP_REASON, validatePolishEdits } from "./polish-apply.mjs"
+
+const { polishDiffFails, runFactPolish } = polishCommand
+const source = (name: string) => readFileSync(join(import.meta.dir, name), "utf8")
+const LEDGER = { schemaVersion: 1, rows: [], events: [] }
+const doc = (body: string) => `<html><body>\n${body}\n</body></html>`
+const BRIEF = join(import.meta.dir, "tests", "fixtures", "fidelity-brief-locked.md")
+
+const dir = mkdtempSync(join(tmpdir(), "polish-copy-returns-"))
+const file = (name: string, content: string) => {
+	const path = join(dir, name)
+	writeFileSync(path, content)
+	return path
+}
+const ledgerPath = file("ledger.json", JSON.stringify(LEDGER))
+const badLedgerPath = file("bad-ledger.json", JSON.stringify({ schemaVersion: 1, rows: "nope" }))
+const reportPath = file("report.html", doc("<p>The span is 320 m [S1].</p>"))
+const savedSession = process.env.SESSION_DIR
+beforeEach(() => {
+	delete process.env.SESSION_DIR
+})
+afterEach(() => {
+	if (savedSession === undefined) delete process.env.SESSION_DIR
+	else process.env.SESSION_DIR = savedSession
+})
+afterAll(() => rmSync(dir, { recursive: true, force: true }))
+
+function outcome(run: () => unknown) {
+	try {
+		run()
+		return "ok"
+	} catch (error) {
+		if (!(error instanceof CliError)) throw error
+		return error.message
+	}
+}
+
+describe("the polish edit contract is polish-apply's", () => {
+	const SHAPES = [
+		["not an array", { before: "a", after: "b" }],
+		["a null edit", [null]],
+		["an array edit", [["a", "b"]]],
+		["a missing after", [{ before: "span" }]],
+		["a numeric before", [{ before: 3, after: "b" }]],
+		["a numeric reason", [{ before: "span", after: "span", reason: 5 }]],
+		["a valid edit", [{ before: "The span is", after: "The span is", reason: "none" }]],
+		["a valid edit without reason", [{ before: "The span is", after: "The span is" }]],
+	] as const
+
+	test("#given the command module #when its edit contract is read #then it is the polish-apply export", () => {
+		expect(polishCommand.validatePolishEdits).toBe(validatePolishEdits)
+		expect(polishCommand.POLISH_EDIT_FIELDS).toBe(POLISH_EDIT_FIELDS)
+		expect(source("fact-commands-polish.mjs")).not.toMatch(/typeof edit\?\.(before|after)/u)
+	})
+
+	for (const [name, edits] of SHAPES) {
+		test(`#given ${name} #when applied directly and through the CLI #then both accept or both refuse`, () => {
+			const editsPath = file(`edits-${name.replaceAll(" ", "-")}.json`, JSON.stringify(edits))
+			const direct = (() => {
+				try {
+					applyEdits(readFileSync(reportPath, "utf8"), edits as never, LEDGER)
+					return "ok"
+				} catch (error) {
+					expect(error).toBeInstanceOf(TypeError)
+					return "refused"
+				}
+			})()
+			const cli = outcome(() => runFactPolish("polish-apply", [reportPath, "--edits", editsPath, "--ledger", ledgerPath, "--out", join(dir, "out.html")]))
+			expect(cli === "ok" ? "ok" : "refused").toBe(direct)
+			if (cli !== "ok") expect(cli).toContain(editsPath)
+		})
+	}
+})
+
+describe("the ledger loader is one shared helper", () => {
+	const pairs = (extra: string[]) => () => runFactMeaning("pairs", [reportPath, "--brief", BRIEF, "--out", join(dir, "pairs.json"), ...extra])
+	const diff = (extra: string[]) => () => runFactPolish("polish-diff", ["--before", reportPath, "--after", reportPath, ...extra])
+
+	test("#given the command modules #when read #then neither defines its own ledger loader or session resolver", () => {
+		expect(polishCommand.ledgerFrom).toBe(ledgerFrom)
+		for (const name of ["fact-commands-meaning.mjs", "fact-commands-polish.mjs"]) {
+			const text = source(name)
+			expect(text, name).not.toMatch(/function (readLedgerFrom|ledgerFrom)\b|validateLedger\(/u)
+			expect(text, name).not.toMatch(/const sessionOf\s*=/u)
+		}
+	})
+
+	test("#given the same valid, invalid, and missing ledgers #when fact pairs and fact polish-diff load them #then both give the same outcome", () => {
+		for (const extra of [["--ledger", ledgerPath], ["--ledger", badLedgerPath], []]) {
+			const expected = outcome(() => ledgerFrom({ ...(extra.length > 0 ? { ledger: extra[1] } : {}) }))
+			expect(outcome(pairs(extra)), extra.join(" ")).toBe(expected)
+			expect(outcome(diff(extra)), extra.join(" ")).toBe(expected)
+		}
+		expect(outcome(() => ledgerFrom({ ledger: badLedgerPath }))).toContain("is not a valid fact ledger")
+		expect(outcome(() => ledgerFrom({}))).toContain("--ledger is required")
+	})
+
+	test("#given a session dir flag or SESSION_DIR #when resolved #then the flag wins and a bare flag is no session", () => {
+		expect(sessionOf({ "session-dir": dir })).toBe(dir)
+		expect(sessionOf({ "session-dir": true })).toBeNull()
+		process.env.SESSION_DIR = dir
+		expect(sessionOf({})).toBe(dir)
+	})
+})
+
+describe("the edition format comes from verify's grammar", () => {
+	test("#given report paths of each case #when polish-apply reads them #then it refuses exactly the Markdown classifications", () => {
+		const editsPath = file("edits-ok.json", "[]")
+		expect(source("fact-commands-polish.mjs")).not.toMatch(/md\|markdown/u)
+		for (const name of ["r.md", "R.MD", "r.markdown", "R.Markdown", "r.html", "r.HTML"]) {
+			const path = file(name, readFileSync(reportPath, "utf8"))
+			const result = outcome(() => runFactPolish("polish-apply", [path, "--edits", editsPath, "--ledger", ledgerPath, "--out", join(dir, "out.html")]))
+			expect(result.includes("takes the filled HTML edition"), name).toBe(editionFormatOf(path, undefined) === "md")
+		}
+	})
+})
+
+describe("polish-diff counts with contracts and exits on blockers only", () => {
+	type DiffRun = { exitCode: number; json: { counts: Record<string, number>; defects: { severity: string }[] } }
+	const run = (before: string, after: string) => runFactPolish("polish-diff", ["--before", file("b.html", doc(before)), "--after", file("a.html", doc(after)), "--ledger", ledgerPath]) as unknown as DiffRun
+
+	test("#given every registry code #when polishDiffFails classifies it #then only registry blockers fail", () => {
+		for (const [code, entry] of Object.entries(DEFECT_CODES) as [string, { severity: string }][]) expect(polishDiffFails([{ code, severity: "minor" }]), code).toBe(entry.severity === "blocker")
+		expect(polishDiffFails([])).toBe(false)
+		expect(source("fact-commands-polish.mjs")).not.toMatch(/blocker:\s*0|counts\.blocker > 0/u)
+	})
+
+	test("#given a major-only polish diff #when run #then it is reported with contract buckets and exits 0", () => {
+		const result = run("<p>The span may be 320 m [S1].</p>", "<p>The span is 320 m [S1].</p>")
+		const { defects } = result.json
+		expect(defects.length).toBeGreaterThan(0)
+		expect(defects.every((defect) => defect.severity === "major")).toBe(true)
+		expect(result.json.counts).toEqual(countDefects(defects))
+		expect(Object.keys(result.json.counts)).toEqual([...SEVERITIES, "total"])
+		expect(result.exitCode).toBe(0)
+	})
+
+	test("#given a changed numeral #when run #then the blocker exits 1", () => {
+		const result = run("<p>Throughput grew 3.5 times [S1].</p>", "<p>Throughput grew 35 times [S1].</p>")
+		expect(result.json.counts).toEqual(countDefects(result.json.defects))
+		expect(result.exitCode).toBe(1)
+	})
+})
+
+describe("fact polish-apply prints every rejection reason verbatim", () => {
+	type ApplyRun = { summary: string; exitCode: number; json: { defects: { index: number; code: string; reason: string }[]; data: { rejected: number; rejected_reasons: string[] } } }
+
+	test("#given an edit holding & #when fact polish-apply runs #then the printed line carries polish-apply's own markup reason", () => {
+		const before = "Revenue & profit rose across the year"
+		const editsPath = file("edits-markup-ampersand.json", JSON.stringify([{ before, after: "Revenue and profit rose across the year", reason: "wording" }]))
+		const run = runFactPolish("polish-apply", [reportPath, "--edits", editsPath, "--ledger", ledgerPath, "--out", join(dir, "ampersand.html")]) as unknown as ApplyRun
+
+		expect(run.exitCode).toBe(0)
+		expect(run.json.data.rejected).toBe(1)
+		expect(run.json.defects.map((defect) => [defect.index, defect.code, defect.reason])).toEqual([[0, "polish_edit_rejected", POLISH_MARKUP_REASON]])
+		const line = `  rejected edit 0 ("${before}"): ${POLISH_MARKUP_REASON}`
+		expect(run.json.data.rejected_reasons).toEqual([line])
+		expect(run.summary.split("\n")[1]).toBe(line)
+	})
+})
+
+describe("--changed-since stays fail-closed", () => {
+	const { pairsChangedSince } = polishCommand as unknown as { pairsChangedSince: (pairs: unknown[], mapPath: string, ledger: unknown, claims: unknown) => unknown[] }
+	const artifact = file("pre-polish.html", doc("<p>The span is 320 m [S1].</p>"))
+
+	test("#given a fill map without artifact_sha256 #when --changed-since reads it #then it refuses", () => {
+		const mapPath = file("fill-map-no-sha.json", JSON.stringify({ artifact, format: "html", entries: [] }))
+		expect(outcome(() => pairsChangedSince([], mapPath, LEDGER, null))).toContain("fill map has no artifact_sha256")
+	})
+
+	test("#given a fill map whose artifact changed since fill #when read #then it still refuses", () => {
+		const mapPath = file("fill-map-stale.json", JSON.stringify({ artifact, artifact_sha256: "0".repeat(64), format: "html", entries: [] }))
+		expect(outcome(() => pairsChangedSince([], mapPath, LEDGER, null))).toContain("changed after fill")
+	})
+})
+
+describe("polish-diff refuses an unknown defect code", () => {
+	test("#given a defect whose code is not in the registry #when classified #then it refuses instead of reading its severity", () => {
+		expect(outcome(() => polishDiffFails([{ code: "not_a_real_code", severity: "minor" }]))).toContain("unknown defect code not_a_real_code")
+		expect(source("fact-commands-polish.mjs")).not.toMatch(/\?\?\s*defect\.severity/u)
+	})
+})
+
+describe("polish-apply writes atomically and honours --format", () => {
+	test("#given the command module #when read #then it writes the edition through writeTextAtomic", () => {
+		const text = source("fact-commands-polish.mjs")
+		expect(text).not.toMatch(/writeFileSync\s*\(/u)
+		expect(text).toMatch(/writeTextAtomic\(flags\.out/u)
+	})
+
+	test("#given --format md on an .html report #when polish-apply runs #then it refuses the Markdown edition", () => {
+		const editsPath = file("edits-format.json", "[]")
+		const result = outcome(() => runFactPolish("polish-apply", [reportPath, "--edits", editsPath, "--ledger", ledgerPath, "--out", join(dir, "fmt.html"), "--format", "md"]))
+		expect(result).toContain("takes the filled HTML edition")
+	})
+})