lazycodex-ai 5.1.46 → 5.1.48

package/packages/shared-skills/skills/ulw-research/scripts/fact-commands-polish.mjs

@@ -0,0 +1,132 @@
+// 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 { lockedBrief } from "./fidelity-policy.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] [--brief brief.md] [--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 { refusal } = lockedBrief("fact polish-apply", flags)
+	if (refusal) return refusal
+	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] [--brief brief.md] [--session-dir D]")
+	const { refusal } = lockedBrief("fact polish-diff", flags)
+	if (refusal) return refusal
+	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/shared-skills/skills/ulw-research/scripts/fact-commands-verify.mjs

@@ -8,6 +8,11 @@
 // 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 locked brief is re-judged here, not only at fill: the edition's fill map (--fill-map, else
+// `<report>.fill-map.json` when present) must carry the current brief's brief_sha256
+// (brief_changed), and policyErrors re-runs over every data-fact the edition carries, so an
+// edition that violates the current derived-numbers or source-floor rule fails here too.
+//
 // The delivery barrier that reads these records (and every other fidelity record) is
 // fidelity-records.mjs.
 
@@ -18,6 +23,8 @@ 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 { briefBindingErrors, fillPolicy, lockedBrief, policyErrors } from "./fidelity-policy.mjs"
 import { FIDELITY_RECORD, writeFidelityRecord } from "./fidelity-records.mjs"
 import { blocksDelivery, checkFidelity } from "./gates-fidelity.mjs"
 import { parseMarkdown } from "./md-lite.mjs"
@@ -120,6 +127,24 @@ export function markdownAsHtml(text, entries, ledger) {
 	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")
@@ -140,8 +165,11 @@ 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 { parsed, refusal } = lockedBrief("fact verify", flags)
+	if (refusal) return refusal
+	const policy = fillPolicy(parsed)
+	const edition = readEdition(report, flags)
 	const claimsPath = flags.claims ?? join(sessionDir, "claims.json")
 	const briefPath = flags.brief ?? join(sessionDir, "brief.md")
 	const ledger = readLedger(sessionDir)
@@ -155,10 +183,15 @@ export function runFactVerify(args) {
 		baseDir: dirname(resolve(report)),
 		recompute,
 	})
-	const counts = countDefects(result.defects)
-	const status = result.defects.some(blocksDelivery) ? "fail" : "pass"
+	const checked = projected?.html ?? edition.text
+	const pointers = [...checked.matchAll(/\bdata-fact="([^"]+)"/gu)].map((match) => ({ token: match[0], start: match.index, parsed: { id: match[1] } }))
+	const mapPath = flags["fill-map"] ?? `${report}.fill-map.json`
+	const bound = existsSync(mapPath) ? briefBindingErrors(readJsonFile(mapPath), mapPath, parsed) : []
+	const defects = [...bound, ...policyErrors(checked, pointers, ledger, sessionDir, policy).errors, ...result.defects]
+	const counts = countDefects(defects)
+	const status = 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 })
+	const record = writeFidelityRecord(out, "fidelity", { command: "fact verify", status, exitCode, format: edition.format, report: resolve(report), artifact_sha256: sha256Of(edition.text), defects, counts, gatesRun: result.gatesRun })
 	return { json: { ...record, out }, summary: `fact verify: ${status.toUpperCase()} - ${counts.blocker} blocker, ${counts.major} major, ${counts.minor} minor`, exitCode }
 }

package/packages/shared-skills/skills/ulw-research/scripts/fact-commands.mjs

@@ -1,21 +1,19 @@
-// fact-commands.mjs - the `fact` subcommands of report-tools: add, quote, retract, export, fill,
-// derive, verify (fact-commands-verify.mjs), pairs and meaning-check (fact-commands-meaning.mjs). Every value reaches the ledger from a source
+// fact-commands.mjs - the `fact` subcommands of report-tools: add, quote, retract, export, derive,
+// fill (fact-commands-fill.mjs), verify (fact-commands-verify.mjs), pairs and meaning-check
+// (fact-commands-meaning.mjs), polish-apply and polish-diff (fact-commands-polish.mjs). Every value reaches the ledger from a source
 // snapshot through a deterministic locator or from a declared derivation; nothing here accepts a
 // typed value. add and quote print the row with 60 chars of source context on each side (JSON
 // with --json). Exit 0 ok, 1 semantic failure (fact_not_located, fill errors, a refused
 // derivation), 2 usage. node: builtins and sibling imports only.
 
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
-import { dirname, extname, join, resolve } from "node:path"
+import { join, resolve } from "node:path"
 
-import { CliError, parseArgs, sha256Of, writeJsonAtomic } from "./cli-support.mjs"
-import { DEFECT_CODES } from "./contracts.mjs"
+import { CliError, parseArgs, sha256Of } from "./cli-support.mjs"
 import { derive } from "./fact-derive.mjs"
-import { fill } from "./fact-fill.mjs"
 import { addRow, readLedger, retractRow, supersedeRow, writeLedger } from "./fact-ledger.mjs"
 import { locateFind, locateMatch, locatePageLine, locateTable } from "./fact-locate.mjs"
 import { QUALIFIER_FORMS } from "./fidelity-lexicon.mjs"
-import { readState, writeState } from "./fidelity-state.mjs"
 import { exportRows } from "./fidelity-values.mjs"
 import { pointedFlag, sessionDirOf, snapshotOf } from "./source-commands.mjs"
 
@@ -156,44 +154,6 @@ function runExport(args) {
 	return { json: { command: "fact export", status: "pass", exitCode: 0, data: { out: resolve(args.flags.out), format: args.flags.csv ? "csv" : "json", sha256: sha256Of(text), coverage } }, summary: coverage, exitCode: 0 }
 }
 
-/** The inline edition: local stylesheets and scripts inlined, relative image paths made absolute. */
-function inlineAssets(html, baseDir) {
-	const local = (ref) => !/^[a-z][a-z0-9+.-]*:|^\/\//i.test(ref)
-	return html
-		.replace(/<link\b[^>]*\brel=["']stylesheet["'][^>]*>/gi, (tag) => {
-			const href = /\bhref=["']([^"']+)["']/i.exec(tag)?.[1]
-			return href && local(href) ? `<style>${readText(resolve(baseDir, href))}</style>` : tag
-		})
-		.replace(/<script\b([^>]*)\bsrc=["']([^"']+)["']([^>]*)><\/script>/gi, (tag, pre, src, post) => (local(src) ? `<script${pre}${post}>${readText(resolve(baseDir, src))}</script>` : tag))
-		.replace(/(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/gi, (tag, pre, src, post) => (local(src) && !src.startsWith("/") ? `${pre}${resolve(baseDir, src)}${post}` : tag))
-}
-
-function runFill(args) {
-	const [source] = args.positionals
-	const { flags } = args
-	if (!source || (flags.out === undefined && !flags.view)) throw new CliError("usage: fact fill <src> (--out <path> | --view) [--format html|md|tex] [--inline] [--replace-failed]")
-	const format = flags.format ?? ({ ".md": "md", ".tex": "tex" }[extname(source).toLowerCase()] ?? "html")
-	if (!["html", "md", "tex"].includes(format)) throw new CliError("--format must be html, md, or tex")
-	if (flags.inline && format !== "html") throw new CliError("--inline applies to the html edition only")
-	const sessionDir = sessionDirOf(flags)
-	const state = flags["replace-failed"] ? readState(sessionDir) : null
-	const result = fill(readText(source), readLedger(sessionDir), { format: format === "tex" ? "md" : format, view: flags.view === true, ...(state ? { replaceFailed: state } : {}) })
-	const warnings = result.warnings
-	if (result.out === null) {
-		const defects = result.errors.map((error) => ({ ...error, severity: DEFECT_CODES[error.code]?.severity ?? "blocker", hint: DEFECT_CODES[error.code]?.hint ?? null }))
-		return { json: { command: "fact fill", status: "fail", exitCode: 1, defects, warnings }, summary: `fact fill: FAIL - ${defects.length} error(s), nothing written`, exitCode: 1 }
-	}
-	const out = flags.inline ? inlineAssets(result.out, dirname(resolve(source))) : result.out
-	if (flags.view) return { text: out, summary: `fact fill --view: ${result.fillMap.length} pointer(s), ${warnings.length} warning(s)`, exitCode: 0 }
-	writeFileSync(flags.out, out)
-	if (state) writeState(sessionDir, state)
-	const artifact = sha256Of(out)
-	const map = `${resolve(flags.out)}.fill-map.json`
-	writeJsonAtomic(map, { schemaVersion: 1, format, artifact: resolve(flags.out), artifact_sha256: artifact, entries: result.fillMap })
-	const data = { out: resolve(flags.out), map, artifact_sha256: artifact, occurrences: result.fillMap.length, warnings }
-	return { json: { command: "fact fill", status: "pass", exitCode: 0, defects: [], data }, summary: `fact fill: wrote ${flags.out} (${result.fillMap.length} pointer(s))`, exitCode: 0 }
-}
-
 function runDerive(args) {
 	const { flags } = args
 	const op = args.required("op")
@@ -217,6 +177,7 @@ function runDerive(args) {
 export async function runFact(argv) {
 	const [sub, ...rest] = argv
 	if (sub === "pairs" || sub === "meaning-check") return (await import("./fact-commands-meaning.mjs")).runFactMeaning(sub, rest)
+	if (sub === "polish-apply" || sub === "polish-diff") return (await import("./fact-commands-polish.mjs")).runFactPolish(sub, rest)
 	const args = parseArgs(rest, { booleans: BOOLEANS })
 	switch (sub) {
 		case "add":
@@ -228,12 +189,12 @@ export async function runFact(argv) {
 		case "export":
 			return runExport(args)
 		case "fill":
-			return runFill(args)
+			return (await import("./fact-commands-fill.mjs")).runFactFill(args)
 		case "derive":
 			return runDerive(args)
 		case "verify":
 			return (await import("./fact-commands-verify.mjs")).runFactVerify(args)
 		default:
-			throw new CliError("usage: fact <add|quote|retract|export|fill|verify|derive|pairs|meaning-check> ...")
+			throw new CliError("usage: fact <add|quote|retract|export|fill|verify|derive|pairs|meaning-check|polish-apply|polish-diff> ...")
 	}
 }

package/packages/shared-skills/skills/ulw-research/scripts/fact-fill.mjs

@@ -10,7 +10,8 @@ import { failureCount, markReplaced, sentenceKey } from "./fidelity-state.mjs"
 import { findPlaceholders, lead, qualifiedText, renderBlockquote, renderQuote, renderValueHtml, subSpan, valueParts } from "./placeholder.mjs"
 import { splitSentences } from "./sentence-split.mjs"
 
-const FORMATS = Object.freeze(["html", "md"])
+/** The output formats fill renders. */
+export const FILL_FORMATS = Object.freeze(["html", "md"])
 const TRANSLATION = Object.freeze({
 	html: /^\s*<span data-translates="(Q\d+)">[\s\S]*?<\/span>/u,
 	md: /^\s*<!-- translates: (Q\d+) -->[^\n]*/u,
@@ -166,7 +167,7 @@ function assemble(text, parts, context) {
  */
 export function fill(sourceText, ledger, options = {}) {
 	const format = options.format ?? "html"
-	if (!FORMATS.includes(format)) throw new TypeError(`format must be one of ${FORMATS.join(", ")}`)
+	if (!FILL_FORMATS.includes(format)) throw new TypeError(`format must be one of ${FILL_FORMATS.join(", ")}`)
 	const rows = new Map(ledger.rows.map((row) => [row.fact_id, row]))
 	const found = findPlaceholders(sourceText)
 	const errors = []

package/packages/shared-skills/skills/ulw-research/scripts/fact-pairs.mjs

@@ -96,11 +96,11 @@ function lexiconRouted(group, sentence) {
 	return lexiconChecks(probes).forceStrong.length > 0
 }
 
-function quotePairs(sentence, rows, filled, slug, reportLang) {
+function quotePairs(sentence, rows, slug, reportLang) {
 	const groups = new Map()
 	for (const fact of sentence.facts) {
 		const row = rows.get(fact.id)
-		if (!row?.quote || (filled && !filled.has(fact.id))) continue
+		if (!row?.quote) continue
 		const group = groups.get(row.quote) ?? { quote: row.quote, row, rows, facts: [], ids: [] }
 		group.facts.push(fact)
 		if (!group.ids.includes(fact.id)) group.ids.push(fact.id)
@@ -136,11 +136,11 @@ function claimPairs(ctx, block, sentence, byClaim, slug, reportLang) {
 		}))
 }
 
-function translationPair(node, rows, filled, slug, reportLang) {
+function translationPair(node, rows, slug, reportLang) {
 	const id = node.attrs["data-translates"]
 	const row = rows.get(id)
 	const text = proseText(node)
-	if (!row?.quote || text === "" || (filled && !filled.has(id))) return null
+	if (!row?.quote || text === "") return null
 	return {
 		kind: "translation",
 		sentence_key: sentenceKey(slug, [id]),
@@ -157,13 +157,11 @@ function translationPair(node, rows, filled, slug, reportLang) {
  * @param {string} html the filled report
  * @param {{ rows: object[] }} ledger
  * @param {{ claims: object[] } | object[] | null} claims indexClaims(...) output or its claims array
- * @param {{ fact_id: string }[]} [fillMap] fact fill's map; when given, only facts it filled are paired
  * @returns {object[]} pairs with pair_id P1, P2, ... in document order
  */
-export function extractPairs(html, ledger, claims, fillMap) {
+export function extractPairs(html, ledger, claims) {
 	const ctx = buildContext(parseHtml(html), {})
 	const rows = new Map((ledger?.rows ?? []).map((row) => [row.fact_id, row]))
-	const filled = Array.isArray(fillMap) ? new Set(fillMap.map((entry) => entry.fact_id)) : null
 	const byClaim = claimMap(claims)
 	const htmlLang = ctx.all.find((node) => node.tag === "html")?.attrs.lang
 	const reportLang = htmlLang ? htmlLang.toLowerCase().split("-")[0] : null
@@ -174,12 +172,12 @@ export function extractPairs(html, ledger, claims, fillMap) {
 		if (!findings) continue
 		const slug = slugOf(block.scope)
 		for (const sentence of block.sentences) {
-			out.push(...quotePairs(sentence, rows, filled, slug, reportLang), ...claimPairs(ctx, block, sentence, byClaim, slug, reportLang))
+			out.push(...quotePairs(sentence, rows, slug, reportLang), ...claimPairs(ctx, block, sentence, byClaim, slug, reportLang))
 		}
 		for (const node of ctx.util.descendants(block.owner)) {
 			if (node.attrs?.["data-translates"] === undefined || seenSpans.has(node)) continue
 			seenSpans.add(node)
-			const pair = translationPair(node, rows, filled, slug, reportLang)
+			const pair = translationPair(node, rows, slug, reportLang)
 			if (pair) out.push(pair)
 		}
 	}

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

@@ -39,8 +39,8 @@ function filled(): { out: string; fillMap: { fact_id: string }[] } {
 }
 
 function pairs(): Pair[] {
-	const { out, fillMap } = filled()
-	return extractPairs(out, LEDGER, CLAIMS, fillMap) as Pair[]
+	const { out } = filled()
+	return extractPairs(out, LEDGER, CLAIMS) as Pair[]
 }
 
 describe("extractPairs: a filled report", () => {
@@ -110,14 +110,7 @@ describe("extractPairs: a filled report", () => {
 		expect(sentences.some((text) => text.includes("Bridge authority"))).toBe(false)
 	})
 
-	test("#given a fill map that omits a fact #when extracted #then that hand-typed fact yields no pair", () => {
-		const { out, fillMap } = filled()
-		const kept = fillMap.filter((entry) => entry.fact_id !== "F13")
-		const result = extractPairs(out, LEDGER, CLAIMS, kept) as Pair[]
-		expect(result.some((pair) => Array.isArray(pair.fact_ids) && (pair.fact_ids as string[]).includes("F13"))).toBe(false)
-	})
-
-	test("#given no fill map #when extracted #then every data-fact element counts as filled", () => {
+	test("#given the filled fixture #when extracted #then every data-fact element yields its pair", () => {
 		const { out } = filled()
 		expect((extractPairs(out, LEDGER, CLAIMS) as Pair[]).length).toBe(6)
 	})
@@ -125,20 +118,11 @@ describe("extractPairs: a filled report", () => {
 	test("#given a Hangul quote #when extracted #then source_lang is ko", () => {
 		const html = "<html><body><h2>Findings</h2><p>HBM revenue reached {{F21:hbm_rev}} [S5].</p></body></html>"
 		const result = fill(html, LEDGER, { format: "html" }) as { out: string; fillMap: { fact_id: string }[] }
-		const [pair] = extractPairs(result.out, LEDGER, CLAIMS, result.fillMap) as Pair[]
+		const [pair] = extractPairs(result.out, LEDGER, CLAIMS) as Pair[]
 		expect(pair).toMatchObject({ fact_ids: ["F21"], source_lang: "ko", report_lang: "en" })
 	})
 })
 
-describe("extractPairs: a fill map over translations", () => {
-	test("#given a fill map that omits the translated fact #when extracted #then no translation pair is emitted", () => {
-		const { out, fillMap } = filled()
-		const kept = fillMap.filter((entry) => entry.fact_id !== "Q7")
-		const result = extractPairs(out, LEDGER, CLAIMS, kept) as Pair[]
-		expect(result.some((pair) => pair.kind === "translation")).toBe(false)
-	})
-})
-
 describe("hasHedge: a month is not a hedge", () => {
 	test("#given a text that starts with the month May #when checked #then it does not count as hedged", () => {
 		expect(hasHedge("May 2024 sales rose.")).toBe(false)
@@ -152,9 +136,9 @@ describe("hasHedge: a month is not a hedge", () => {
 
 describe("extractPairs: determinism", () => {
 	test("#given the same filled report twice #when extracted #then both results are byte-for-byte equal", () => {
-		const { out, fillMap } = filled()
-		const first = JSON.stringify(extractPairs(out, LEDGER, CLAIMS, fillMap))
-		const second = JSON.stringify(extractPairs(out, LEDGER, CLAIMS, fillMap))
+		const { out } = filled()
+		const first = JSON.stringify(extractPairs(out, LEDGER, CLAIMS))
+		const second = JSON.stringify(extractPairs(out, LEDGER, CLAIMS))
 		expect(second).toBe(first)
 	})
 })

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

@@ -0,0 +1,183 @@
+// fidelity-policy.mjs - what the locked `## Fidelity` block of brief.md means to the CLI stages.
+//
+// lockedBrief is the gate the six reader-facing stages (fact fill, verify, pairs, meaning-check,
+// polish-apply, polish-diff) run before reading or writing anything: an unlocked brief returns
+// one fidelity_interview_incomplete defect (exit 1), a malformed block is a usage error (exit 2).
+// fillPolicy reads the fields fact fill consumes (a value off its table is a usage error, exit 2),
+// and policyErrors refuses a placeholder whose row the brief forbids: derived_not_allowed
+// (`derived numbers: none` against a derived, converted, or assumed row) and source_outside_floor
+// (the source floor is evaluated live against each source's meta.json at every fill and verify;
+// under any floor but `standard` a row resting on no source is refused too; a row's outside_floor
+// is only the cached result). briefHashOf binds the locked block into the fill map, and
+// briefBindingErrors refuses an edition whose map was filled under another brief (brief_changed).
+// Collection stages never call this module. node: builtins and sibling imports only.
+
+import { existsSync, readFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+
+import { CliError, sha256Of } from "./cli-support.mjs"
+import { DEFECT_CODES } from "./contracts.mjs"
+import { KIND_RULES } from "./fact-ledger-kinds.mjs"
+import { FIDELITY_FIELDS, meaningCheckEnabled, requireLockedBrief } from "./fidelity-brief.mjs"
+
+export { meaningCheckEnabled }
+
+/**
+ * Ledger kinds a brief with `derived numbers: none` refuses. A policy list, not the ledger's
+ * derivation set: it also names assumed. Every name must be a KIND_RULES kind (checked at load).
+ */
+const DERIVED_KINDS = Object.freeze(["derived", "converted", "assumed"])
+for (const kind of DERIVED_KINDS) {
+	if (!Object.hasOwn(KIND_RULES, kind)) throw new Error(`fidelity-policy: ${kind} is not a KIND_RULES kind`)
+}
+
+/** Fields whose only legal values are a closed table: value (any case) -> its reading. */
+const VALUE_TABLES = Object.freeze({
+	"derived numbers": Object.freeze({ allowed: false, none: true }),
+	fallback: Object.freeze({ "block-quote": "quote", omit: "omit" }),
+})
+
+/** The reading of a table value; any other text is a usage error naming the field and the value. */
+function tableValue(field, value) {
+	const table = VALUE_TABLES[field]
+	const key = value.trim().toLowerCase()
+	if (Object.hasOwn(table, key)) return table[key]
+	throw new CliError(`${field} "${value}" is not ${Object.keys(table).join(", ")}`)
+}
+
+/** How each field value the fill stages consume is read; the single owner of those readings. */
+export const FIDELITY_VALUE_RULES = Object.freeze({
+	tables: VALUE_TABLES,
+	derivedKinds: DERIVED_KINDS,
+	derivedRefused: (kind) => DERIVED_KINDS.includes(kind),
+	derivedNone: (value) => tableValue("derived numbers", value),
+	fallback: (value) => tableValue("fallback", value),
+	translations: (value) => /with translation beside/iu.test(value),
+	meaningCheck: (value) => meaningCheckEnabled({ fields: { "meaning check": value } }),
+})
+
+/** The `source floor` forms: `pattern` reads one, `listed` forms carry a comma list. */
+export const SOURCE_FLOOR_RULES = Object.freeze([
+	Object.freeze({ kind: "standard", form: "standard", pattern: /^standard$/iu, listed: false }),
+	Object.freeze({ kind: "primary", form: "primary only", pattern: /^primary only$/iu, listed: false }),
+	Object.freeze({ kind: "pointed", form: "pointed only: <list>", pattern: /^pointed only:\s*(.+)$/iu, listed: true }),
+	Object.freeze({ kind: "classes", form: "classes: <list>", pattern: /^classes:\s*(.+)$/iu, listed: true }),
+])
+const lineOf = (text, at) => text.slice(0, at).split("\n").length
+const listOf = (text) => text.split(",").map((entry) => entry.trim()).filter(Boolean)
+
+/** brief.md from --brief, else the session's; a usage error when neither is known. */
+export function briefPathOf(flags) {
+	if (flags.brief !== undefined && flags.brief !== true) return resolve(flags.brief)
+	const dir = flags["session-dir"] ?? process.env.SESSION_DIR
+	if (!dir || dir === true) throw new CliError("--brief is required without --session-dir (or SESSION_DIR)")
+	return join(resolve(dir), "brief.md")
+}
+
+/**
+ * @returns {{ parsed: object, refusal: null } | { parsed: null, refusal: { json: object, summary: string, exitCode: 1 } }}
+ */
+export function lockedBrief(command, flags) {
+	const path = briefPathOf(flags)
+	const lock = requireLockedBrief(path)
+	if (lock.exitCode === 2) throw new CliError(`${path}: ${lock.errors.join("; ")}`)
+	if (lock.locked) return { parsed: lock.parsed, refusal: null }
+	const json = { command, status: "fail", exitCode: 1, defects: lock.defects }
+	return { parsed: null, refusal: { json, summary: `${command}: ${lock.defects[0].message}`, exitCode: 1 } }
+}
+
+/**
+ * The source floor as a rule, or null for `standard`; a usage error for any other text.
+ * @returns {null | { kind: "primary" } | { kind: "pointed" | "classes", list: string[] }}
+ */
+export function parseSourceFloor(value) {
+	const text = value.trim()
+	for (const rule of SOURCE_FLOOR_RULES) {
+		const match = rule.pattern.exec(text)
+		if (!match) continue
+		if (rule.kind === "standard") return null
+		return rule.listed ? { kind: rule.kind, list: listOf(match[1]) } : { kind: rule.kind }
+	}
+	throw new CliError(`source floor "${value}" is not ${SOURCE_FLOOR_RULES.map((rule) => rule.form).join(", ")}`)
+}
+
+function hostOf(url) {
+	return typeof url === "string" && URL.canParse(url) ? new URL(url).hostname.toLowerCase() : null
+}
+
+/** Whether one source (id and meta.json) satisfies a parsed floor rule. */
+export function sourceInsideFloor(rule, sourceId, meta) {
+	if (rule.kind === "primary") return meta.provenance === "primary"
+	if (rule.kind === "pointed") return rule.list.includes(sourceId) || rule.list.includes(meta.url)
+	const host = hostOf(meta.url)
+	return host !== null && rule.list.some((entry) => host === entry.toLowerCase() || host.endsWith(`.${entry.toLowerCase()}`))
+}
+
+/** The fields fact fill consumes: the fallback form and whether a translation binds to its quote. */
+export function fillPolicy(parsed) {
+	const field = (name) => parsed.fields[name]
+	return {
+		fallback: FIDELITY_VALUE_RULES.fallback(field("fallback")),
+		translations: FIDELITY_VALUE_RULES.translations(field("languages")),
+		derivedNone: FIDELITY_VALUE_RULES.derivedNone(field("derived numbers")),
+		floor: parseSourceFloor(field("source floor")),
+	}
+}
+
+/** Source ids behind a row: its own, or for a derived row its operands' sources; null marks a leaf with no source. */
+function sourcesOf(row, rows, seen = new Set()) {
+	if (seen.has(row.fact_id)) return []
+	seen.add(row.fact_id)
+	if (row.source_id) return [row.source_id]
+	const inputs = [...(row.operands ?? []), ...(row.derived_from ?? [])]
+	if (inputs.length === 0) return [null]
+	return inputs.flatMap((id) => (rows.has(id) ? sourcesOf(rows.get(id), rows, seen) : [null]))
+}
+
+/** sha256 of the locked `## Fidelity` block normalized: the seven fields in FIDELITY_FIELDS order, `field: value` per line. */
+export const briefHashOf = (parsed) => sha256Of(FIDELITY_FIELDS.map((field) => `${field}: ${parsed.fields[field]}`).join("\n"))
+
+/** brief_changed when a fill map was not written under the current brief (or predates the binding). */
+export function briefBindingErrors(map, mapPath, parsed) {
+	if (map.brief_sha256 === briefHashOf(parsed)) return []
+	const why = typeof map.brief_sha256 === "string" ? "was filled under a different ## Fidelity block" : "records no brief_sha256"
+	return [{ code: "brief_changed", token: null, line: null, message: `${mapPath} ${why}; re-run fact fill under the current brief`, severity: DEFECT_CODES.brief_changed.severity, integrity: DEFECT_CODES.brief_changed.integrity, hint: DEFECT_CODES.brief_changed.hint }]
+}
+
+function metaOf(sessionDir, sourceId, cache) {
+	if (!cache.has(sourceId)) {
+		const file = join(sessionDir, "sources", sourceId, "meta.json")
+		cache.set(sourceId, existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : { url: null, provenance: "unknown" })
+	}
+	return cache.get(sourceId)
+}
+
+const defect = (code, pointer, text, message) => ({ code, token: pointer.token, line: lineOf(text, pointer.start), message, severity: DEFECT_CODES[code].severity, hint: DEFECT_CODES[code].hint })
+
+/**
+ * Refusals for the placeholders of one fill source (or the data-fact elements of one edition at
+ * verify). Sets each referenced row's outside_floor to this evaluation and reports whether any
+ * cached value changed.
+ * @param {{ token: string, start: number, parsed: { id?: string } }[]} found findPlaceholders output
+ * @returns {{ errors: object[], cacheChanged: boolean }}
+ */
+export function policyErrors(text, found, ledger, sessionDir, policy) {
+	const rows = new Map(ledger.rows.map((row) => [row.fact_id, row]))
+	const metas = new Map()
+	const errors = []
+	let cacheChanged = false
+	for (const pointer of found) {
+		const row = rows.get(pointer.parsed?.id)
+		if (row === undefined || row.status !== "active") continue
+		if (policy.derivedNone && FIDELITY_VALUE_RULES.derivedRefused(row.kind)) {
+			errors.push(defect("derived_not_allowed", pointer, text, `${row.fact_id} is ${row.kind}; the brief records derived numbers: none`))
+		}
+		const sources = sourcesOf(row, rows)
+		const outside = policy.floor === null ? [] : [...new Set(sources.filter((id) => id === null || !sourceInsideFloor(policy.floor, id, metaOf(sessionDir, id, metas))))]
+		if (row.outside_floor !== outside.length > 0) cacheChanged = true
+		row.outside_floor = outside.length > 0
+		const named = outside.map((id) => id ?? "no source").join(", ")
+		if (outside.length > 0) errors.push(defect("source_outside_floor", pointer, text, `${row.fact_id} rests on ${named}, outside the source floor`))
+	}
+	return { errors, cacheChanged }
+}