oh-my-opencode 5.1.45 → 5.1.47

package/packages/omo-codex/plugin/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/packages/omo-codex/plugin/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)
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fact-commands-polish.mjs

@@ -0,0 +1,127 @@
+// fact-commands-polish.mjs - `fact polish-apply` and `fact polish-diff`, the script half of the
+// proofread gate, plus the --changed-since filter of `fact pairs`.
+//
+// The writing lane returns polish-edits.json ([{before, after, reason}]) and never edits the
+// report. polish-apply applies each edit through polish-apply.mjs and writes the result; a
+// rejected (major) or unlocated (minor) edit leaves its region unchanged and is listed with its
+// index and reason so the orchestrator can re-send it; every rejection reason is printed verbatim, one
+// line per rejected edit (index and the first 60 characters of its before), in the summary and in
+// data.rejected_reasons. It exits 0 whenever it wrote the output.
+// polish-diff is the whole-document backstop (polish-diff.mjs) between the pre-polish artifact
+// and any later copy; it exits 1 on a blocker. pairsChangedSince keeps only the pairs whose
+// sentence text (normalized) is not in the pre-polish artifact that a fill map names, so the
+// meaning readers re-check exactly what polish rewrote. No model, no network.
+
+import { existsSync, readFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+
+import { CliError, parseArgs, readJsonFile, sha256Of, writeJsonAtomic, writeTextAtomic } from "./cli-support.mjs"
+import { countDefects, DEFECT_CODES } from "./contracts.mjs"
+import { editionFormatOf, ledgerFrom, markdownAsHtml, sessionOf } from "./fact-commands-verify.mjs"
+import { extractPairs } from "./fact-pairs.mjs"
+import { applyEdits, POLISH_EDIT_FIELDS, validatePolishEdits } from "./polish-apply.mjs"
+import { diffPolish } from "./polish-diff.mjs"
+import { normalizeText } from "./text-normalize.mjs"
+
+export { ledgerFrom, POLISH_EDIT_FIELDS, validatePolishEdits }
+
+export const POLISH_RECORD = "polish-defects.json"
+
+/**
+ * The polish-diff exit policy: only a registry blocker fails the command; majors are reported.
+ * Fail-closed like the delivery barrier: a code the registry does not know refuses outright,
+ * because a caller-claimed severity may not demote it.
+ */
+export const polishDiffFails = (defects) =>
+	defects.some((defect) => {
+		if (!Object.hasOwn(DEFECT_CODES, defect?.code)) throw new CliError(`unknown defect code ${defect?.code}`)
+		return DEFECT_CODES[defect.code].severity === "blocker"
+	})
+
+function readText(path) {
+	try {
+		return readFileSync(path, "utf8")
+	} catch (error) {
+		throw new CliError(`cannot read ${path}: ${error.code ?? error.message}`)
+	}
+}
+
+const withSeverity = (entry) => ({ ...entry, severity: DEFECT_CODES[entry.code].severity, hint: DEFECT_CODES[entry.code].hint })
+
+/** The first 60 characters of an edit's before, on one line. */
+const beforePreview = (before) => (typeof before === "string" ? before : "").replace(/\s+/gu, " ").slice(0, 60)
+
+/** One line per rejected edit: its index, the start of its before, and its reason verbatim. */
+const rejectionLine = (entry, edit) => `  rejected edit ${entry.index} ("${beforePreview(edit?.before)}"): ${entry.reason}`
+
+function runPolishApply(args) {
+	const [report] = args.positionals
+	const { flags } = args
+	if (!report || flags.edits === undefined || flags.out === undefined) throw new CliError("usage: fact polish-apply <report.html> --edits polish-edits.json --out <report.polished.html> [--ledger F] [--session-dir D]")
+	if (editionFormatOf(report, flags.format) === "md") throw new CliError("fact polish-apply takes the filled HTML edition; polish a Markdown edition through its HTML source")
+	const html = readText(report)
+	const editsText = readText(flags.edits)
+	const edits = readJsonFile(flags.edits)
+	try {
+		validatePolishEdits(edits)
+	} catch (error) {
+		throw new CliError(`${flags.edits} must be an array of {${Object.keys(POLISH_EDIT_FIELDS).join(", ")}} objects: ${error.message}`)
+	}
+	const result = applyEdits(html, edits, ledgerFrom(flags))
+	writeTextAtomic(flags.out, result.out)
+	const defects = [...result.rejected, ...result.unlocated].sort((a, b) => a.index - b.index).map(withSeverity)
+	const counts = { applied: result.applied.length, rejected: result.rejected.length, unlocated: result.unlocated.length }
+	const data = { out: resolve(flags.out), ...counts, applied_indexes: result.applied, input_sha256: sha256Of(html), edits_sha256: sha256Of(editsText), out_sha256: sha256Of(result.out) }
+	const rejected_reasons = result.rejected.map((entry) => rejectionLine(entry, edits[entry.index]))
+	const summary = [`fact polish-apply: ${counts.applied} applied, ${counts.rejected} rejected, ${counts.unlocated} unlocated of ${edits.length} edit(s)`, ...rejected_reasons].join("\n")
+	return { json: { command: "fact polish-apply", status: "pass", exitCode: 0, defects, data: { ...data, rejected_reasons } }, summary, exitCode: 0 }
+}
+
+function runPolishDiff(args) {
+	const { flags } = args
+	if (flags.before === undefined || flags.after === undefined) throw new CliError("usage: fact polish-diff --before <pre-polish.html> --after <polished.html> [--ledger F] [--out polish-defects.json] [--session-dir D]")
+	const after = readText(flags.after)
+	const defects = diffPolish(readText(flags.before), after, ledgerFrom(flags)).map((defect) => ({ ...defect, hint: DEFECT_CODES[defect.code]?.hint ?? null }))
+	const counts = countDefects(defects)
+	const status = polishDiffFails(defects) ? "fail" : "pass"
+	const exitCode = status === "fail" ? 1 : 0
+	const record = { command: "fact polish-diff", status, exitCode, before: resolve(flags.before), artifact: resolve(flags.after), artifact_sha256: sha256Of(after), defects, counts }
+	const session = sessionOf(flags)
+	const out = flags.out ?? (session === null ? null : join(session, POLISH_RECORD))
+	if (out !== null) writeJsonAtomic(resolve(out), record)
+	const summary = `fact polish-diff: ${status.toUpperCase()} - ${counts.blocker} blocker, ${counts.major} major, ${counts.minor} minor`
+	return { json: { ...record, out: out === null ? null : resolve(out) }, summary, exitCode }
+}
+
+const pairKey = (pair) => [pair.kind, pair.sentence_key, pair.claim_id ?? "", normalizeText(pair.sentence)].join("\u0000")
+
+/**
+ * The pairs whose sentence text changed since the pre-polish artifact a fill map names: a pair is
+ * kept unless the same (kind, sentence key, normalized sentence) occurs in that artifact. The map
+ * must carry the artifact's `artifact_sha256` and the bytes must still match it, so the filter is
+ * fail-closed on a hand-made or stale map.
+ * @param {object[]} pairs extractPairs output on the polished edition
+ * @param {string} mapPath the pre-polish fill map (fact fill's `<out>.fill-map.json`)
+ */
+export function pairsChangedSince(pairs, mapPath, ledger, claims) {
+	const map = readJsonFile(mapPath)
+	if (typeof map.artifact !== "string" || !existsSync(map.artifact)) throw new CliError(`${mapPath} names no readable pre-polish artifact`)
+	const text = readText(map.artifact)
+	if (typeof map.artifact_sha256 !== "string") throw new CliError(`${mapPath} fill map has no artifact_sha256; --changed-since needs the pre-polish hash`)
+	if (sha256Of(text) !== map.artifact_sha256) throw new CliError(`${map.artifact} changed after fill; --changed-since needs the pre-polish bytes`)
+	const html = map.format === "md" ? markdownAsHtml(text, map.entries, ledger).html : text
+	const before = new Map()
+	for (const pair of extractPairs(html, ledger, claims)) before.set(pairKey(pair), (before.get(pairKey(pair)) ?? 0) + 1)
+	return pairs.filter((pair) => {
+		const left = before.get(pairKey(pair)) ?? 0
+		if (left === 0) return true
+		before.set(pairKey(pair), left - 1)
+		return false
+	})
+}
+
+/** @param {string[]} argv the arguments after `fact polish-apply` or `fact polish-diff` */
+export function runFactPolish(sub, argv) {
+	const args = parseArgs(argv)
+	return sub === "polish-apply" ? runPolishApply(args) : runPolishDiff(args)
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fact-commands-verify.mjs

@@ -0,0 +1,183 @@
+// fact-commands-verify.mjs - `fact verify` and the Markdown projection it checks.
+//
+// fact verify runs the deterministic fidelity gate over one filled HTML or Markdown edition and
+// writes a fidelity record (default $SESSION_DIR/fidelity-defects.json, through
+// writeFidelityRecord) carrying the artifact's sha256. It
+// exits 1 on any blocker or major defect (the orchestrator then records `outcome gate fidelity
+// fail`); minors alone exit 0 and are listed. A Markdown edition is read through md-lite into an
+// escaped HTML projection (same line numbers) and checked with its fill map, which is the only
+// record of where its values sit; LaTeX is verified through its Markdown source.
+//
+// The delivery barrier that reads these records (and every other fidelity record) is
+// fidelity-records.mjs.
+
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+
+import { CliError, readJsonFile, sha256Of } from "./cli-support.mjs"
+import { countDefects } from "./contracts.mjs"
+import { recompute } from "./fact-derive.mjs"
+import { readLedger } from "./fact-ledger.mjs"
+import { validateLedger } from "./fact-ledger-schema.mjs"
+import { FIDELITY_RECORD, writeFidelityRecord } from "./fidelity-records.mjs"
+import { blocksDelivery, checkFidelity } from "./gates-fidelity.mjs"
+import { parseMarkdown } from "./md-lite.mjs"
+import { escapeHtml, parseRenderedQuote, renderQuote, renderValueHtml } from "./placeholder.mjs"
+import { sessionDirOf } from "./source-commands.mjs"
+
+function readText(path) {
+	try {
+		return readFileSync(path, "utf8")
+	} catch (error) {
+		throw new CliError(`cannot read ${path}: ${error.code ?? error.message}`)
+	}
+}
+
+/**
+ * md-lite block kind -> its projection: the element tag (null = h<level>) and, for a run of one kind,
+ * the container that wraps the run. Code and table rows also take the specialized bodies below.
+ */
+export const MD_HTML_BLOCK_RULES = Object.freeze({
+	heading: Object.freeze({ tag: null }),
+	paragraph: Object.freeze({ tag: "p" }),
+	list_item: Object.freeze({ tag: "li", group: Object.freeze(["<ul>", "</ul>"]) }),
+	blockquote: Object.freeze({ tag: "blockquote" }),
+	code: Object.freeze({ tag: "code" }),
+	table_row: Object.freeze({ tag: "tr", group: Object.freeze(["<table>", "</table>"]) }),
+})
+
+/** Escaped text with inline links and code spans kept as elements, so a URL is never read as prose. */
+export const projectMarkdownInline = (text) =>
+	escapeHtml(text)
+		.replace(/\[([^\]]+)\]\(([^)\s]+)\)/gu, '<a href="$2">$1</a>')
+		.replace(/`([^`]+)`/gu, "<code>$1</code>")
+
+/** The element the HTML fill writes for one fill-map entry, or null when its bytes were edited since. */
+function entryHtml(text, entry, rows) {
+	const body = text.slice(entry.start, entry.end)
+	if (body !== entry.rendered) return null
+	const row = rows.get(entry.fact_id)
+	if (entry.translates) return `<span data-translates="${escapeHtml(entry.translates)}">${projectMarkdownInline(body.replace(/^<!--[\s\S]*?-->\s*/u, ""))}</span>`
+	if (!row) return `<data data-fact="${escapeHtml(entry.fact_id)}">${escapeHtml(body)}</data>`
+	const quoted = row.kind === "quote" ? parseRenderedQuote(body) : null
+	if (quoted) return renderQuote(row, entry.selector ?? "full", quoted.text, "html")
+	return row.kind === "quote" ? null : renderValueHtml(row, body)
+}
+
+/** [from, to) of the filled text as HTML, each intact fill-map entry rebuilt as its fill element. */
+function spanHtml(text, from, to, entries, rows, stale) {
+	let html = ""
+	let cursor = from
+	for (const entry of entries) {
+		if (entry.start < cursor || entry.end > to || entry.start < from || entry.replaced !== undefined) continue
+		const element = entryHtml(text, entry, rows)
+		if (element === null) continue
+		stale.delete(entry)
+		html += projectMarkdownInline(text.slice(cursor, entry.start)) + element
+		cursor = entry.end
+	}
+	return html + projectMarkdownInline(text.slice(cursor, to))
+}
+
+/**
+ * An escaped HTML projection of a filled Markdown edition: one element per md-lite block, each on
+ * the source line it starts on, lists and table rows grouped. Never a rendering for readers.
+ * @param {string} text the filled Markdown
+ * @param {{ fact_id: string, start: number, end: number, rendered: string, replaced?: string, translates?: string }[]} entries its fill map
+ * @param {{ rows: object[] }} ledger
+ * @returns {{ html: string, stale: object[] }} stale: entries whose bytes changed after fill (checked by text)
+ */
+export function markdownAsHtml(text, entries, ledger) {
+	const sorted = [...(entries ?? [])].sort((a, b) => a.start - b.start)
+	const rows = new Map((ledger?.rows ?? []).map((row) => [row.fact_id, row]))
+	const stale = new Set(sorted.filter((entry) => entry.replaced === undefined))
+	const lineAt = (offset) => text.slice(0, offset).split("\n").length
+	const parsed = parseMarkdown(text)
+	if (parsed.problems.length > 0) {
+		throw new CliError(`the Markdown edition is malformed: ${parsed.problems.map((problem) => `${problem.code} at line ${problem.line}`).join(", ")}; fix it before verifying`)
+	}
+	let html = "<!doctype html><html><head><title>md</title></head><body>"
+	let line = 1
+	let open = null
+	for (const block of parsed.blocks) {
+		const rule = MD_HTML_BLOCK_RULES[block.kind]
+		if (rule === undefined) throw new CliError(`md-lite block kind ${block.kind} has no projection rule`)
+		if (open && open !== block.kind) html += MD_HTML_BLOCK_RULES[open].group[1]
+		const target = lineAt(block.start)
+		if (target > line) html += "\n".repeat(target - line)
+		line = Math.max(line, target) + (text.slice(block.start, block.end).match(/\n/gu)?.length ?? 0)
+		if (rule.group && open !== block.kind) html += rule.group[0]
+		open = rule.group ? block.kind : null
+		const inner = (from, to) => spanHtml(text, from, to, sorted, rows, stale)
+		if (block.kind === "table_row") html += `<${rule.tag}>${block.cells.map((cell) => `<td>${inner(cell.start, cell.end)}</td>`).join("")}</${rule.tag}>`
+		else if (block.kind === "code") html += `<pre><${rule.tag}>${escapeHtml(block.text)}</${rule.tag}></pre>`
+		else {
+			const tag = rule.tag ?? `h${block.level}`
+			const replaced = block.kind === "blockquote" ? sorted.find((entry) => entry.replaced !== undefined && entry.start <= block.start && entry.end >= block.end) : undefined
+			const attrs = replaced ? ` data-fact="${escapeHtml(replaced.fact_id)}" data-replaced="${escapeHtml(replaced.replaced)}"` : ""
+			html += `<${tag}${attrs}>${inner(block.start, block.end)}</${tag}>`
+		}
+	}
+	return { html: `${html}${open ? MD_HTML_BLOCK_RULES[open].group[1] : ""}</body></html>\n`, stale: [...stale] }
+}
+
+/** The session dir from --session-dir or SESSION_DIR, or null; a bare flag names no session. */
+export const sessionOf = (flags) => {
+	const dir = flags["session-dir"] ?? process.env.SESSION_DIR
+	return dir && dir !== true ? resolve(dir) : null
+}
+
+/** The ledger from --ledger (validated) or from the session dir; every fact command loads it here. */
+export function ledgerFrom(flags, session = sessionOf(flags)) {
+	if (flags.ledger === undefined) {
+		if (session === null) throw new CliError("--ledger is required without --session-dir (or SESSION_DIR)")
+		return readLedger(session)
+	}
+	const ledger = readJsonFile(flags.ledger)
+	const errors = validateLedger(ledger)
+	if (errors.length > 0) throw new CliError(`${flags.ledger} is not a valid fact ledger: ${errors[0]}`)
+	return ledger
+}
+
+const MARKDOWN_EXTENSION = /\.(md|markdown)$/iu
+/** The edition format: the explicit flag, else md for a .md or .markdown path (any case), else html. */
+export const editionFormatOf = (path, flag) => flag ?? (MARKDOWN_EXTENSION.test(path) ? "md" : "html")
+
+/** The report's format (from --format or its extension) and, for Markdown, its fill map entries. */
+export function readEdition(report, flags) {
+	const format = editionFormatOf(report, flags.format)
+	if (format !== "html" && format !== "md") throw new CliError(`--format ${format}: verify html or md (a LaTeX edition is verified through its Markdown source)`)
+	const text = readText(report)
+	if (format === "html") return { format, text, entries: flags["fill-map"] === undefined ? null : readJsonFile(flags["fill-map"]).entries }
+	const map = flags["fill-map"] ?? `${report}.fill-map.json`
+	if (!existsSync(map)) throw new CliError(`a Markdown edition needs its fill map: ${map} is missing (pass --fill-map)`)
+	return { format, text, entries: readJsonFile(map).entries }
+}
+
+/** @param {{ positionals: string[], flags: Record<string, any> }} args parsed by runFact */
+export function runFactVerify(args) {
+	const [report] = args.positionals
+	const { flags } = args
+	if (!report) throw new CliError("usage: fact verify <report> [--format html|md] [--sources D] [--claims claims.json] [--fill-map F] [--brief brief.md] [--out fidelity-defects.json]")
+	const edition = readEdition(report, flags)
+	const sessionDir = sessionDirOf(flags)
+	const claimsPath = flags.claims ?? join(sessionDir, "claims.json")
+	const briefPath = flags.brief ?? join(sessionDir, "brief.md")
+	const ledger = readLedger(sessionDir)
+	const projected = edition.format === "md" ? markdownAsHtml(edition.text, edition.entries, ledger) : null
+	const result = checkFidelity(projected?.html ?? edition.text, {
+		ledger,
+		sourcesDir: resolve(flags.sources ?? join(sessionDir, "sources")),
+		claims: flags.claims !== undefined || existsSync(claimsPath) ? readJsonFile(claimsPath) : null,
+		fillMap: projected?.stale ?? edition.entries,
+		brief: existsSync(briefPath) ? readText(briefPath) : "",
+		baseDir: dirname(resolve(report)),
+		recompute,
+	})
+	const counts = countDefects(result.defects)
+	const status = result.defects.some(blocksDelivery) ? "fail" : "pass"
+	const exitCode = status === "fail" ? 1 : 0
+	const out = resolve(flags.out ?? join(sessionDir, FIDELITY_RECORD))
+	const record = writeFidelityRecord(out, "fidelity", { command: "fact verify", status, exitCode, format: edition.format, report: resolve(report), artifact_sha256: sha256Of(edition.text), defects: result.defects, counts, gatesRun: result.gatesRun })
+	return { json: { ...record, out }, summary: `fact verify: ${status.toUpperCase()} - ${counts.blocker} blocker, ${counts.major} major, ${counts.minor} minor`, exitCode }
+}