lazycodex-ai 5.1.44 → 5.1.46

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

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test"
+
+import { guardedTerms, isKoreanTerm, lexicalPattern, lexiconChecks, QUALIFIER_FORMS } from "./fidelity-lexicon.mjs"
+import { HEDGES, QUALIFIERS } from "./lexicon.mjs"
+
+type Pair = { pair_id: string; quote: string; sentence: string; span?: [number, number] | null; qualifier?: string | null; acronyms?: Record<string, string> }
+type Finding = { pair_id: string; code: string; message: string }
+type Result = { findings: Finding[]; forceStrong: string[] }
+
+function check(pair: Omit<Pair, "pair_id">): Result {
+	return lexiconChecks([{ pair_id: "P1", ...pair }]) as Result
+}
+
+const codes = (result: Result) => result.findings.map((finding) => finding.code)
+
+function withSpan(quote: string, sentence: string, fact: string, qualifier: string | null): Omit<Pair, "pair_id"> {
+	const at = sentence.indexOf(fact)
+	return { quote, sentence, span: [at, at + fact.length], qualifier }
+}
+
+describe("source-versus-sentence lexicon", () => {
+	test("#given a hedged source and an unhedged sentence #when checked #then hedge_dropped", () => {
+		expect(codes(check({ quote: "estimated 100억", sentence: "100억 달성" }))).toEqual(["hedge_dropped"])
+	})
+
+	test("#given the hedge kept #when checked #then clean", () => {
+		expect(codes(check({ quote: "estimated 100억", sentence: "estimated 100억 달성" }))).toEqual([])
+	})
+
+	test("#given a source that falls and a sentence that rises #when checked #then direction_flipped", () => {
+		expect(codes(check({ quote: "Costs were reduced last year.", sentence: "Costs increased last year." }))).toEqual(["direction_flipped"])
+	})
+
+	test("#given a negated sentence #when checked #then direction is routed, not flagged", () => {
+		expect(codes(check({ quote: "Costs were reduced last year.", sentence: "Costs did not increase last year." }))).toEqual([])
+	})
+
+	test("#given a causal connective the source lacks #when checked #then causality_added", () => {
+		expect(codes(check({ quote: "Sales rose and prices fell.", sentence: "Sales rose because prices fell." }))).toEqual(["causality_added"])
+	})
+
+	test("#given a narrow source scope and a broad sentence scope #when checked #then scope_widened_warn and force_strong", () => {
+		const result = check({ quote: "북미 매출이 늘었다", sentence: "전 세계 매출이 늘었다" })
+		expect(codes(result)).toEqual(["scope_widened_warn"])
+		expect(result.forceStrong).toEqual(["P1"])
+	})
+})
+
+describe("qualifiers", () => {
+	const QUOTE = "The bridge span is up to 320 m long."
+
+	test("#given an upper-bounded row and a sentence without the bound #when checked #then qualifier_dropped", () => {
+		expect(codes(check(withSpan(QUOTE, "The span is 320 m long.", "320 m", "upper_inclusive")))).toEqual(["qualifier_dropped"])
+	})
+
+	test("#given the :q rendering inside the fact span #when checked #then clean", () => {
+		expect(codes(check(withSpan(QUOTE, "The span is up to 320 m long.", "up to 320 m", "upper_inclusive")))).toEqual([])
+	})
+
+	test("#given the Korean surface form after the value #when checked #then the closed mapping accepts it", () => {
+		expect(codes(check(withSpan("최대 320 m", "길이는 320 m 이하 수준이다", "320 m", "upper_inclusive")))).toEqual([])
+	})
+
+	test("#given a qualifier more than six tokens away #when checked #then it does not count", () => {
+		const sentence = "Up to now the bridge, built over the long river, spans 320 m."
+		expect(codes(check(withSpan(QUOTE, sentence, "320 m", "upper_inclusive")))).toEqual(["qualifier_dropped"])
+	})
+})
+
+describe("names and routing", () => {
+	test("#given an acronym in neither the quote nor the source's acronym table #when checked #then name_outside_quote and force_strong", () => {
+		const result = check({ quote: "Demand rose in 2026.", sentence: "HBM demand rose in 2026.", acronyms: {} })
+		expect(codes(result)).toEqual(["name_outside_quote"])
+		expect(result.forceStrong).toEqual(["P1"])
+	})
+
+	test("#given the acronym listed in the source's acronym table #when checked #then clean", () => {
+		expect(codes(check({ quote: "Demand rose in 2026.", sentence: "HBM demand rose in 2026.", acronyms: { HBM: "High Bandwidth Memory" } }))).toEqual([])
+	})
+
+	test("#given a hedge before a concessive in the sentence while the source hedges its final clause #when checked #then force_strong only", () => {
+		const result = check({
+			quote: "Revenue rose, but the margin is estimated to fall.",
+			sentence: "The margin is estimated to fall, but revenue rose.",
+		})
+		expect(codes(result)).toEqual([])
+		expect(result.forceStrong).toEqual(["P1"])
+	})
+})
+
+describe("shared lexical owners used by polish (duplication sweep)", () => {
+	const hits = (text: string, term: string, mode: string) => [...text.matchAll(lexicalPattern(term, mode))].length
+
+	test("guardedTerms is the union of HEDGES, QUALIFIERS and every QUALIFIER_FORMS form", () => {
+		const union = new Set([...HEDGES, ...QUALIFIERS, ...Object.values(QUALIFIER_FORMS).flat()])
+		expect(new Set(guardedTerms())).toEqual(union)
+		expect(guardedTerms().length).toBe(union.size)
+	})
+
+	test("isKoreanTerm detects Hangul", () => {
+		expect(isKoreanTerm("\uC57D")).toBe(true)
+		expect(isKoreanTerm("about")).toBe(false)
+	})
+
+	test("guard mode: single Latin words inflect, multiword terms do not, Korean matches as a substring", () => {
+		expect(hits("it was estimatedly so", "estimated", "guard")).toBe(1)
+		expect(hits("more thanks", "more than", "guard")).toBe(0)
+		expect(hits("more than", "more than", "guard")).toBe(1)
+		expect(hits("\uC608\uC57D", "\uC57D", "guard")).toBe(1)
+	})
+
+	test("stem mode keeps its own rules: multiword terms inflect and a one-syllable Korean term needs a boundary", () => {
+		expect(hits("more thanks", "more than", "stem")).toBe(1)
+		expect(hits("\uC608\uC57D", "\uC57D", "stem")).toBe(0)
+		expect(hits("\uC57D 3", "\uC57D", "stem")).toBe(1)
+	})
+})

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

@@ -0,0 +1,163 @@
+// fidelity-records.mjs - the fidelity record schema and the delivery barrier of `outcome verify`
+// and `outcome finish`.
+//
+// The table and the schema are the spec for the barrier. Every fidelity record is written through
+// writeFidelityRecord, which stamps one envelope (RECORD_ENVELOPE: record_kind, artifact_sha256,
+// report, written_at, defects) plus the fields its kind declares, and read through
+// readFidelityRecord, which refuses a missing, unknown, or ill-typed field (fail closed).
+// FIDELITY_RECORDS holds every per-record rule as a column: where the records are (targets), when a
+// delivered session must carry one (requiredWhen), which envelope field binds it to the delivered
+// bytes (bindsTo), and which defects block delivery (blocking). The barrier is one loop over the
+// table with no record-specific branch; a new fidelity step adds a row here and nothing else.
+//
+// HTML/PDF/DOCX need a gate record or an explicitly logged not_run reason, even without a ledger.
+// That logged exemption covers deliveries this harness never gated: once a ledger or any session
+// fidelity record exists, the barrier refuses the unverified edition regardless of it, and the same
+// exemption is the only way a required record may be absent.
+
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { CliError, readJsonFile, sha256Of, writeJsonAtomic } from "./cli-support.mjs"
+import { LEDGER_FILENAME } from "./fact-ledger.mjs"
+import { meaningCheckEnabled, requireLockedBrief } from "./fidelity-brief.mjs"
+import { blocksDelivery, deliveryBlockReason } from "./gates-fidelity.mjs"
+
+export const FIDELITY_RECORD = "fidelity-defects.json"
+export const MEANING_RECORD = "fidelity-meaning-defects.json"
+
+/** The fields every fidelity record carries, whatever its kind. */
+export const RECORD_ENVELOPE = Object.freeze(["record_kind", "artifact_sha256", "report", "written_at", "defects"])
+
+/** Formats that need a fidelity record even in a session with no ledger and no record. */
+const GATED_FORMATS = Object.freeze(["html", "pdf", "docx"])
+
+/** The meaning record is required unless the locked brief turns the check off; a malformed block cannot prove off. */
+function meaningRequired({ sessionDir }) {
+	const lock = requireLockedBrief(join(sessionDir, "brief.md"))
+	return lock.exitCode === 2 || (lock.locked && meaningCheckEnabled(lock.parsed))
+}
+
+const subjectOf = (row) => row.renderedFrom ?? row.path ?? null
+
+/** One record per delivered edition: the file its row names with --verified-by, bound to that edition's bytes. */
+const perEdition = (sessionDir, delivered) =>
+	delivered.map((row) => ({ path: row.verifiedBy ?? null, declared: row.verifiedBy !== undefined, format: row.format, at: `${row.format}: `, subjects: [subjectOf(row)].filter((subject) => subject !== null) }))
+
+/** One record per session, in the session directory, bound to any delivered edition's bytes. */
+const perSession = (file) => (sessionDir, delivered) => [{ path: join(sessionDir, file), declared: false, format: null, at: "", subjects: delivered.map(subjectOf).filter((subject) => subject !== null) }]
+
+/** Every fidelity record the barrier reads, in check order; each column is one rule the barrier applies. */
+export const FIDELITY_RECORDS = Object.freeze([
+	Object.freeze({
+		kind: "fidelity",
+		file: FIDELITY_RECORD,
+		step: "fidelity gate",
+		targets: perEdition,
+		requiredWhen: ({ hasFidelity }, target) => hasFidelity || GATED_FORMATS.includes(target.format),
+		remedy: (target) => `run fact verify on ${target.subjects[0] ?? "the edition"} and set it with --verified-by`,
+		bindsTo: "artifact_sha256",
+		blocking: blocksDelivery,
+		payload: Object.freeze(["command", "status", "exitCode", "format", "counts", "gatesRun"]),
+	}),
+	Object.freeze({
+		kind: "meaning",
+		file: MEANING_RECORD,
+		step: "meaning gate",
+		targets: perSession(MEANING_RECORD),
+		requiredWhen: meaningRequired,
+		remedy: () => "run fact pairs and fact meaning-check before delivery",
+		bindsTo: "artifact_sha256",
+		blocking: blocksDelivery,
+		payload: Object.freeze(["command", "status", "exitCode", "run_id", "pairs_sha256", "counts", "dropped", "unverified", "calibration_path", "calibration_written", "calibration_replaced", "promotion_eligibility"]),
+	}),
+])
+
+const entryOf = (kind) => {
+	const entry = FIDELITY_RECORDS.find((row) => row.kind === kind)
+	if (entry === undefined) throw new CliError(`unknown fidelity record kind ${kind}`)
+	return entry
+}
+
+/** Why a value is not a valid record of this kind, or null. */
+function envelopeProblem(record, entry) {
+	if (record === null || typeof record !== "object" || Array.isArray(record)) return "not a record object"
+	const missing = RECORD_ENVELOPE.filter((key) => !Object.hasOwn(record, key))
+	if (missing.length > 0) return `missing ${missing.join(", ")}`
+	const unknown = Object.keys(record).filter((key) => !RECORD_ENVELOPE.includes(key) && !entry.payload.includes(key))
+	if (unknown.length > 0) return `unknown field(s) ${unknown.join(", ")}`
+	if (record.record_kind !== entry.kind) return `record_kind ${JSON.stringify(record.record_kind)} is not ${entry.kind}`
+	if (typeof record.artifact_sha256 !== "string" || !/^[0-9a-f]{64}$/u.test(record.artifact_sha256)) return "artifact_sha256 is not a sha256 hex digest"
+	if (typeof record.report !== "string" || record.report === "") return "report is not a path"
+	if (typeof record.written_at !== "string" || Number.isNaN(Date.parse(record.written_at))) return "written_at is not an ISO time"
+	if (!Array.isArray(record.defects) || !record.defects.every((defect) => typeof defect?.code === "string")) return "defects is not a list of coded defects"
+	return null
+}
+
+/**
+ * Write one fidelity record of a kind in the table: the envelope plus that kind's payload fields.
+ * @param {string} path
+ * @param {string} kind a FIDELITY_RECORDS kind
+ * @param {{ artifact_sha256: string, report: string, defects: object[], [field: string]: unknown }} fields the envelope values plus the kind's payload
+ */
+export function writeFidelityRecord(path, kind, { artifact_sha256, report, defects, ...payload }, now = new Date()) {
+	const entry = entryOf(kind)
+	const record = { record_kind: kind, artifact_sha256, report, written_at: now.toISOString(), defects, ...payload }
+	const problem = envelopeProblem(record, entry)
+	if (problem !== null) throw new CliError(`refusing to write a malformed ${kind} record: ${problem}`)
+	writeJsonAtomic(path, record)
+	return record
+}
+
+/** Read one fidelity record of a kind; anything but a valid envelope is a CliError naming the path. */
+export function readFidelityRecord(path, kind) {
+	const entry = entryOf(kind)
+	let record
+	try {
+		record = readJsonFile(path)
+	} catch (error) {
+		throw new CliError(`${kind} record ${path} is malformed: ${error.message}`)
+	}
+	const problem = envelopeProblem(record, entry)
+	if (problem !== null) throw new CliError(`${kind} record ${path} is malformed: ${problem}`)
+	return record
+}
+
+const unresolved = (format, codes, path) => ({ code: "fidelity_unresolved", format, codes, message: codes.map((code) => deliveryBlockReason({ code })).join("; "), path })
+const hashOf = (path) => (existsSync(path) ? sha256Of(readFileSync(path)) : null)
+
+/** Barrier problems for `outcome verify` and `outcome finish`; empty when nothing blocks delivery. */
+export function fidelityProblems(sessionDir, manifest) {
+	const delivered = manifest.deliverables.filter((row) => row.status === "delivered")
+	const hasFidelity = existsSync(join(sessionDir, LEDGER_FILENAME)) || FIDELITY_RECORDS.some((entry) => existsSync(join(sessionDir, entry.file)))
+	const lastFidelity = manifest.gateHistory?.findLast((entry) => entry.gate === "fidelity")
+	const exempt = !hasFidelity && manifest.gates.fidelity === "not_run" && lastFidelity?.status === "not_run" && Boolean(lastFidelity.reason?.trim())
+	const context = { sessionDir, hasFidelity }
+	const problems = []
+	const counted = new Set()
+	for (const entry of FIDELITY_RECORDS) {
+		for (const target of entry.targets(sessionDir, delivered)) {
+			const refuse = (message, path = target.path) => problems.push({ code: "edition_unverified", format: target.format, message: `${target.at}${message}`, path })
+			if (target.path === null || !existsSync(target.path)) {
+				if (target.declared) refuse(`${entry.kind} record ${target.path} is missing`)
+				else if (delivered.length > 0 && !exempt && entry.requiredWhen(context, target)) refuse(`${entry.step} not run; ${entry.remedy(target)}`, target.path ?? target.subjects[0] ?? null)
+				continue
+			}
+			let record
+			try {
+				record = readFidelityRecord(target.path, entry.kind)
+			} catch (error) {
+				refuse(error.message)
+				continue
+			}
+			if (target.subjects.length > 0 && !target.subjects.some((subject) => hashOf(subject) === record[entry.bindsTo])) {
+				refuse(`${entry.kind} record ${target.path} is for a different edition than ${target.subjects.join(", ")}`)
+			}
+			if (counted.has(target.path)) continue
+			counted.add(target.path)
+			const codes = [...new Set(record.defects.filter(entry.blocking).map((defect) => defect.code))].sort()
+			if (codes.length > 0) problems.push(unresolved(target.format, codes, target.path))
+		}
+	}
+	return problems
+}

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

@@ -0,0 +1,64 @@
+// fidelity-state.mjs - per-sentence failure counts for the fidelity repair loop. A sentence is
+// keyed by its section slug and the sorted fact ids it cites, so a reworded sentence that
+// cites the same facts keeps its count. The exact slug and id rules are in the comment above
+// slugify in fact-fill.mjs. node: builtins only.
+
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+
+import { CliError, readJsonFile, writeJsonAtomic } from "./cli-support.mjs"
+
+export const STATE_FILENAME = "fidelity-state.json"
+export const STATE_SCHEMA_VERSION = 1
+
+/** slug + '#' + the fact ids sorted and joined by ','. */
+export function sentenceKey(sectionSlug, factIds) {
+	return `${sectionSlug}#${[...factIds].sort().join(",")}`
+}
+
+function emptyState() {
+	return { schemaVersion: STATE_SCHEMA_VERSION, failures: {}, replaced: [] }
+}
+
+function isValid(state) {
+	return (
+		state !== null &&
+		typeof state === "object" &&
+		state.schemaVersion === STATE_SCHEMA_VERSION &&
+		state.failures !== null &&
+		typeof state.failures === "object" &&
+		!Array.isArray(state.failures) &&
+		Object.values(state.failures).every((count) => Number.isInteger(count) && count >= 0) &&
+		Array.isArray(state.replaced) &&
+		state.replaced.every((key) => typeof key === "string")
+	)
+}
+
+export function readState(dir) {
+	const file = join(dir, STATE_FILENAME)
+	if (!existsSync(file)) return emptyState()
+	const state = readJsonFile(file)
+	if (!isValid(state)) throw new CliError(`${file} is not a valid fidelity state`)
+	return state
+}
+
+export function recordFailure(state, key) {
+	state.failures[key] = (state.failures[key] ?? 0) + 1
+	return state.failures[key]
+}
+
+export function failureCount(state, key) {
+	return state.failures[key] ?? 0
+}
+
+export function markReplaced(state, key) {
+	if (!state.replaced.includes(key)) state.replaced.push(key)
+	return state
+}
+
+export function writeState(dir, state) {
+	if (!isValid(state)) throw new CliError("refusing to write an invalid fidelity state")
+	const file = join(dir, STATE_FILENAME)
+	writeJsonAtomic(file, state)
+	return file
+}

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

@@ -0,0 +1,46 @@
+import { describe, expect, onTestFinished, test } from "bun:test"
+import { mkdtempSync, readdirSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { failureCount, markReplaced, readState, recordFailure, sentenceKey, writeState } from "./fidelity-state.mjs"
+
+function tempDir(): string {
+	const dir = mkdtempSync(join(tmpdir(), "ulw-fidelity-"))
+	onTestFinished(() => rmSync(dir, { recursive: true, force: true }))
+	return dir
+}
+
+describe("fidelity state", () => {
+	test("sentenceKey is order-independent on ids", () => {
+		expect(sentenceKey("findings", ["F3", "Q1", "F12"])).toBe(sentenceKey("findings", ["F12", "F3", "Q1"]))
+		expect(sentenceKey("findings", ["F2", "F1"])).toBe("findings#F1,F2")
+		expect(sentenceKey("findings", ["F1"])).not.toBe(sentenceKey("other", ["F1"]))
+	})
+
+	test("failureCount increments per key", () => {
+		const dir = tempDir()
+		const state = readState(dir)
+		const key = sentenceKey("findings", ["F1"])
+		expect(failureCount(state, key)).toBe(0)
+		recordFailure(state, key)
+		recordFailure(state, key)
+		expect(failureCount(state, key)).toBe(2)
+		expect(failureCount(state, sentenceKey("findings", ["F2"]))).toBe(0)
+	})
+
+	test("markReplaced records the key and survives a write/read", () => {
+		const dir = tempDir()
+		const state = readState(dir)
+		const key = sentenceKey("findings", ["Q1"])
+		recordFailure(state, key)
+		markReplaced(state, key)
+		markReplaced(state, key)
+		expect(state.replaced).toEqual([key])
+		writeState(dir, state)
+		expect(readdirSync(dir)).toEqual(["fidelity-state.json"])
+		const loaded = readState(dir)
+		expect(loaded).toEqual(state)
+		expect(failureCount(loaded, key)).toBe(1)
+	})
+})

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

@@ -0,0 +1,85 @@
+// fidelity-trace.mjs - the numeral and quotation trace of the deterministic fidelity gate.
+//
+// Every numeral in prose and table cells outside sources, toc and chart figures (dates included)
+// must sit in a data-fact, data-translates, q or blockquote element, or at the site of a fill-map
+// entry; otherwise untraceable_number. Quoted runs with no Q row are quote_unbound, and leftover
+// {{...}} pointers unresolved_placeholder. No model, no network.
+//
+// Fill-map assumption (fact-fill.mjs fill(), #11141): format "html" wraps every value and quote in
+// <data data-fact> / <q data-fact> / <blockquote data-fact>, which this trace skips by element, so
+// it needs no fill map. Format "md" writes bare text, and each fillMap entry is
+// { fact_id, rendered, start, end } with start/end indexing the filled Markdown, not the HTML this
+// gate reads. fill() pushes entries in output order and the Markdown-to-HTML step keeps text order,
+// so each entry, in array order, is matched to the next untraced occurrence of its rendered text in
+// document order that is a whole numeral and reads as the entry's row there (fits: "1,237 million"
+// is not F2's 1,237), and strips that one occurrence only. A copy of the same text that no entry
+// accounts for stays in the scan; an entry whose text is gone strips nothing.
+
+import { NOT_CLAIMS } from "./numerals.mjs"
+
+/** Structural numerals: versions, figure/table/section references, times (NOT_CLAIMS 7-11), pages, citations, placeholders. */
+export const STRUCTURAL = [...NOT_CLAIMS.slice(7, 12), /\b(?:p|pp|page|pages)\.?\s*\d+(?:\s*[-\u2013]\s*\d+)?/gi, /\[(?:S|Source\s*)\d+\]|\[\^\d+\]/gi, /\{\{[^}]*\}\}/g]
+const NUMERAL = /\d+(?:[.,\-/:]\d+)*/g
+const TRACED = "\u0000"
+const QUOTE_RUNS = [/"([^"]+)"/g, /\u201C([^\u201C\u201D]+)\u201D/g, /\u300C([^\u300C\u300D]+)\u300D/g, /\u300E([^\u300E\u300F]+)\u300F/g]
+
+export const clip = (text) => String(text).replace(/\s+/g, " ").trim().slice(0, 80)
+
+function ownerTexts(ctx, charts) {
+	const owners = new Map()
+	for (const entry of ctx.texts) {
+		const kind = ctx.kindOf(entry.scope)
+		if (kind === "sources" || kind === "toc") continue
+		if (charts.has(ctx.util.closest(entry.node, (cur) => cur.tag === "figure"))) continue
+		const hidden = ctx.util.closest(entry.node, (cur) => cur.attrs["data-fact"] !== undefined || cur.attrs["data-translates"] !== undefined || cur.tag === "q" || cur.tag === "blockquote")
+		owners.set(entry.owner, (owners.get(entry.owner) ?? "") + (hidden ? ` ${TRACED} ` : entry.node.text))
+	}
+	return owners
+}
+
+function scanOwner(ctx, owner, raw, flag) {
+	let text = raw
+	if (/^h[1-6]$/.test(owner.tag)) text = text.replace(/^\s*\d+(?:[.-]\d+)*[.):]?\s+/, " ")
+	if (text.includes("{{")) flag("unresolved_placeholder", owner, `leftover placeholder: "${clip(text.slice(text.indexOf("{{")))}"`)
+	for (const re of QUOTE_RUNS) {
+		for (const match of text.matchAll(re)) {
+			const inner = match[1].replaceAll(TRACED, " ").trim()
+			const after = text.slice(match.index + match[0].length).trim().split(/\s+/).slice(0, 6).join(" ")
+			if (inner && (inner.split(/\s+/).length >= 3 || ctx.util.citationMarker.test(after))) flag("quote_unbound", owner, `direct quotation with no Q row: "${clip(match[0])}"`)
+		}
+	}
+	const rest = STRUCTURAL.reduce((acc, re) => acc.replace(re, " "), text)
+	for (const match of rest.matchAll(NUMERAL)) flag("untraceable_number", owner, `number "${match[0]}" has no ledger row: "${clip(rest.slice(Math.max(0, match.index - 30), match.index + 30))}"`)
+}
+
+/** Strip each fill-map entry at its own fill site: the next untraced occurrence after the previous entry's site. */
+function traceFills(owners, fillMap, fits) {
+	const keys = [...owners.keys()]
+	const texts = [...owners.values()]
+	let [index, from] = [0, 0]
+	for (const entry of fillMap ?? []) {
+		const { rendered } = entry
+		if (!rendered) continue
+		for (let i = index, at = from; i < texts.length; i += 1, at = 0) {
+			let hit = texts[i].indexOf(rendered, at)
+			const glued = (pos) => /\d/.test(texts[i][pos - 1] ?? "") || /\d/.test(texts[i][pos + rendered.length] ?? "")
+			while (hit !== -1 && (glued(hit) || !fits(entry, texts[i].slice(hit)))) hit = texts[i].indexOf(rendered, hit + 1)
+			if (hit === -1) continue
+			texts[i] = `${texts[i].slice(0, hit)}${TRACED}${texts[i].slice(hit + rendered.length)}`
+			;[index, from] = [i, hit + TRACED.length]
+			break
+		}
+	}
+	return new Map(keys.map((key, i) => [key, texts[i]]))
+}
+
+/**
+ * @param {object} ctx buildContext(...) from gates-static.mjs
+ * @param {Map<object, unknown>} charts chart figures, whose numerals chart checks own
+ * @param {{ fact_id: string, rendered: string, start?: number, end?: number }[] | null} fillMap Markdown fill map, or null
+ * @param {(code: string, node: object, message: string) => void} flag
+ * @param {(entry: object, tail: string) => boolean} fits whether the text from a candidate site on reads as the entry's row
+ */
+export function traceChecks(ctx, charts, fillMap, flag, fits) {
+	for (const [owner, text] of traceFills(ownerTexts(ctx, charts), fillMap, fits)) scanOwner(ctx, owner, text, flag)
+}

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

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { indexClaims } from "./claims-index.mjs"
+import { checkFidelity } from "./gates-fidelity.mjs"
+
+type Defect = { code: string; message: string }
+
+const FIXTURES = join(import.meta.dir, "tests", "fixtures")
+const FIX = join(FIXTURES, "fidelity")
+const read = (path: string) => readFileSync(path, "utf8")
+const GOOD = read(join(FIX, "report-good.html"))
+const OPTIONS = {
+	ledger: JSON.parse(read(join(FIX, "ledger-verify.json"))),
+	sourcesDir: join(FIX, "sources"),
+	claims: indexClaims(read(join(FIX, "claim-graph.md"))),
+	fillMap: null,
+	brief: read(join(FIXTURES, "fidelity-brief-locked.md")),
+	baseDir: FIX,
+}
+
+const run = (html: string, extra: Record<string, unknown> = {}) => (checkFidelity(html, { ...OPTIONS, ...extra }) as { defects: Defect[] }).defects
+const codes = (defects: Defect[]) => defects.map((defect) => defect.code)
+const F1_SENTENCE = "long [S4].</p>"
+const F2_FILL = [{ token: "{{F2:units_sold}}", fact_id: "F2", start: 0, end: 5, rendered: "1,237" }]
+
+describe("fill-site trace (Markdown fill map)", () => {
+	test("#given a filled 1,237 and a second bare 1,237 with no ledger row #when checked #then untraceable_number", () => {
+		const html = GOOD.replace("<h2>Appendix</h2>", "<p>Revenue was 1,237 million [S4].</p>\n<h2>Appendix</h2>")
+		expect(codes(run(html, { fillMap: F2_FILL }))).toEqual(["untraceable_number"])
+	})
+
+	test("#given the filled occurrence alone #when checked #then it stays traced", () => {
+		const html = GOOD.replace("<h2>Appendix</h2>", "<p>Units sold were 1,237 [S4].</p>\n<h2>Appendix</h2>")
+		expect(run(html, { fillMap: F2_FILL })).toEqual([])
+	})
+
+	test("#given one fill entry and two plain 1,237 sites #when checked #then the unfilled copy is untraceable_number", () => {
+		const html = GOOD.replace("<h2>Appendix</h2>", "<p>Units sold were 1,237 [S4].</p>\n<p>Again, 1,237 units [S4].</p>\n<h2>Appendix</h2>")
+		expect(codes(run(html, { fillMap: F2_FILL }))).toEqual(["untraceable_number"])
+	})
+
+	test("#given two fill entries for two occurrences #when checked #then both are traced", () => {
+		const html = GOOD.replace("<h2>Appendix</h2>", "<p>Units sold were 1,237 [S4].</p>\n<p>Again, 1,237 units [S4].</p>\n<h2>Appendix</h2>")
+		expect(run(html, { fillMap: [...F2_FILL, { ...F2_FILL[0], start: 40, end: 45 }] })).toEqual([])
+	})
+})
+
+describe("verification claims are judged by their mark, not their wording", () => {
+	test("#given the reviewer's prose 'as confirmed with the annual inspection report' #when checked #then no unsupported_verification", () => {
+		expect(run(GOOD.replace(F1_SENTENCE, "long, as confirmed with the annual inspection report [S4].</p>"))).toEqual([])
+	})
+
+	test("#given report-good's F7 marked verified but pointed at a page-sourced row #when checked #then unsupported_verification", () => {
+		expect(codes(run(GOOD.replace('value="42" data-fact="F7" data-claim-kind="verified" data-lineage="MEASURED">42 passed', 'value="320" data-fact="F1" data-unit="m" data-claim-kind="verified" data-lineage="MEASURED">up to 320 m')))).toEqual(["unsupported_verification"])
+	})
+})