lazycodex-ai 5.1.45 → 5.1.46

package/packages/shared-skills/skills/ulw-research/scripts/meaning-check.test.ts

@@ -0,0 +1,228 @@
+import { 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 { DRIFT_KINDS, ingestVerdicts } from "./meaning-check.mjs"
+
+type Verdict = Record<string, unknown>
+type Result = {
+	defects: { code: string; severity: string; integrity: boolean; pair_id: string; drift_kind: string; fragment: string; source_fragment: string }[]
+	dropped: { pair_id: string | null; reason: string; model_tier: string | null; file: string }[]
+	unverified: { pair_id: string; reason: string }[]
+	calibrationLines: string[]
+}
+
+const PAIRS = [
+	{ pair_id: "P1", kind: "quote", sentence_key: "findings#Q1", fact_ids: ["Q1"], quote: "The pilot covered North America.", sentence: "The rollout was worldwide.", force_strong: true },
+	{ pair_id: "P2", kind: "claim", claim_id: "C2", statement: "Revenue may grow in 2026.", sentence: "Revenue will grow in 2026.", force_strong: true },
+]
+
+const base = (tier: string, extra: Verdict = {}): Verdict => ({
+	pair_id: "P1",
+	verdict: "drift",
+	drift_kind: "scope_widened",
+	fragment: "worldwide",
+	source_fragment: "North America",
+	explanation: "The assertion broadens the reported region.",
+	model_tier: tier,
+	...extra,
+})
+
+let dir = ""
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "meaning-check-"))
+})
+afterEach(() => {
+	rmSync(dir, { recursive: true, force: true })
+})
+
+function file(name: string, verdicts: Verdict[]): string {
+	const path = join(dir, name)
+	writeFileSync(path, JSON.stringify(verdicts))
+	return path
+}
+
+function run(cheap: Verdict[], strong: Verdict[] = [], options: object = {}): Result {
+	return ingestVerdicts(PAIRS, [file("cheap.json", cheap), file("strong.json", strong)], options) as Result
+}
+
+describe("ingestVerdicts: tier agreement", () => {
+	test("#given cheap and strong agree on scope_widened #when ingested #then meaning_drift_confirmed (major, non-integrity)", () => {
+		const result = run([base("cheap")], [base("strong")])
+		expect(result.defects).toHaveLength(1)
+		expect(result.defects[0]).toMatchObject({ code: "meaning_drift_confirmed", severity: "major", integrity: false, pair_id: "P1", drift_kind: "scope_widened" })
+		expect(result.dropped).toEqual([])
+	})
+
+	test("#given only the cheap tier flags #when ingested #then meaning_drift_warn (minor)", () => {
+		const result = run([base("cheap")])
+		expect(result.defects.map((d) => [d.code, d.severity])).toEqual([["meaning_drift_warn", "minor"]])
+	})
+
+	test("#given both tiers agree on other #when ingested #then warn only, never confirmed", () => {
+		const result = run([base("cheap", { drift_kind: "other" })], [base("strong", { drift_kind: "other" })])
+		expect(result.defects.map((d) => d.code)).toEqual(["meaning_drift_warn"])
+	})
+
+	test("#given the tiers name different drift kinds #when ingested #then warn only", () => {
+		const result = run([base("cheap")], [base("strong", { drift_kind: "subject_changed" })])
+		expect(result.defects.map((d) => d.code)).toEqual(["meaning_drift_warn"])
+	})
+
+	test("#given an ok verdict #when ingested #then no defect and no calibration line", () => {
+		const result = run([{ pair_id: "P1", verdict: "ok", model_tier: "cheap" }])
+		expect(result.defects).toEqual([])
+		expect(result.calibrationLines).toEqual([])
+	})
+
+	test("#given a claim pair #when both tiers agree on evidence_grade_raised #then confirmed against the statement", () => {
+		const verdict = { pair_id: "P2", verdict: "drift", drift_kind: "evidence_grade_raised", fragment: "will grow", source_fragment: "may grow", explanation: "certainty raised" }
+		const result = run([{ ...verdict, model_tier: "cheap" }], [{ ...verdict, model_tier: "strong" }])
+		expect(result.defects.map((d) => [d.code, d.pair_id])).toEqual([["meaning_drift_confirmed", "P2"]])
+	})
+})
+
+describe("ingestVerdicts: grounding drops", () => {
+	test("#given a fragment that is not in the sentence #when ingested #then dropped and counted, no defect", () => {
+		const result = run([base("cheap", { fragment: "Europe" })])
+		expect(result.defects).toEqual([])
+		expect(result.dropped).toHaveLength(1)
+		expect(result.dropped[0]).toMatchObject({ pair_id: "P1", reason: "fragment_not_found", model_tier: "cheap" })
+	})
+
+	test("#given a source fragment that is not in the quote #when ingested #then dropped", () => {
+		const result = run([base("cheap", { source_fragment: "Asia" })])
+		expect(result.defects).toEqual([])
+		expect(result.dropped.map((d) => d.reason)).toEqual(["source_fragment_not_found"])
+	})
+
+	test("#given empty or blank fragments #when ingested #then dropped as empty", () => {
+		const result = run([base("cheap", { fragment: "" })], [base("strong", { source_fragment: "   " })])
+		expect(result.defects).toEqual([])
+		expect(result.dropped.map((d) => d.reason)).toEqual(["empty_fragment", "empty_fragment"])
+	})
+
+	test("#given an unknown drift_kind #when ingested #then dropped", () => {
+		const result = run([base("cheap", { drift_kind: "tone_shifted" })])
+		expect(result.defects).toEqual([])
+		expect(result.dropped.map((d) => d.reason)).toEqual(["unknown_drift_kind"])
+	})
+
+	test("#given an unknown pair id or tier #when ingested #then dropped", () => {
+		const result = run([base("cheap", { pair_id: "P99" }), base("medium")])
+		expect(result.dropped.map((d) => d.reason)).toEqual(["unknown_pair", "invalid_model_tier"])
+	})
+
+	test("#given extra whitespace in a fragment #when ingested #then it still grounds", () => {
+		const result = run([base("cheap", { fragment: "rollout \n  was", source_fragment: " North  America " })])
+		expect(result.dropped).toEqual([])
+		expect(result.defects.map((d) => d.code)).toEqual(["meaning_drift_warn"])
+	})
+
+	test("#given the closed drift_kind set #when read #then it holds exactly the nine kinds", () => {
+		expect([...DRIFT_KINDS]).toEqual([
+			"subject_changed", "scope_widened", "hedge_dropped", "certainty_added", "causality_added",
+			"direction_flipped", "population_changed", "evidence_grade_raised", "other",
+		])
+	})
+})
+
+describe("ingestVerdicts: calibration log", () => {
+	test("#given a dispute on a confirmed pair #when ingested #then the defect stays and the line records disputed:true", () => {
+		const result = run([base("cheap")], [base("strong")], { dispute: { pair_id: "P1", reason: "Scope is justified by a second observation." } })
+		expect(result.defects.map((d) => d.code)).toEqual(["meaning_drift_confirmed"])
+		expect(result.calibrationLines.map((line) => JSON.parse(line))).toEqual([
+			{ kind: "quote", pair_id: "P1", tiers: ["cheap", "strong"], drift_kind: "scope_widened", confirmed: true, disputed: true, reason: "Scope is justified by a second observation." },
+		])
+	})
+
+	test("#given two flagged pairs and one ok verdict #when ingested with a calibration path #then exactly one line per flagged pair is appended", () => {
+		const calibrationPath = join(dir, "fidelity-calibration.jsonl")
+		const claimDrift = { pair_id: "P2", verdict: "drift", drift_kind: "certainty_added", fragment: "will", source_fragment: "may", explanation: "x", model_tier: "cheap" }
+		const cheap = [base("cheap"), claimDrift, { pair_id: "P1", verdict: "ok", model_tier: "cheap" }]
+		const first = run(cheap, [], { calibrationPath })
+		expect(first.calibrationLines).toHaveLength(2)
+		const lines = () => readFileSync(calibrationPath, "utf8").split("\n").filter(Boolean)
+		expect(lines()).toHaveLength(2)
+		expect(JSON.parse(lines()[1])).toEqual({ kind: "claim", pair_id: "P2", tiers: ["cheap"], drift_kind: "certainty_added", confirmed: false, disputed: false, reason: null })
+		run(cheap, [], { calibrationPath })
+		expect(lines()).toHaveLength(4)
+	})
+})
+
+describe("ingestVerdicts: coverage", () => {
+	test("#given a pair no reader judged #when ingested #then it is reported as unverified, never as clean", () => {
+		const result = run([base("cheap")], [base("strong")])
+		expect(result.unverified).toEqual([{ pair_id: "P2", reason: "no_verdict" }])
+	})
+
+	test("#given a force_strong pair with only a cheap verdict #when ingested #then unverified says no_strong_verdict", () => {
+		const result = run([base("cheap"), { pair_id: "P2", verdict: "ok", model_tier: "cheap" }])
+		expect(result.unverified).toEqual([
+			{ pair_id: "P1", reason: "no_strong_verdict" },
+			{ pair_id: "P2", reason: "no_strong_verdict" },
+		])
+	})
+
+	test("#given every pair read by both tiers #when ingested #then unverified is empty", () => {
+		const ok = (pair_id: string, tier: string): Verdict => ({ pair_id, verdict: "ok", model_tier: tier })
+		const result = run([ok("P1", "cheap"), ok("P2", "cheap")], [ok("P1", "strong"), ok("P2", "strong")])
+		expect(result.unverified).toEqual([])
+		expect(result.defects).toEqual([])
+	})
+
+	test("#given only dropped verdicts on a pair #when ingested #then the pair counts as unread", () => {
+		const result = run([base("cheap", { fragment: "Europe" })], [base("strong", { fragment: "Europe" })])
+		expect(result.unverified.map((entry) => entry.pair_id)).toEqual(["P1", "P2"])
+	})
+})
+
+describe("ingestVerdicts: the reported fragment", () => {
+	test("#given an earlier other verdict #when the tiers agree on a later kind #then the fragment comes from the agreed verdict", () => {
+		const other = base("cheap", { drift_kind: "other", fragment: "The rollout", source_fragment: "The pilot" })
+		const result = run([other, base("cheap")], [base("strong")])
+		expect(result.defects).toHaveLength(1)
+		expect(result.defects[0]).toMatchObject({ code: "meaning_drift_confirmed", drift_kind: "scope_widened", fragment: "worldwide", source_fragment: "North America" })
+	})
+})
+
+describe("ingestVerdicts: determinism", () => {
+	test("#given the same verdicts twice #when ingested #then both results are byte-for-byte equal", () => {
+		const cheap = [base("cheap"), { pair_id: "P2", verdict: "drift", drift_kind: "certainty_added", fragment: "will grow", source_fragment: "may grow", model_tier: "cheap" }, base("medium")]
+		const strong = [base("strong")]
+		const first = JSON.stringify(run(cheap, strong))
+		const second = JSON.stringify(run(cheap, strong))
+		expect(second).toBe(first)
+	})
+})
+
+describe("ingestVerdicts: unreadable verdict files", () => {
+	test("#given a missing verdict file #when ingested #then a short typed error names the file", () => {
+		const missing = join(dir, "absent.json")
+		expect(() => ingestVerdicts(PAIRS, [missing])).toThrow(TypeError)
+		expect(() => ingestVerdicts(PAIRS, [missing])).toThrow(/absent\.json: cannot read the verdict file/u)
+	})
+
+	test("#given invalid JSON #when ingested #then a short typed error names the file", () => {
+		const path = join(dir, "broken.json")
+		writeFileSync(path, "{ not json")
+		expect(() => ingestVerdicts(PAIRS, [path])).toThrow(/broken\.json: the verdict file is not valid JSON/u)
+	})
+})
+
+describe("ingestVerdicts: malformed pairs input", () => {
+	test("#given a missing or malformed pairs input #when ingested #then it refuses instead of reporting a clean result", () => {
+		for (const bad of [undefined, null, {}, { pairs: "P1" }, "pairs.json", 7]) {
+			expect(() => ingestVerdicts(bad as never, []), JSON.stringify(bad)).toThrow(TypeError)
+		}
+		expect(ingestVerdicts({ pairs: [] }, []).unverified).toEqual([])
+	})
+})
+
+describe("ingestVerdicts: the no-model contract", () => {
+	test("#given the module source #when read #then it never fetches or imports a network or model client", () => {
+		const text = readFileSync(join(import.meta.dir, "meaning-check.mjs"), "utf8")
+		expect(text).not.toMatch(/\bfetch\s*\(|node:https?|node:net|from\s+"(?!\.\/|node:)/u)
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/outcome.mjs

@@ -1,6 +1,5 @@
-// outcome.mjs - the per-run outcome manifest (`outcome.json`) and the closing briefing.
-// Manifest functions are pure (they return a new manifest); the briefing reads only the
-// manifest, the sources-ledger text, and an injected `now`. node: builtins only.
+// outcome.mjs - the per-run outcome manifest (`outcome.json`) and the closing briefing. Manifest functions are pure (they return a new manifest).
+// The briefing reads only the manifest, the sources-ledger text, and an injected `now`. node: builtins only.
 
 import * as nodeFs from "node:fs"
 import { basename, dirname, join } from "node:path"
@@ -86,7 +85,7 @@ export function setDeliverable(manifest, format, status, detail = {}) {
 	const next = clone(manifest)
 	const index = next.deliverables.findIndex((row) => row.format === format)
 	const row = { format, status, promised: index >= 0 ? next.deliverables[index].promised : false, updatedAt: stamp(detail.now) }
-	for (const key of ["path", "reason", "pages", "bytes"]) {
+	for (const key of ["path", "reason", "pages", "bytes", "verifiedBy", "renderedFrom"]) {
 		if (detail[key] !== undefined) row[key] = detail[key]
 	}
 	if (index >= 0) next.deliverables[index] = row
@@ -94,11 +93,13 @@ export function setDeliverable(manifest, format, status, detail = {}) {
 	return next
 }
 
-export function setGate(manifest, gate, status) {
+export function setGate(manifest, gate, status, detail = {}) {
 	assertOneOf("unknown_gate", "gate", gate, GATE_NAMES)
 	assertOneOf("unknown_gate_status", "gate status", status, GATE_STATUSES)
+	if (gate === "fidelity" && status === "not_run" && (typeof detail.reason !== "string" || !detail.reason.trim())) throw new OutcomeError("gate_reason_required", "fidelity not_run requires a non-empty --reason")
 	const next = clone(manifest)
 	next.gates[gate] = status
+	next.gateHistory = [...(next.gateHistory ?? []), { gate, status, ...(detail.reason !== undefined ? { reason: detail.reason.trim() } : {}), at: stamp(detail.now) }]
 	return next
 }
 

package/packages/shared-skills/skills/ulw-research/scripts/placeholder.mjs

@@ -0,0 +1,184 @@
+// placeholder.mjs - the fact pointer grammar of the fill step and its render helpers.
+// Value pointers: {{F12:label}}, {{F12:label:value}}, {{F12:label:unit}}, {{F12:label:q}}.
+// Quote pointers: {{Q7:label}}, {{Q7:label:lead=18}}, {{Q7:label:from="x":to="y"}} (anchors are
+// JSON strings, so they may hold a colon or an escaped quote). Labels are compared exactly by the
+// caller; this module never guesses an id. Pure functions; node: builtins only.
+
+import { parseNumeral } from "./numerals.mjs"
+
+export const ELLIPSIS = "\u2026"
+
+const ID = /^([FQ])\d+$/
+const LABEL = /^[^\s:{}"]+$/
+const VALUE_MODES = new Set(["value", "unit", "q"])
+const LEAD = /^lead=([1-9]\d*)$/
+const LINEAGE = Object.freeze({ measured: "MEASURED", assumed: "ASSUMED", derived: "DERIVED", converted: "DERIVED" })
+
+/** End index (exclusive) of a JSON string starting at `at`, or -1 when it is not closed on its line. */
+function jsonStringEnd(text, at) {
+	let i = at + 1
+	while (i < text.length && text[i] !== '"' && text[i] !== "\n") i += text[i] === "\\" ? 2 : 1
+	return text[i] === '"' ? i + 1 : -1
+}
+
+function readJsonString(text, at) {
+	if (text[at] !== '"') return null
+	const end = jsonStringEnd(text, at)
+	if (end === -1) return null
+	try {
+		return { value: JSON.parse(text.slice(at, end)), end }
+	} catch {
+		return null
+	}
+}
+
+function parseAnchors(tail) {
+	if (!tail.startsWith("from=")) return null
+	const from = readJsonString(tail, 5)
+	if (from === null || !tail.startsWith(":to=", from.end)) return null
+	const to = readJsonString(tail, from.end + 4)
+	if (to === null || to.end !== tail.length || from.value === "" || to.value === "") return null
+	return { from: from.value, to: to.value }
+}
+
+/** @returns the parsed pointer, or { error } for a malformed one. */
+export function parsePlaceholder(token) {
+	if (!token.startsWith("{{") || !token.endsWith("}}")) return { error: "a placeholder is {{ID:label...}}" }
+	const body = token.slice(2, -2)
+	const colon = body.indexOf(":")
+	const id = colon === -1 ? body : body.slice(0, colon)
+	const idMatch = ID.exec(id)
+	if (idMatch === null) return { error: `"${id}" is not an F<n> or Q<n> id` }
+	if (colon === -1) return { error: `${id} has no label; write {{${id}:label}}` }
+	const rest = body.slice(colon + 1)
+	const second = rest.indexOf(":")
+	const label = second === -1 ? rest : rest.slice(0, second)
+	if (!LABEL.test(label)) return { error: `"${label}" is not a label` }
+	const tail = second === -1 ? null : rest.slice(second + 1)
+	const base = { id, kind: idMatch[1], label }
+	if (idMatch[1] === "F") {
+		if (tail === null) return { ...base, mode: "full" }
+		return VALUE_MODES.has(tail) ? { ...base, mode: tail } : { error: `"${tail}" is not a value mode (value, unit, q)` }
+	}
+	if (tail === null) return { ...base, mode: "full", selector: "full" }
+	const lead = LEAD.exec(tail)
+	if (lead !== null) return { ...base, mode: "lead", lead: Number(lead[1]), selector: `lead=${lead[1]}` }
+	const anchors = parseAnchors(tail)
+	if (anchors === null) return { error: `"${tail}" is not a quote selector (lead=N or from="..":to="..")` }
+	return { ...base, mode: "span", ...anchors, selector: `from=${anchors.from};to=${anchors.to}` }
+}
+
+/** End index (exclusive) of the pointer opened at `at`, or -1 when it is not closed on its line. */
+function placeholderEnd(text, at) {
+	let i = at + 2
+	while (i < text.length && text[i] !== "\n") {
+		if (text[i] === '"') {
+			const end = jsonStringEnd(text, i)
+			if (end === -1) return -1
+			i = end
+		} else if (text.startsWith("}}", i)) return i + 2
+		else i++
+	}
+	return -1
+}
+
+/** Every `{{...}}` pointer in source order: [{ token, start, end, parsed }]. */
+export function findPlaceholders(text) {
+	const found = []
+	let at = text.indexOf("{{")
+	while (at !== -1) {
+		const end = placeholderEnd(text, at)
+		if (end === -1) {
+			found.push({ token: text.slice(at, text.indexOf("\n", at) === -1 ? text.length : text.indexOf("\n", at)), start: at, end: at + 2, parsed: { error: "the placeholder is not closed on its line" } })
+			at = text.indexOf("{{", at + 2)
+			continue
+		}
+		const token = text.slice(at, end)
+		found.push({ token, start: at, end, parsed: parsePlaceholder(token) })
+		at = text.indexOf("{{", end)
+	}
+	return found
+}
+
+function occurrences(text, needle) {
+	let count = 0
+	for (let at = text.indexOf(needle); at !== -1; at = text.indexOf(needle, at + 1)) count++
+	return count
+}
+
+function cut(quote, start, end) {
+	return { text: `${start > 0 ? ELLIPSIS : ""}${quote.slice(start, end)}${end < quote.length ? ELLIPSIS : ""}`, start, end }
+}
+
+/** The contiguous span from `from` through `to`; each anchor must occur exactly once, in order. */
+export function subSpan(quote, from, to) {
+	if (occurrences(quote, from) !== 1 || occurrences(quote, to) !== 1) return null
+	const start = quote.indexOf(from)
+	const toAt = quote.indexOf(to)
+	if (toAt < start || toAt + to.length < start + from.length) return null
+	return cut(quote, start, toAt + to.length)
+}
+
+/** The first `n` whitespace-delimited words, with an ellipsis when words were cut. */
+export function lead(quote, n) {
+	const words = [...quote.matchAll(/\S+/g)]
+	if (words.length <= n) return { text: quote, start: 0, end: quote.length }
+	const last = words[n - 1]
+	return cut(quote, 0, last.index + last[0].length)
+}
+
+/** The value and unit parts of a row's raw text ("4.2 eok won" -> value "4.2 eok", unit "won"). */
+export function valueParts(row) {
+	const unitText = parseNumeral(row.raw)?.unitRaw ?? row.unit
+	const valueText = unitText && row.raw.endsWith(unitText) ? row.raw.slice(0, -unitText.length).trimEnd() : (row.value ?? row.raw)
+	return { valueText, unitText: unitText ?? "" }
+}
+
+/** The quote interval holding the row's qualifier and its raw quantity, or null if absent. */
+export function qualifiedText(row) {
+	if (row.qualifier === null) return row.raw
+	for (let numeral = parseNumeral(row.quote); numeral !== null; numeral = parseNumeral(row.quote, numeral.span[1])) {
+		if (numeral.raw !== row.raw || numeral.qualifierRaw === null) continue
+		const [start, end] = numeral.span
+		const before = row.quote.lastIndexOf(numeral.qualifierRaw, start)
+		const between = before === -1 ? [] : row.quote.slice(before + numeral.qualifierRaw.length, start).split(/\s+/u).filter(Boolean)
+		if (before !== -1 && between.length <= 1) return row.quote.slice(before, end)
+		const after = row.quote.indexOf(numeral.qualifierRaw, end)
+		if (after !== -1) return row.quote.slice(start, after + numeral.qualifierRaw.length)
+	}
+	return null
+}
+
+export function escapeHtml(text) {
+	return String(text).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;")
+}
+
+/** The elements the renderers below emit as fact spans; recognizers build their patterns from this. */
+export const FACT_ELEMENT_TAGS = Object.freeze(["data", "q", "blockquote"])
+
+export function renderValueHtml(row, text) {
+	const unit = row.unit === null ? "" : ` data-unit="${escapeHtml(row.unit)}"`
+	return `<data class="fact" value="${escapeHtml(row.value)}" data-fact="${row.fact_id}"${unit} data-lineage="${LINEAGE[row.kind]}">${escapeHtml(text)}</data>`
+}
+
+export function renderQuote(row, selector, text, format) {
+	const marker = `[${row.source_id}]`
+	if (format === "md") return `"${text}" ${marker}`
+	return `<q data-fact="${row.fact_id}" data-quote-sel="${escapeHtml(selector)}">${escapeHtml(text)}</q> ${marker}`
+}
+
+const RENDERED_MD_QUOTE = /^"([\s\S]*)" (\[S\d+\])$/u
+
+/** The quote text and source marker of bytes renderQuote wrote for md, or null for any other layout. */
+export function parseRenderedQuote(body) {
+	const match = RENDERED_MD_QUOTE.exec(body)
+	return match ? { text: match[1], marker: match[2] } : null
+}
+
+/** The attributed block that replaces a twice-failed sentence; entity and valid_at stay outside the quote. */
+export function renderBlockquote(row, key, format) {
+	const attribution = row.entity === null ? "" : `, on ${row.entity}${row.valid_at === null ? "" : ` (${row.valid_at})`}`
+	const footer = `[${row.source_id}]${attribution}`
+	if (format === "md") return `> "${row.quote}"\n> ${footer}`
+	return `<blockquote data-fact="${row.fact_id}" data-replaced="${escapeHtml(key)}">"${escapeHtml(row.quote)}" <footer>${escapeHtml(footer)}</footer></blockquote>`
+}

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

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test"
+
+import { findPlaceholders, lead, parsePlaceholder, subSpan } from "./placeholder.mjs"
+
+const QUOTE = "we estimate completion no earlier than 2027"
+
+describe("parsePlaceholder", () => {
+	test("value pointers: full, value, unit, q", () => {
+		expect(parsePlaceholder("{{F12:span_len}}")).toEqual({ id: "F12", kind: "F", label: "span_len", mode: "full" })
+		expect(parsePlaceholder("{{F12:span_len:value}}")).toEqual({ id: "F12", kind: "F", label: "span_len", mode: "value" })
+		expect(parsePlaceholder("{{F12:span_len:unit}}")).toEqual({ id: "F12", kind: "F", label: "span_len", mode: "unit" })
+		expect(parsePlaceholder("{{F12:span_len:q}}")).toEqual({ id: "F12", kind: "F", label: "span_len", mode: "q" })
+	})
+
+	test("quote pointers: full, lead, from/to with JSON anchors", () => {
+		expect(parsePlaceholder("{{Q7:completion}}")).toEqual({ id: "Q7", kind: "Q", label: "completion", mode: "full", selector: "full" })
+		expect(parsePlaceholder("{{Q7:completion:lead=18}}")).toEqual({ id: "Q7", kind: "Q", label: "completion", mode: "lead", lead: 18, selector: "lead=18" })
+		expect(parsePlaceholder('{{Q7:completion:from="no earlier":to="2027"}}')).toEqual({
+			id: "Q7",
+			kind: "Q",
+			label: "completion",
+			mode: "span",
+			from: "no earlier",
+			to: "2027",
+			selector: "from=no earlier;to=2027",
+		})
+	})
+
+	test("an anchor may contain a colon or an escaped quote", () => {
+		const parsed = parsePlaceholder('{{Q7:c:from="a:b":to="say \\"x\\""}}')
+		expect(parsed).toMatchObject({ mode: "span", from: "a:b", to: 'say "x"' })
+	})
+
+	test("malformed pointers carry an error and no id guess", () => {
+		for (const token of ["{{F12}}", "{{X1:a}}", "{{F12:a:lead=3}}", "{{Q7:a:value}}", "{{Q7:a:lead=0}}", '{{Q7:a:from="":to="b"}}', '{{Q7:a:from="a"}}', "{{F12:a:b:c}}"]) {
+			expect(parsePlaceholder(token)).toHaveProperty("error")
+		}
+	})
+})
+
+describe("findPlaceholders", () => {
+	test("returns every token with offsets that slice back to it", () => {
+		const text = 'Span {{F12:span_len}} and {{Q7:completion:from="a}}b":to="c"}} end'
+		const found = findPlaceholders(text)
+		expect(found.map((item) => item.token)).toEqual(["{{F12:span_len}}", '{{Q7:completion:from="a}}b":to="c"}}'])
+		for (const item of found) expect(text.slice(item.start, item.end)).toBe(item.token)
+		expect(found[1].parsed).toMatchObject({ from: "a}}b", to: "c" })
+	})
+
+	test("an unterminated pointer is reported, not skipped", () => {
+		const found = findPlaceholders("a {{F12:span_len\nb")
+		expect(found).toHaveLength(1)
+		expect(found[0].parsed).toHaveProperty("error")
+	})
+})
+
+describe("subSpan", () => {
+	test("inclusive sub-span with an ellipsis only at cut ends", () => {
+		expect(subSpan(QUOTE, "no earlier", "2027")).toEqual({ text: "\u2026no earlier than 2027", start: 23, end: 43 })
+		expect(subSpan(QUOTE, "we", "completion")).toEqual({ text: "we estimate completion\u2026", start: 0, end: 22 })
+		expect(subSpan(QUOTE, "estimate", "earlier").text).toBe("\u2026estimate completion no earlier\u2026")
+	})
+
+	test("an anchor that is missing, repeated, or reversed is null", () => {
+		expect(subSpan(QUOTE, "missing", "2027")).toBeNull()
+		expect(subSpan(QUOTE, "ti", "2027")).toBeNull()
+		expect(subSpan(QUOTE, "2027", "estimate")).toBeNull()
+	})
+})
+
+describe("lead", () => {
+	test("first n words plus an ellipsis, never cutting a word", () => {
+		expect(lead(QUOTE, 3)).toEqual({ text: "we estimate completion\u2026", start: 0, end: 22 })
+		expect(lead(QUOTE, 7)).toEqual({ text: QUOTE, start: 0, end: QUOTE.length })
+		expect(lead(QUOTE, 40)).toEqual({ text: QUOTE, start: 0, end: QUOTE.length })
+	})
+})

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

@@ -0,0 +1,115 @@
+// polish-apply.mjs - checked, per-edit application of a proofread lane's polish edits.
+//
+// An edit whose before or after holds <, > or & is polish_edit_rejected (POLISH_MARKUP_REASON)
+// before anything else, so no edit can create, alter, close or escape a tag, comment,
+// bogus comment, CDATA section, entity or script, whatever the tokenizer models; a located region
+// that overlaps a character reference or opens one (it starts inside `&name`) is rejected with
+// POLISH_REFERENCE_REASON, so an edit can neither change nor complete an existing reference.
+// Those two guards are the early, actionable refusals; the guarantee itself is the whole-document
+// skeleton comparison (html-markup.skeletonChange) that polish-rules runs in both gates: every
+// markup token and every character reference stays byte-identical, and an accepted edit's span
+// holds no skeleton token, so any difference refuses the edit and reports polish_diff_fail.
+// applyEdits(html, edits, ledger) applies each {before, after, reason} edit in edits-file order,
+// against the output of the edits accepted before it. `before` must occur exactly once (runs of
+// whitespace match any whitespace run) and must not cut through a fact span; otherwise the edit is
+// polish_edit_unlocated. A located edit is applied whole or not at all: it is polish_edit_rejected
+// when polish-rules.polishDefects(..., {ordered: true}) finds any defect between the current
+// document and the document with the edit (per edit), or between the ORIGINAL input and the
+// document with the edit (whole document: the baseline polish-diff uses). Ordered is stricter than
+// polish-diff's multiset comparison and the last accepted candidate is the output, so a clean run
+// is always polish-diff clean: no cross-edit case is left to the backstop. The rules see the
+// text-node projection and freeze every markup byte, including script/style/template content.
+// validatePolishEdits and POLISH_EDIT_FIELDS are the edit
+// contract every caller (the CLI included) uses. No IO, no model. Plain Node ESM.
+
+import { CHARACTER_REFERENCE } from "./html-markup.mjs"
+import { factSpans } from "./polish-project.mjs"
+import { polishDefects } from "./polish-rules.mjs"
+
+export { numeralKeys, project, SLOT, termCounts, textOf } from "./polish-project.mjs"
+
+/** The fields of one polish edit: before and after are required strings, reason an optional string. */
+export const POLISH_EDIT_FIELDS = Object.freeze({ before: "required", after: "required", reason: "optional" })
+
+/** Throws a TypeError naming the first edit that breaks POLISH_EDIT_FIELDS; returns the edits. */
+export function validatePolishEdits(edits) {
+	if (!Array.isArray(edits)) throw new TypeError("edits must be an array")
+	edits.forEach((edit, index) => {
+		if (edit === null || typeof edit !== "object" || Array.isArray(edit)) throw new TypeError(`edit ${index} must be an object`)
+		for (const [field, need] of Object.entries(POLISH_EDIT_FIELDS)) {
+			if (need === "optional" && edit[field] === undefined) continue
+			if (typeof edit[field] !== "string") throw new TypeError(`edit ${index} needs ${need === "optional" ? "a string" : "string"} ${field}`)
+		}
+	})
+	return edits
+}
+
+/** Characters an edit's before and after may never contain. */
+export const POLISH_MARKUP_CHARACTERS = /[<>&]/
+/** The actionable rejection reason for an edit holding a markup character. */
+export const POLISH_MARKUP_REASON = "edit contains markup characters (<, >, &): route this section through the full fidelity gates"
+/** The actionable rejection reason for a located region touching a character reference. */
+export const POLISH_REFERENCE_REASON = "edit touches a character reference: route this section through the full fidelity gates"
+
+/** True when [start, end) overlaps a character reference of html or starts inside one. */
+export function touchesReference(html, start, end) {
+	for (const match of String(html).matchAll(CHARACTER_REFERENCE)) {
+		if (match.index < end && match.index + match[0].length > start) return true
+	}
+	return /&[#\w]*$/.test(html.slice(Math.max(0, start - 16), start))
+}
+
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+/** The single whitespace-normalized match of `before` in html as {start, end}, or {count} otherwise. */
+function locate(html, before) {
+	if (before.trim() === "") return { count: 0 }
+	const pattern = new RegExp(before.split(/\s+/).map(escape).join("\\s+"), "g")
+	const hits = [...html.matchAll(pattern)]
+	return hits.length === 1 ? { count: 1, start: hits[0].index, end: hits[0].index + hits[0][0].length } : { count: hits.length }
+}
+
+/** The id of a fact span the region [start, end) cuts through (overlaps without containing), or null. */
+export function cutSpan(html, start, end) {
+	return factSpans(html).find((span) => span.start < end && span.end > start && !(start <= span.start && span.end <= end))?.id ?? null
+}
+
+/**
+ * @param {string} html the filled report
+ * @param {{ before: string, after: string, reason?: string }[]} edits in edits-file order
+ * @param {{ rows: object[] }} ledger
+ * @returns {{ out: string, applied: number[], rejected: { index: number, code: string, reason: string }[],
+ *   unlocated: { index: number, code: string, reason: string }[] }}
+ */
+export function applyEdits(html, edits, ledger) {
+	validatePolishEdits(edits)
+	const original = String(html)
+	const result = { out: original, applied: [], rejected: [], unlocated: [] }
+	const defects = (candidate) => {
+		const messages = [result.out, original].flatMap((base) => polishDefects(base, candidate, ledger, { ordered: true }).map((d) => d.message))
+		return [...new Set(messages)]
+	}
+	edits.forEach((edit, index) => {
+		const touches = POLISH_MARKUP_CHARACTERS.test(edit.before) || POLISH_MARKUP_CHARACTERS.test(edit.after)
+		const where = locate(result.out, edit.before)
+		if (where.count !== 1 && !touches) {
+			result.unlocated.push({ index, code: "polish_edit_unlocated", reason: `before matches ${where.count} times; it must match exactly once` })
+			return
+		}
+		const reasons = touches ? [POLISH_MARKUP_REASON] : []
+		const candidate = where.count === 1 ? result.out.slice(0, where.start) + edit.after + result.out.slice(where.end) : result.out
+		if (where.count === 1) {
+			const cut = cutSpan(result.out, where.start, where.end)
+			if (touchesReference(result.out, where.start, where.end)) reasons.push(POLISH_REFERENCE_REASON)
+			reasons.push(...defects(candidate))
+			if (cut !== null) reasons.push(`the edit cuts through fact span ${cut}`)
+		}
+		if (reasons.length > 0) {
+			result.rejected.push({ index, code: "polish_edit_rejected", reason: reasons.join("; ") })
+			return
+		}
+		result.out = candidate
+		result.applied.push(index)
+	})
+	return result
+}