lazycodex-ai 5.1.46 → 5.1.48

package/packages/shared-skills/skills/ulw-research/scripts/copy-returns-fidelity-policy.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, test } from "bun:test"
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { FILL_INPUT_FORMAT_RULES, FILL_INPUT_FORMATS } from "./fact-commands-fill.mjs"
+import { KIND_RULES } from "./fact-ledger-kinds.mjs"
+import { FILL_FORMATS } from "./fact-fill.mjs"
+import { meaningCheckEnabled as briefMeaningCheckEnabled } from "./fidelity-brief.mjs"
+import { FIDELITY_VALUE_RULES, meaningCheckEnabled, parseSourceFloor, policyErrors, SOURCE_FLOOR_RULES, sourceInsideFloor } from "./fidelity-policy.mjs"
+
+type PolicyRow = { fact_id: string; kind: string; status: string; source_id: string | null; operands: string[]; derived_from: string[] }
+const policyRow = (fact_id: string, kind: string, source_id: string | null, operands: string[] = []): PolicyRow => ({ fact_id, kind, status: "active", source_id, operands, derived_from: [] })
+
+/** policyErrors over one placeholder per row id under a parsed floor, as code and message pairs. */
+function floorRefusals(rows: PolicyRow[], ids: string[], floor: ReturnType<typeof parseSourceFloor>) {
+	const found = ids.map((id, index) => ({ token: `{{${id}}}`, start: index, parsed: { id } }))
+	const refused = policyErrors(ids.map((id) => `{{${id}}}`).join(""), found, { rows }, tmpdir(), { derivedNone: false, floor })
+	return refused.errors.map((error: { code: string; message: string }) => [error.code, error.message])
+}
+
+const referenceValues = async (field: string) => {
+	const row = (await Bun.file(REFERENCE).text()).split("\n").find((line) => line.startsWith(`| \`${field}\` |`)) ?? ""
+	return [...(row.split("|")[2] ?? "").matchAll(/`([^`]+)`/gu)].map((match) => match[1])
+}
+import { pointedFlag } from "./source-commands.mjs"
+
+const REFERENCE = join(import.meta.dir, "..", "references", "deliverable-phase.md")
+
+function briefWithFloor(floor: string) {
+	const dir = mkdtempSync(join(tmpdir(), "policy-registry-"))
+	const lines = ["as of: latest at run start, 2026-10-23", "meaning check: on", `source floor: ${floor}`, "derived numbers: allowed", "languages: report en; sources en; quotes original", "identifier classes: none", "fallback: block-quote"]
+	writeFileSync(join(dir, "brief.md"), `## Fidelity\n${lines.map((line) => `${line} (answered_by: default)`).join("\n")}\n`)
+	return dir
+}
+
+const floorOf = (text: string) => {
+	const parsed = parseSourceFloor(text)
+	if (parsed === null) throw new Error(`parseSourceFloor(${text}) read no floor`)
+	return parsed
+}
+
+const derivedRefusal = (kind: string) => {
+	const row = { fact_id: "F1", kind, status: "active", source_id: null, operands: [], derived_from: [] }
+	const found = [{ token: "{{F1}}", start: 0, parsed: { id: "F1" } }]
+	const refused = policyErrors("{{F1}}", found, { rows: [row] }, tmpdir(), { derivedNone: true, floor: null })
+	return refused.errors.some((error: { code: string }) => error.code === "derived_not_allowed")
+}
+
+describe("fidelity-policy registry: copies must not return", () => {
+	test("#given every ledger kind #when derived numbers none refuses #then policyErrors agrees with FIDELITY_VALUE_RULES and assumed is refused", () => {
+		const kinds = Object.keys(KIND_RULES)
+		for (const kind of kinds) expect({ kind, refused: derivedRefusal(kind) }).toEqual({ kind, refused: FIDELITY_VALUE_RULES.derivedRefused(kind) })
+		for (const kind of FIDELITY_VALUE_RULES.derivedKinds) expect(kinds).toContain(kind)
+		expect(FIDELITY_VALUE_RULES.derivedRefused("assumed")).toBe(true)
+	})
+
+	test("#given each source floor form #when parsed #then the rule matches the registry and an unknown form is a usage error", () => {
+		expect(parseSourceFloor("standard")).toBeNull()
+		expect(parseSourceFloor("Primary Only")).toEqual({ kind: "primary" })
+		expect(parseSourceFloor("pointed only: S4, https://a.example/x")).toEqual({ kind: "pointed", list: ["S4", "https://a.example/x"] })
+		expect(parseSourceFloor("classes: example.com, gov.uk")).toEqual({ kind: "classes", list: ["example.com", "gov.uk"] })
+		for (const rule of SOURCE_FLOOR_RULES) expect(Object.isFrozen(rule)).toBe(true)
+		expect(() => parseSourceFloor("only nice sources")).toThrow(/source floor/)
+	})
+
+	test("#given pointed and classes floors #when evaluated #then ids, urls, hosts, and suffixes match and notexample.com does not", () => {
+		const pointed = floorOf("pointed only: S4, https://a.example/x")
+		expect(sourceInsideFloor(pointed, "S4", { url: null })).toBe(true)
+		expect(sourceInsideFloor(pointed, "S9", { url: "https://a.example/x" })).toBe(true)
+		expect(sourceInsideFloor(pointed, "S9", { url: "https://a.example/y" })).toBe(false)
+		const classes = floorOf("classes: example.com")
+		for (const [url, inside] of [["https://example.com/a", true], ["https://docs.example.com/a", true], ["https://notexample.com/a", false], [null, false]] as const) {
+			expect({ url, inside: sourceInsideFloor(classes, "S1", { url }) }).toEqual({ url, inside })
+		}
+		expect(sourceInsideFloor({ kind: "primary" }, "S1", { provenance: "primary" })).toBe(true)
+		expect(sourceInsideFloor({ kind: "primary" }, "S1", { provenance: "secondary" })).toBe(false)
+	})
+
+	test("#given a brief floor #when pointedFlag reads it #then it agrees with parseSourceFloor for every form", () => {
+		const url = "https://a.example/x"
+		for (const floor of ["pointed only: S4, https://a.example/x", "pointed only: S4", "standard", "primary only", "classes: a.example"]) {
+			const dir = briefWithFloor(floor)
+			try {
+				const rule = (() => {
+					try {
+						return parseSourceFloor(floor)
+					} catch {
+						return null
+					}
+				})()
+				expect({ floor, flag: pointedFlag(dir, url) }).toEqual({ floor, flag: rule?.kind === "pointed" && rule.list.includes(url) })
+			} finally {
+				rmSync(dir, { recursive: true, force: true })
+			}
+		}
+	})
+
+	test("#given a malformed or pending floor #when pointedFlag reads it #then malformed is a usage error and pending is not pointed", () => {
+		const malformed = briefWithFloor("not a floor")
+		const pending = mkdtempSync(join(tmpdir(), "policy-registry-"))
+		writeFileSync(join(pending, "brief.md"), "## Fidelity\nsource floor: pending (answered_by: pending)\n")
+		try {
+			expect(() => pointedFlag(malformed, "https://a.example/x")).toThrow(/source floor "not a floor"/)
+			expect(pointedFlag(pending, "https://a.example/x")).toBe(false)
+		} finally {
+			for (const dir of [malformed, pending]) rmSync(dir, { recursive: true, force: true })
+		}
+	})
+
+	test("#given derived numbers and fallback values #when read #then only their table values pass, any case, and anything else names field and value", () => {
+		expect(["none", "None", " none "].map((value) => FIDELITY_VALUE_RULES.derivedNone(value))).toEqual([true, true, true])
+		expect(["allowed", "Allowed"].map((value) => FIDELITY_VALUE_RULES.derivedNone(value))).toEqual([false, false])
+		for (const value of ["nope", "no", "n/a", "none.", "measured only"]) expect(() => FIDELITY_VALUE_RULES.derivedNone(value)).toThrow(`derived numbers "${value}" is not allowed, none`)
+		expect(["block-quote", "Omit"].map((value) => FIDELITY_VALUE_RULES.fallback(value))).toEqual(["quote", "omit"])
+		for (const value of ["drop", "omit sentence", "quote"]) expect(() => FIDELITY_VALUE_RULES.fallback(value)).toThrow(`fallback "${value}" is not block-quote, omit`)
+	})
+
+	test("#given the deliverable reference #when its derived numbers and fallback rows are read #then they name exactly the registry tables", async () => {
+		for (const [field, table] of Object.entries(FIDELITY_VALUE_RULES.tables)) expect({ field, values: await referenceValues(field) }).toEqual({ field, values: Object.keys(table) })
+		expect(Object.keys(FIDELITY_VALUE_RULES.tables)).toEqual(["derived numbers", "fallback"])
+	})
+
+	test("#given sourceless rows #when judged under a strict floor and under standard #then strict refuses each, a derived row over one included, and standard refuses none", () => {
+		const rows = [policyRow("F1", "measured", "S1"), policyRow("A1", "assumed", null), policyRow("D1", "derived", null, ["F1", "A1"]), policyRow("D2", "derived", null, ["F9"])]
+		const ids = ["F1", "A1", "D1", "D2"]
+		expect(floorRefusals(rows, ids, floorOf("pointed only: S1"))).toEqual([
+			["source_outside_floor", "A1 rests on no source, outside the source floor"],
+			["source_outside_floor", "D1 rests on no source, outside the source floor"],
+			["source_outside_floor", "D2 rests on no source, outside the source floor"],
+		])
+		expect(floorRefusals(rows, ids, parseSourceFloor("standard"))).toEqual([])
+	})
+
+	test("#given the meaning check value rule #when read through the policy or the brief #then both are the same function", () => {
+		expect(meaningCheckEnabled).toBe(briefMeaningCheckEnabled)
+		for (const value of ["on", "off", "Off", "on; force strong: money", "offline"]) {
+			expect({ value, on: FIDELITY_VALUE_RULES.meaningCheck(value) }).toEqual({ value, on: meaningCheckEnabled({ fields: { "meaning check": value } }) })
+		}
+	})
+
+	test("#given the fill input vocabulary #when derived #then every input maps to a FILL_FORMATS member and every output format is reachable", () => {
+		const target = (format: string) => (FILL_INPUT_FORMAT_RULES.aliases as Record<string, string>)[format] ?? format
+		for (const format of FILL_INPUT_FORMATS) expect(FILL_FORMATS as readonly string[]).toContain(target(format))
+		for (const format of FILL_FORMATS) expect(FILL_INPUT_FORMATS as readonly string[]).toContain(format)
+		for (const format of Object.values(FILL_INPUT_FORMAT_RULES.extensions)) expect(FILL_INPUT_FORMATS as readonly string[]).toContain(format)
+		expect(FILL_INPUT_FORMAT_RULES.aliases).toEqual({ tex: "md" })
+	})
+
+	test("#given the deliverable reference #when its source floor row is read #then it names exactly the SOURCE_FLOOR_RULES forms", async () => {
+		const row = (await Bun.file(REFERENCE).text()).split("\n").find((line) => line.startsWith("| `source floor` |")) ?? ""
+		const values = row.split("|")[2] ?? ""
+		const forms = [...values.matchAll(/`([^`]+)`/gu)].map((match) => match[1])
+		expect(forms).toEqual(SOURCE_FLOOR_RULES.map((rule) => rule.form))
+	})
+})

package/packages/shared-skills/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, "--brief", BRIEF, "--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, "--brief", BRIEF, ...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, "--brief", BRIEF, "--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, "--brief", BRIEF]) 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, "--brief", BRIEF, "--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, "--brief", BRIEF, "--out", join(dir, "fmt.html"), "--format", "md"]))
+		expect(result).toContain("takes the filled HTML edition")
+	})
+})

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

@@ -0,0 +1,86 @@
+// fact-commands-fill.mjs - `fact fill`, the reader-facing fill of a placeholder source.
+//
+// It refuses an unlocked brief (fidelity_interview_incomplete) and applies the locked `## Fidelity`
+// fields: `derived numbers: none` and the source floor refuse rows (derived_not_allowed,
+// source_outside_floor, evaluated at every fill), `languages` decides whether a translation after a
+// quote binds to it, and `fallback` picks the block quote or omission for --replace-failed. Any
+// error writes no edition, fill map, or state; the one write that survives a refusal is the
+// ledger's cached outside_floor per row (skipped under --view). The fill map records brief_sha256,
+// the locked block fact verify checks it against. node: builtins and sibling imports only.
+
+import { readFileSync, writeFileSync } from "node:fs"
+import { dirname, extname, resolve } from "node:path"
+
+import { CliError, sha256Of, writeJsonAtomic } from "./cli-support.mjs"
+import { DEFECT_CODES } from "./contracts.mjs"
+import { FILL_FORMATS, fill } from "./fact-fill.mjs"
+import { readLedger, writeLedger } from "./fact-ledger.mjs"
+import { briefHashOf, fillPolicy, lockedBrief, policyErrors } from "./fidelity-policy.mjs"
+import { readState, writeState } from "./fidelity-state.mjs"
+import { findPlaceholders } from "./placeholder.mjs"
+import { sessionDirOf } from "./source-commands.mjs"
+
+/** The CLI's input vocabulary: fill's output formats plus aliases (tex is filled as md), and the extension defaults. */
+export const FILL_INPUT_FORMAT_RULES = Object.freeze({
+	aliases: Object.freeze({ tex: "md" }),
+	extensions: Object.freeze({ ".md": "md", ".tex": "tex" }),
+})
+export const FILL_INPUT_FORMATS = Object.freeze([...FILL_FORMATS, ...Object.keys(FILL_INPUT_FORMAT_RULES.aliases)])
+const fillFormatOf = (format) => FILL_INPUT_FORMAT_RULES.aliases[format] ?? format
+
+function readText(path) {
+	try {
+		return readFileSync(path, "utf8")
+	} catch (error) {
+		throw new CliError(`cannot read ${path}: ${error.code ?? error.message}`)
+	}
+}
+
+/** 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))
+}
+
+/** @param {{ positionals: string[], flags: Record<string, any> }} args parsed by runFact */
+export function runFactFill(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] [--brief brief.md]")
+	const format = flags.format ?? FILL_INPUT_FORMAT_RULES.extensions[extname(source).toLowerCase()] ?? "html"
+	if (!FILL_INPUT_FORMATS.includes(format)) throw new CliError(`--format must be ${FILL_INPUT_FORMATS.slice(0, -1).join(", ")}, or ${FILL_INPUT_FORMATS.at(-1)}`)
+	if (flags.inline && format !== "html") throw new CliError("--inline applies to the html edition only")
+	const sessionDir = sessionDirOf(flags)
+	const { parsed, refusal } = lockedBrief("fact fill", flags)
+	if (refusal) return refusal
+	const policy = fillPolicy(parsed)
+	const text = readText(source)
+	const ledger = readLedger(sessionDir)
+	const refused = policyErrors(text, findPlaceholders(text), ledger, sessionDir, policy)
+	if (refused.cacheChanged && !flags.view) writeLedger(sessionDir, ledger)
+	const state = flags["replace-failed"] ? readState(sessionDir) : null
+	const result = fill(text, ledger, { format: fillFormatOf(format), view: flags.view === true, fallback: policy.fallback, ...(state ? { replaceFailed: state } : {}) })
+	const warnings = result.warnings
+	if (result.out === null || refused.errors.length > 0) {
+		const filled = result.errors.map((error) => ({ ...error, severity: DEFECT_CODES[error.code]?.severity ?? "blocker", hint: DEFECT_CODES[error.code]?.hint ?? null }))
+		const defects = [...refused.errors, ...filled]
+		return { json: { command: "fact fill", status: "fail", exitCode: 1, defects, warnings }, summary: `fact fill: FAIL - ${defects.length} error(s), nothing written`, exitCode: 1 }
+	}
+	const entries = policy.translations ? result.fillMap : result.fillMap.filter((entry) => entry.translates === undefined)
+	const out = flags.inline ? inlineAssets(result.out, dirname(resolve(source))) : result.out
+	if (flags.view) return { text: out, summary: `fact fill --view: ${entries.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`
+	const brief = briefHashOf(parsed)
+	writeJsonAtomic(map, { schemaVersion: 1, format, artifact: resolve(flags.out), artifact_sha256: artifact, brief_sha256: brief, entries })
+	const data = { out: resolve(flags.out), map, artifact_sha256: artifact, brief_sha256: brief, occurrences: entries.length, warnings }
+	return { json: { command: "fact fill", status: "pass", exitCode: 0, defects: [], data }, summary: `fact fill: wrote ${flags.out} (${entries.length} pointer(s))`, exitCode: 0 }
+}

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

@@ -1,24 +1,26 @@
 // 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; it honours the brief's `meaning check` field and writes
+// 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.
+// instead of counting a second run. Both refuse an unlocked brief (fidelity_interview_incomplete) before
+// reading anything else. 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 { markdownAsHtml, readEdition } from "./fact-commands-verify.mjs"
-import { readLedger } from "./fact-ledger.mjs"
-import { validateLedger } from "./fact-ledger-schema.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 { FIDELITY_INCOMPLETE } from "./fidelity-brief.mjs"
+import { briefPathOf, lockedBrief, meaningCheckEnabled } from "./fidelity-policy.mjs"
 import { MEANING_RECORD, writeFidelityRecord } from "./fidelity-records.mjs"
 import { blocksDelivery } from "./gates-fidelity.mjs"
 import { ingestVerdicts, unverifiedDefects, VERDICT_SCHEMA } from "./meaning-check.mjs"
@@ -31,45 +33,20 @@ export const PROMOTION = Object.freeze({ code: "meaning_drift_confirmed", to: "i
 /** The command status: fail when any defect blocks delivery under the registry policy. */
 export const meaningStatus = (defects) => (defects.some(blocksDelivery) ? "fail" : "pass")
 
-const sessionOf = (flags) => {
-	const dir = flags["session-dir"] ?? process.env.SESSION_DIR
-	return dir && dir !== true ? resolve(dir) : null
-}
 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 readLedgerFrom(flags, session) {
-	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
-}
-
-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 { parsed, refusal } = lockedBrief("fact pairs", flags)
+	if (refusal) return refusal
+	if (!meaningCheckEnabled(parsed)) {
 		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 }
@@ -77,10 +54,10 @@ function runPairs(args) {
 	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 changed = flags["changed-since"] === undefined ? undefined : readJsonFile(flags["changed-since"]).entries
-	const ledger = readLedgerFrom(flags, session)
+	const ledger = ledgerFrom(flags, session)
 	const html = edition.format === "md" ? markdownAsHtml(edition.text, edition.entries, ledger).html : edition.text
-	const pairs = extractPairs(html, ledger, claims, changed)
+	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 }
@@ -140,23 +117,23 @@ function recordCalibration(path, lines, runId, pairsSha) {
 }
 
 /** 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` }
+function skippedRefusal(flags, parsed) {
+	if (meaningCheckEnabled(parsed)) return { error: "meaning_check_required", message: `${flags.pairs} says skipped but ${briefPathOf(flags)} 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]"
+	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] [--brief brief.md] [--out F]"
 	if (flags.pairs === undefined || !Array.isArray(flags.verdicts)) throw new CliError(usage)
 	const session = sessionOf(flags)
+	const { parsed, refusal } = lockedBrief("fact meaning-check", flags)
+	if (refusal) return { ...refusal, json: { ...refusal.json, error: FIDELITY_INCOMPLETE } }
 	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 }
+		const skipped = skippedRefusal(flags, parsed)
+		if (skipped !== null) return { json: { command: "fact meaning-check", status: "fail", exitCode: 1, ...skipped }, summary: `fact meaning-check: ${skipped.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`)