oh-my-opencode 5.1.46 → 5.1.47

package/dist/skills/browser/runtime/omowright/manifest.json

@@ -5,5 +5,5 @@
     "index.js": "d67d3a847fe0bbc43e824feded48b280890d31879538309e671cd5f671133995",
     "page-bundle.js": "bfd51e8383cf47200d57387bbbed258bce5a3a3d00c38fc108034d2888e23f0c"
   },
-  "stagedAtUtc": "2026-10-25T01:01:55.641Z"
+  "stagedAtUtc": "2026-10-25T10:57:15.107Z"
 }

package/dist/skills/ulw-research/SKILL.md

@@ -373,7 +373,7 @@ Next, write `$SESSION_DIR/pairs-strong.json` (the same file, keeping only the pa
 
 3. **Layout gates.** Print the probe with `node "$SKILL_DIR/scripts/report-tools.mjs" layout-probe --json`, evaluate its `source` in the rendered page through the `browser` skill's owned headless engine, save the result as `$SESSION_DIR/boxes.json`, and re-run `check` with `--layout "$SESSION_DIR/boxes.json"` (overflow, clipped text, distorted images, overlapping siblings).
 4. **Visual QA.** Render the produced artifact back to images — PDF pages to PNG, the HTML through the browser skill at desktop and phone widths — and look at them: missing or broken figures, images stretched or spilling their containers, diagram or chart text rendered off the spec's font or palette, clipped tables, overflowing CJK text, blank pages, unlabeled chart values, wrong page breaks. Reading the source markup is not visual QA; inspect the pixels.
-5. **Proofread gate: `task(category="writing", ...)`.** Hand the final text to a dedicated `writing` worker whose only job is language: grammar, spelling, punctuation, terminology consistency, and whether the prose reads NATIVELY in the report's own language. It proofreads only and never composes. It returns a defect list; fix every item and re-run the gate on the delta. Deliver only on a clean pass. This gate runs BEFORE the first delivery, not after the user finds the typo.
+5. **Proofread gate: `task(category="writing", ...)`.** Hand the final text to a dedicated `writing` worker whose only job is language: grammar, spelling, punctuation, terminology consistency, and whether the prose reads NATIVELY in the report's own language. It proofreads only and never composes, and it never edits the file: it returns `$SESSION_DIR/polish-edits.json`, an array of `{"before": ..., "after": ..., "reason": ...}` where `before` is the exact current text of one or more adjacent sentences. Edits change text only; an edit whose before/after would alter any tag, attribute, comment, or script/style content is rejected, and markup changes go through the full fidelity gates instead. Apply it with `node "$SKILL_DIR/scripts/report-tools.mjs" fact polish-apply "$SESSION_DIR/report.html" --edits "$SESSION_DIR/polish-edits.json" --out "$SESSION_DIR/report.polished.html" --session-dir "$SESSION_DIR"`: each edit is applied alone, and an edit that changes a fact span, a numeral, a link, or a claim id, or drops a hedge or qualifier the source carries, is `polish_edit_rejected` (a `before` not found exactly once is `polish_edit_unlocated`) and leaves its text unchanged. Send the rejected and unlocated edits back to the same worker with their reasons, plus `$SESSION_DIR/polish-defects.json` and the pre-polish `report.html` the backstop compared against, so the worker sees why each edit was refused; it returns either a rewritten sentence or a new edit list, and the repair round re-runs `fact polish-apply` with `"$SESSION_DIR/report.polished.html"` as both input and output, within the repair budget. Then run the backstop `fact polish-diff --before "$SESSION_DIR/report.html" --after "$SESSION_DIR/report.polished.html" --session-dir "$SESSION_DIR"` (exit `1` on `polish_diff_fail`), `fact verify` on `report.polished.html`, and `fact pairs "$SESSION_DIR/report.polished.html" --changed-since "$SESSION_DIR/report.html.fill-map.json" --session-dir "$SESSION_DIR"`, which keeps only the quote and claim pairs whose sentence text changed during polish; run the meaning readers above (cheap, then strong on the flagged pairs) on exactly those pairs and `fact meaning-check` before recording `outcome gate fidelity`. A rewording that keeps every number, hedge, qualifier, and link but swaps who did what to whom therefore still reaches a meaning reader on the delivered text. `report.polished.html` is the report that is delivered. Deliver only on a clean pass. This gate runs BEFORE the first delivery, not after the user finds the typo. Edits must not span entities (such as & or <) or markup; narrow the edit to the surrounding words instead, and a rejected edit comes back with the reason to act on.
 
 **Repair is bounded.** After every gate run that found defects, ask `node "$SKILL_DIR/scripts/report-tools.mjs" repair decide --state "$SESSION_DIR/repair-state.json" --defects "$SESSION_DIR/defects.json" --defects "$SESSION_DIR/fidelity-defects.json" --artifact-bytes <bytes> --renders <pages> --session-dir "$SESSION_DIR"` and obey it: `repair` means fix and re-run; `deliver` means stop and ship with the residual defects the manifest now lists; `block` means a content-integrity defect remains (or there is no usable artifact), so do not deliver: tell the user what blocks it and record the row as `failed` with the reason. Never repair past a stop decision (3 attempts, a 2-attempt plateau, an oscillation, or 15 minutes; the reference's section 8). Fidelity defects ride the same loop (`--defects "$SESSION_DIR/defects.json" --defects "$SESSION_DIR/fidelity-defects.json"`), but a `deliver` decision does not release them: while `fidelity-defects.json` lists `untraceable_number`, `value_mismatch`, `unit_mismatch`, `quote_not_verbatim`, `quote_unbound`, `unbound_sentence`, or `chart_value_untraceable`, `outcome verify` fails with `fidelity_unresolved` and `outcome finish` refuses, even with the repair budget spent. The only ways out are a ledger row, an `assumed` row with its rationale, or removing the sentence.
 

package/dist/skills/ulw-research/references/deliverable-phase.md

@@ -133,7 +133,12 @@ Nothing reaches the requester until the gates for its QA tier pass, in this orde
    node "$SKILL_DIR/scripts/report-tools.mjs" layout-probe --json   # .source is one async expression
    ```
 4. **Visual QA.** Render the artifact to images (PDF pages to PNG, the HTML in the browser skill's engine at desktop and phone widths) and look at the pixels for what a machine cannot see: composition, hierarchy, page breaks, figure legibility.
-5. **Proofread.** A dedicated writing lane proofreads the final text only (grammar, spelling, punctuation, terminology, native register); it never composes or rewrites content.
+5. **Proofread.** A dedicated writing lane proofreads the final text only (grammar, spelling, punctuation, terminology, native register); it never composes or rewrites content and never edits the file. Edits change text only; an edit whose before/after would alter any tag, attribute, comment, or script/style content is rejected, and markup changes go through the full fidelity gates instead. It returns `polish-edits.json` (`[{before, after, reason}]`), which the orchestrator applies edit by edit; a rejected or unlocated edit goes back to the lane with its reason, within the repair budget. The backstop diff, `fact verify` on the polished file, and the meaning readers on the pairs whose sentences polish changed run before the fidelity gate is recorded again. Edits must not span entities (such as & or <) or markup; narrow the edit to the surrounding words instead, and a rejected edit comes back with the reason to act on.
+   ```bash
+   node "$SKILL_DIR/scripts/report-tools.mjs" fact polish-apply "$SESSION_DIR/report.html" --edits "$SESSION_DIR/polish-edits.json" --out "$SESSION_DIR/report.polished.html" --session-dir "$SESSION_DIR"
+   node "$SKILL_DIR/scripts/report-tools.mjs" fact polish-diff --before "$SESSION_DIR/report.html" --after "$SESSION_DIR/report.polished.html" --session-dir "$SESSION_DIR"   # writes polish-defects.json
+   node "$SKILL_DIR/scripts/report-tools.mjs" fact pairs "$SESSION_DIR/report.polished.html" --changed-since "$SESSION_DIR/report.html.fill-map.json" --session-dir "$SESSION_DIR"
+   ```
 
 **Every reader-facing edition is verified.** The main report, the inline edition (section 9), LaTeX per-section sources, and slide sources are filled by `fact fill` from one placeholder source and each is verified by `fact verify` into its own record; PDF and DOCX are renders of a verified source. A delivered row is recorded with `outcome set <format> delivered --path <file> --verified-by <record>`, where the record's `artifact_sha256` equals the sha256 of the delivered source; a PDF or DOCX adds `--rendered-from <source>` and is matched against that source. In a session with a fact ledger, `outcome verify` refuses a delivered row without a matching record (`edition_unverified`, blocker, integrity). Markdown and LaTeX verification arrive with the Markdown stage; until then `fact verify --format md|tex` exits `2`, and such an edition is recorded `blocked_capability` with that reason rather than delivered unverified.
 
@@ -216,7 +221,9 @@ Invoke every command as `node "$SKILL_DIR/scripts/report-tools.mjs" <command>`.
 | `fact export` | `--csv`, `--out <file>`, `--session-dir <dir>` | never |
 | `fact fill <src>` | `--out <file>` or `--view`, `--format html\|md\|tex`, `--inline`, `--replace-failed`, `--session-dir <dir>` | a fill error (nothing is written) |
 | `fact verify <report>` | `--format html\|md` (from the extension by default), `--sources <dir>`, `--claims <claims.json>`, `--fill-map <file>` (a Markdown edition reads `<report>.fill-map.json` by default), `--brief <brief.md>`, `--out <record>`, `--session-dir <dir>` | any blocker or major defect |
-| `fact pairs <report>` | `--format html\|md`, `--ledger <fact-ledger.json>`, `--claims <claims.json>`, `--changed-since <fill-map.json>` (pair only the facts that map filled), `--brief <brief.md>`, `--out <pairs.json>`, `--session-dir <dir>` | the brief has no locked `## Fidelity` block (with `meaning check: off` it writes `{"skipped": true}` and exits `0`) |
+| `fact pairs <report>` | `--format html\|md`, `--ledger <fact-ledger.json>`, `--claims <claims.json>`, `--changed-since <fill-map.json>` (keep only the pairs whose sentence text is not in the pre-polish artifact that map names, so the readers re-check exactly what polish rewrote; the map must carry `artifact_sha256` and the artifact must still hash to it, otherwise the command exits `2`), `--brief <brief.md>`, `--out <pairs.json>`, `--session-dir <dir>` | the brief has no locked `## Fidelity` block (with `meaning check: off` it writes `{"skipped": true}` and exits `0`) |
+| `fact polish-apply <report.html>` | `--edits <polish-edits.json>` and `--out <report.polished.html>` (both required; a missing flag or a Markdown edition exits `2`), `--format html`, `--ledger <fact-ledger.json>`, `--session-dir <dir>` | never: it exits `0` whenever it wrote the output. Each rejected (`polish_edit_rejected`) or unlocated (`polish_edit_unlocated`) edit leaves its text unchanged and is printed verbatim, one line per rejection, in the summary and in `data.rejected_reasons`; `data` also carries `applied`, `rejected`, `unlocated`, `applied_indexes`, `input_sha256`, `edits_sha256`, and `out_sha256` |
+| `fact polish-diff` | `--before <pre-polish.html>` and `--after <polished.html>` (both required; a missing flag exits `2`), `--ledger <fact-ledger.json>`, `--out <record>` (default `$SESSION_DIR/polish-defects.json`), `--session-dir <dir>` | a registry blocker in the diff (majors and minors are reported and exit `0`; a defect code the registry does not know refuses with `unknown defect code <code>`). The record is `{command, status, exitCode, before, artifact, artifact_sha256, defects[], counts}`, with `counts` in contract buckets |
 | `fact meaning-check` | `--pairs <pairs.json>` and `--verdicts <file>` (required; repeatable, one per reader tier), `--dispute P<n> --reason <text>`, `--run-id <id>`, `--calibration <file>` (default `fidelity-calibration.jsonl`), `--out <record>` (default `fidelity-meaning-defects.json`), `--session-dir <dir>` | `meaning_drift_confirmed` (stderr carries one JSON line with the defect and dropped-verdict counts) |
 | `fact derive` | `--op <op>` (required) with the operation's operands (section 11), `--unit`, `--to`, `--rationale`, `--disjoint`, `--label`, `--json`, `--session-dir <dir>` | `incompatible_operands` (no row written) |
 | `claims index <claim-graph.md>` | `--out <claims.json>` (required) | never (a malformed claim table exits `2`) |

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

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

@@ -1,6 +1,7 @@
 // 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
@@ -14,9 +15,8 @@ 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 { MEANING_RECORD, writeFidelityRecord } from "./fidelity-records.mjs"
@@ -31,26 +31,11 @@ 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)
@@ -77,10 +62,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 }

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

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

package/dist/skills/ulw-research/scripts/fact-commands-verify.mjs

@@ -18,6 +18,7 @@ import { CliError, readJsonFile, sha256Of } from "./cli-support.mjs"
 import { countDefects } from "./contracts.mjs"
 import { recompute } from "./fact-derive.mjs"
 import { readLedger } from "./fact-ledger.mjs"
+import { validateLedger } from "./fact-ledger-schema.mjs"
 import { FIDELITY_RECORD, writeFidelityRecord } from "./fidelity-records.mjs"
 import { blocksDelivery, checkFidelity } from "./gates-fidelity.mjs"
 import { parseMarkdown } from "./md-lite.mjs"
@@ -120,6 +121,24 @@ export function markdownAsHtml(text, entries, ledger) {
 	return { html: `${html}${open ? MD_HTML_BLOCK_RULES[open].group[1] : ""}</body></html>\n`, stale: [...stale] }
 }
 
+/** The session dir from --session-dir or SESSION_DIR, or null; a bare flag names no session. */
+export const sessionOf = (flags) => {
+	const dir = flags["session-dir"] ?? process.env.SESSION_DIR
+	return dir && dir !== true ? resolve(dir) : null
+}
+
+/** The ledger from --ledger (validated) or from the session dir; every fact command loads it here. */
+export function ledgerFrom(flags, session = sessionOf(flags)) {
+	if (flags.ledger === undefined) {
+		if (session === null) throw new CliError("--ledger is required without --session-dir (or SESSION_DIR)")
+		return readLedger(session)
+	}
+	const ledger = readJsonFile(flags.ledger)
+	const errors = validateLedger(ledger)
+	if (errors.length > 0) throw new CliError(`${flags.ledger} is not a valid fact ledger: ${errors[0]}`)
+	return ledger
+}
+
 const MARKDOWN_EXTENSION = /\.(md|markdown)$/iu
 /** The edition format: the explicit flag, else md for a .md or .markdown path (any case), else html. */
 export const editionFormatOf = (path, flag) => flag ?? (MARKDOWN_EXTENSION.test(path) ? "md" : "html")

package/dist/skills/ulw-research/scripts/fact-commands.mjs

@@ -1,5 +1,6 @@
 // fact-commands.mjs - the `fact` subcommands of report-tools: add, quote, retract, export, fill,
-// derive, verify (fact-commands-verify.mjs), pairs and meaning-check (fact-commands-meaning.mjs). Every value reaches the ledger from a source
+// derive, verify (fact-commands-verify.mjs), pairs and meaning-check (fact-commands-meaning.mjs), polish-apply and
+// polish-diff (fact-commands-polish.mjs). Every value reaches the ledger from a source
 // snapshot through a deterministic locator or from a declared derivation; nothing here accepts a
 // typed value. add and quote print the row with 60 chars of source context on each side (JSON
 // with --json). Exit 0 ok, 1 semantic failure (fact_not_located, fill errors, a refused
@@ -217,6 +218,7 @@ function runDerive(args) {
 export async function runFact(argv) {
 	const [sub, ...rest] = argv
 	if (sub === "pairs" || sub === "meaning-check") return (await import("./fact-commands-meaning.mjs")).runFactMeaning(sub, rest)
+	if (sub === "polish-apply" || sub === "polish-diff") return (await import("./fact-commands-polish.mjs")).runFactPolish(sub, rest)
 	const args = parseArgs(rest, { booleans: BOOLEANS })
 	switch (sub) {
 		case "add":
@@ -234,6 +236,6 @@ export async function runFact(argv) {
 		case "verify":
 			return (await import("./fact-commands-verify.mjs")).runFactVerify(args)
 		default:
-			throw new CliError("usage: fact <add|quote|retract|export|fill|verify|derive|pairs|meaning-check> ...")
+			throw new CliError("usage: fact <add|quote|retract|export|fill|verify|derive|pairs|meaning-check|polish-apply|polish-diff> ...")
 	}
 }

package/dist/skills/ulw-research/scripts/fact-pairs.mjs

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

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

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