lazycodex-ai 5.1.45 → 5.1.46

package/packages/omo-codex/plugin/skills/ulw-research/references/unit-rules.md

@@ -0,0 +1,157 @@
+# Unit rules for derived facts
+
+The one definition of which unit a derived or converted fact row carries, and the reviewer's checklist for
+`scripts/unit-rules.mjs`. ONE registry (`OPERATION_RULES`) owns, per operation: arity, operand-unit guards, context
+fields, result-unit inference, and malformed shapes. `derive()` (`fact-derive.mjs`) and `recompute()`
+(`fact-recompute.mjs`) both call it; neither has op-specific unit code. `row.unit` is NEVER used to choose arithmetic;
+numeric guards may read `exact` values, unit selection may not. The property tests in
+`scripts/fact-unit-rules.test.ts` iterate the registry, so a new operation needs a table row here and cases there.
+
+## Units
+- Canonical unit text is stored and compared exactly (case-sensitive symbols). Registered aliases
+  (`pp` -> `%p`, `kilometre` -> `km`, ...) are canonicalized ONLY at input (derive/fact add); a relabel to an alias
+  at rest is a relabel and is detected. Unit text with no alias is stored as given: whitespace is trimmed only around
+  `*`, `/`, `^`, and parentheses, so `million people`, `metric ton`, and `USD per person` keep their inner spaces.
+- A scale word (`million`, `M`, `bn`, `billion`, `thousand`, `e6`, ...; the `scale` rows of `units.mjs`) is a
+  multiplier, not a unit, and denomination scaling is out of scope, so it never becomes a unit atom: `million`,
+  `USD/M`, and `million*person` are refused at input (derive, and every operand read). Either store the scaled numeral
+  in the counted unit (5 million people as `5000000 person`) or keep the whole phrase as plain unit text:
+  `million people` has no table alias as a whole, so it is stored as given and sums only with `million people`, never
+  with `person`.
+- `null` = dimensionless. Omitted unit on a derived spec is an error, not null (distinguish omission from declared null).
+- Percent `%` stores percentage numerals (20% stores 20). Delta `%p` (percentage points). 1 basis point = 0.01 %p
+  (input alias `bp` -> `%p` with /100 scaling).
+- Composite units are canonical algebraic strings built by the registry (`USD/kg`, `person`), never by concatenating
+  operand strings: equal factors cancel (`USD/(USD/person)` -> `person`).
+- Affine scales (temperature: `C`, `F`) are flagged in the unit table; sum/diff/growth/share/ratio and every expr
+  node refuse them (temperatures are not summed or differenced as absolute values); only convert takes them.
+  Affine atoms in composites are refused before cancellation. Exponents are exact signed bigint integers, including zero.
+
+## Operation table
+
+| op | arity | operand guards | context fields (persisted on the row) | result unit | malformed -> recompute ok:false |
+|---|---|---|---|---|---|
+| sum | n>=2 | non-affine units, all equal after canonicalization; if `%`: `disjoint: true` AND `reference` (one denominator id/text) equal on every operand AND rationale | disjoint, reference, rationale | the common unit (`%` stays `%`) | <2 operands; missing id; no context; unequal/affine units; `%` without disjoint, reference, or rationale |
+| diff | 2 | non-affine units; typed pairs only: U-U -> U (same non-% unit); %-% -> `%p`; %-%p -> `%`; %p-%p -> `%p`; %p-% REFUSED | none | per the pair rule | arity; invalid pair (`%p - %`, `m - person`); affine units; stray context |
+| growth | 2 (from,to) | equal non-affine units; same entity; two different valid_at; from.exact > 0 | none | `%` (= 100(to-from)/from) | arity; unequal/affine units; entity/valid_at; from<=0; stray context |
+| share | 2 (part,whole) | equal non-affine units; whole.exact > 0; 0 <= part <= whole | none | `%` (= 100 part/whole) | arity; units; whole<=0; part outside [0,whole]; stray context |
+| ratio | 2 (num,den) | non-affine units; den.exact != 0; unequal `%`/`%p` REFUSED | none | registry composite: equal units -> null; else canonical `U(num)/U(den)` with cancellation | arity; den=0; stray context |
+| convert | 1 | U(a) has a registered factor to `target`; currencies REFUSED (use expr with a dated rate row) | target (persisted as canonical text; the ONLY accepted declared unit; `row.unit` is compared to it exactly, never canonicalized at rest) | the persisted target | arity; no context; target missing; target not canonical (an alias at rest); currency target; no factor; declared unit != persisted target |
+| expr | n>=1 | formula ids == operand set; node rules: `+`/`-` follow the sum/diff typed-pair rules, affine refusal included (so `20% - 10%` is `%p`, never `%`, and `25 C + 30 C` is refused); `+` also takes `%` + `%p` in either order -> `%` (as diff's `%-%p`), while `%` + `%` is refused (use sum); `*` and `/` compose canonical composites, `%`/`%p` operands normalize by /100 to dimensionless first; result must be fully inferred: NO rationale escape | none | the inferred unit; an explicit null->`%` conversion is a separate `convert`-like node (`pct()`) | formula/operand id mismatch; parse error; /0; uninferable unit; affine operands; stray context |
+
+Every row's malformed column also holds the two operand-identity shapes below (`repeated operand`, `self reference`).
+
+## Operand identity (applies to every row)
+- Operand ids are DISTINCT within one derived row. sum of F1, F1 is not a sum of two shares, and diff, ratio, share,
+  growth, or convert of an operand with itself is meaningless and would dodge every pair guard. A repeated id is
+  refused by `derive()` (`operand F1 is repeated`) and is `ok:false` at `recompute()` (malformed shape
+  `repeated operand`). The check sits in the registry (`expectedUnit` and `malformed`), so no operation can skip it.
+- expr may reference the same id in several leaves (`F1 * F1` is a legitimate square). Its stored operand list is the
+  formula's id SET, which must equal the formula ids (`formula id mismatch`); an id listed twice in that list is the
+  `repeated operand` shape too.
+- A derived row may not cite itself, directly (`self reference`: its own id among its operands) or through nested
+  derived operands (a cycle). `recompute()` refuses both. `derive()` recomputes every derived operand first and
+  refuses one that does not recompute (tampered, cyclic, or self-citing), so nothing is built on such a row.
+
+## Invariants (property tests iterate the table)
+1. For each op: generate valid typed operands (rational boundaries, aliases at input, composites, %/%p, affine,
+   metadata, conversion targets, repeated expr refs), derive, assert `recompute(row).ok === true`.
+2. Relabel: for each op, set `unit` to every different canonical string/null (incl. aliases and other valid targets),
+   regenerate render, keep exact: `recompute(row).ok === false` naming the expected unit; and `derive()` with that
+   declared unit is refused.
+3. Malformed: per op, every shape in the table's malformed column has one case, named in the registry's
+   `OPERATION_RULES[op].malformed` list (the test asserts its case names equal that list): `recompute` returns
+   `ok:false` for that shape's own reason, never throws.
+4. Nested derived rows are verified recursively (operands may be derived rows); cycles and self references are
+   refused, by `recompute()` and by `derive()` before it builds on a derived operand.
+5. Render precision (`renderPrecision` in `unit-rules.mjs`): fewest decimal places for sum, diff, an expr whose root
+   node is `+` or `-`, and every `%p` result; fewest significant figures otherwise (an expr `*` or `/` root with a
+   non-`%p` result included). Operand values and expr literals both count.
+
+## Decisions
+- Q1: the canonical composite goes in `unit` (consumers compare `unit` text); no side field.
+- Q2: expr with an unresolved unit is REFUSED; a known-unit `a*b/c` is inferable, so no rationale escape exists.
+- Q3: canonical `%p`, input alias `pp` (matches units.mjs).
+- Q4: strict null metadata: null matches only null; required metadata must be present.
+
+## Out of scope (follow-ups)
+Per-capita identity, named index/base and index-point differences, weighted means, dated FX / nominal-real bases,
+same-currency denomination scaling (M/B), summing ratios over a common base. Each needs its own table row + tests.
+
+## Dimensions
+
+1. Enforced: kind and operation agree; a changed discriminator cannot disable recursive verification.
+2. Enforced: expression and direct arithmetic check population, snapshot, and accounting metadata; common metadata propagates.
+3. Enforced: stored `precision: { places, sigfigs }` carries operand precision independently of display trailing zeros.
+4. Enforced: scaled aliases normalize at every composite factor and exponent, scaling the input numeral exactly.
+5. Enforced: derive and recompute return classified refusals with `shape`, `expected`, and `detail`; derive never appends on refusal.
+6. Enforced: aliases canonicalize at input; noncanonical stored results and conversion targets are refused, and a source unit that needs rescaling (a scaled alias) is refused as an operand.
+7. Enforced: stored rationals are reduced integer strings with positive denominators and canonical zero.
+8. Enforced: operation contexts have closed keys and types, including non-percent sums and context-free operations.
+9. Enforced: formula, factor, derived_from, raw, render, metadata, precision, and compatibility are compared on replay.
+10. Enforced: metadata object equality ignores key insertion order; missing and invalid metadata never equal explicit null.
+11. Enforced: new derivations require active transitive dependencies; historical arithmetic remains reproducible after retraction.
+12. Enforced: graph and expression traversal use explicit stacks; shared nodes are evaluated once per verification.
+13. Enforced: factor exponents use bigint, preserve grouping and quotient direction, and canonicalize idempotently.
+14. Enforced: affine atoms cannot hide in composites or cancellation; scale words are never unit atoms.
+15. Enforced: disjoint percentage shares are individually in [0,100], total at most 100, and use exactly one reference.
+16. Enforced: currency table conversion is refused; FX expressions require a dated rate and persist compatibility `unchecked`.
+17. Enforced: symbols are case-sensitive; only registered spelling aliases normalize; opaque Unicode and phrases stay distinct.
+18. Enforced: missing, undefined, and empty required fields do not substitute for explicit null; zero remains valid.
+19. Enforced: identifiers allocate exactly beyond 2^53 using bigint; operand lists remain distinct.
+20. Enforced: a supplied expression operand list must equal the formula's unique leaf set.
+21. Enforced: additive expression roots and percentage-point results use decimal places; other roots count literal significant figures.
+22. Enforced: cloned snapshots with the same spec and timestamp produce identical rows; replay appends a new identity.
+23. Documented limitation: coherent rewrites of trusted operands, context, and all dependent audit fields require external provenance to detect.
+24. Enforced: arity belongs to each table row; sums are permutation-invariant while ordered operations keep positional meaning.
+25. Enforced: denominators, positive growth starts, and bounded shares obey numeric domains; ordinary negative arithmetic remains valid.
+26. Enforced: percent, percentage-point, and fraction semantics follow typed pairs, multiplicative normalization, and explicit pct nodes.
+27. Enforced: table factors and affine offsets compose exactly; unknown and cross-dimension conversions are refused.
+28. Enforced: only decimal literals, fact identifiers, binary arithmetic, parentheses, and pct parse; unsupported syntax is refused.
+29. Enforced: rounding is half away from zero; values are plain decimals and display uses canonical units and grouping.
+30. Enforced: seeded factor trees and conversion compositions have expected values computed independently of OPERATION_RULES.
+31. Enforced: a ledger written before `context`, `precision`, and `compatibility` existed still loads and accepts new derivations. On measured, quote, and assumed rows a missing column reads as null, and a registered alias unit is canonicalized on read (unknown or scaled text stays as given); the file changes only on the next write. Derived and converted rows without those columns load, but `recompute` reports shape `legacy derived row` and `derive` refuses them as operands with the same shape until they are regenerated.
+32. Enforced: value/exact agreement. When a row stores both, `exact` must equal `value` at the value's decimal places; a legacy row that disagrees loads and is flagged `dimension 32`, and `addRow` refuses a new one.
+
+## Precedence: dimension 31 wins at read time
+
+Anything dev's shipped writer could write loads and validates. Every row is first read through `readRow`: exacts that
+are integer pairs are reduced (sign on the numerator, no leading zeros, positive denominator), decimal values lose
+leading zeros, and source rows get canonical units and null later columns. Measured exacts stay as stored because they
+are always the reduced exact of `value`. Only then do the strict dimensions run. They apply in full to derived and
+converted rows that carry this version's columns, and to every row this version writes. A source row that loads but
+still breaks a strict rule (a scale word as unit, empty metadata, an operation or derivation fields) is flagged when it
+is used: `derive` and `recompute` refuse it with shape `dimension 6`, `dimension 18`, or `dimension 1`, and `addRow`
+refuses to write a new one. Normalization never strips user data: an `exact` carrying keys beyond `num` and `den` is left exactly as written and flagged `dimension 7` on use, never silently reduced to `{ num, den }`. Reading a normalized file again changes nothing. The legacy test fixture is generated by
+dev's own `addRow` (`scripts/tests/fixtures/fidelity/gen-legacy-dev.mjs`, which pins the dev commit).
+
+## Trust boundary
+
+Recomputation verifies arithmetic against the ledger's trusted operands and operation context, not against an external
+immutable source. A zero-metre conversion rewritten from km to cm together with its target, formula, factor, precision,
+and display is indistinguishable from an honestly generated cm conversion. Single-field relabels are detected; a coherent
+rewrite needs an immutable ledger baseline or source provenance outside this arithmetic verifier.
+
+Rows carry no per-row schema marker, so a current derived row with `context`, `precision`, and `compatibility` all
+deleted reads as a legacy row: `validateLedger` skips its at-rest unit and row-shape checks, and a relabeled unit on
+it passes validation. It never becomes trusted again: `recompute` and `derive` refuse it as `legacy derived row`.
+
+## Implementation notes
+
+- Context fields live in the row's `context` column (null or an object on derived and converted rows, always null on
+  measured, quote, and assumed rows: a `KIND_RULES` column):
+  sum stores `{ disjoint, reference }`, convert stores `{ target }`. The sum rationale stays in `rationale`.
+  Schema and recomputation both require the operation's context. Context-free rows carry explicit null.
+- `schemaVersion` remains 1. A derived or converted row from an older writer (no `context`, `precision`, or
+  `compatibility`) is kept as written and never used as an operand: regenerate it with `derive` to carry precision,
+  compatibility, and complete audit fields. Older source rows need nothing: they are read with null later columns.
+- `reference` is either one text (the caller asserts one shared denominator) or a map from each operand id to its
+  denominator; the map passes only when every operand names the same non-empty denominator.
+- `addRow` canonicalizes source units and scales alias numerals, including `100 bp/person` to `1 %p/person`.
+  At rest, source-row aliases are canonicalized on read (dimension 31); current derived rows with alias units are refused. A declared result unit with a nontrivial alias scale is refused.
+  Scale exponents with absolute value above 10000 are explicitly refused instead of allocating an unbounded numeral.
+- A ratio over `%` or `%p` operands with unequal units is refused (use expr, where `%` enters `*` and `/` as a fraction).
+- convert reads its target from `to`; a declared `unit` is optional and must equal that target.
+- expr persists compatibility `unchecked` on the row as well as returning it. Population, snapshot, and accounting
+  predicates apply; a currency-rate operand needs a nonempty `valid_at`. This is arithmetic and unit verification,
+  not a guarantee of rate freshness, matching dates, population identity, or financial comparability.

package/packages/omo-codex/plugin/skills/ulw-research/scripts/claim-kinds.mjs

@@ -0,0 +1,116 @@
+// claim-kinds.mjs - the claim kinds a report sentence can carry, as one table, CLAIM_KINDS.
+//
+// A claim kind is structural: the writer marks it in the placeholder ({{V:F12:label}}), fill
+// emits it as the data-claim-kind attribute on the element it renders, and the fidelity gate
+// (fidelity-claims.mjs) checks that every marked element cites a row the kind accepts. An
+// unmarked element is a plain fact or quote and is checked only by the value and quote checks.
+// The one lexical piece is `unmarked`: a few first-person run patterns that raise a minor warning
+// when a sentence reads like the kind but carries no mark; they never raise a major. The table in
+// references/fidelity-claim-kinds.md is rendered from CLAIM_KINDS (`node claim-kinds.mjs --render-doc`).
+// Pure; node: builtins only. Korean phrases are \u escapes.
+
+import { isCliEntry } from "./entry-guard.mjs"
+
+export const CLAIM_ATTRIBUTE = "data-claim-kind"
+
+const kind = (entry) => Object.freeze({ ...entry, rowKinds: Object.freeze(entry.rowKinds), sourceKinds: entry.sourceKinds && Object.freeze(entry.sourceKinds), unmarked: entry.unmarked && Object.freeze({ ...entry.unmarked, patterns: Object.freeze(entry.unmarked.patterns) }) })
+
+// Korean pieces as \u escapes: WE_SUBJECT = uri|jeohui as a standalone subject word (+ ga|neun, or " tim-i"),
+// WE_RUN = silhaeng-haet/hayeo/hae | dol-lyeot/lyeo, DIRECT = jikjeop, RUN = silhaeng | dol-li/ryeo/ryeot/rin/ril,
+// SUBJECT = a word ending in the particle ga|i|eun|neun|kkeseo (a third party ran it, not us).
+const KO_WE_SUBJECT = "(?:^|[\\s,.;!?(])(?:\uC6B0\uB9AC|\uC800\uD76C)(?:[\uAC00\uB294]|\\s+\uD300\uC774)\\s+"
+const KO_WE_RUN = "(?:\uC2E4\uD589(?:\uD588|\uD558\uC5EC|\uD574)|\uB3CC[\uB838\uB824])"
+const KO_RUN = "(?:\uC2E4\uD589|\uB3CC[\uB9AC\uB824\uB838\uB9B0\uB9B4])"
+const KO_SUBJECT = "[^\\s,.;!?]*(?:[\uAC00\uC774\uC740\uB294]|\uAED8\uC11C)(?=\\s)"
+
+/**
+ * kind -> { prefix: placeholder prefix (null = the default form), placeholder: an example,
+ *   rowKinds: ledger row kinds it accepts, sourceKinds: meta.json kinds the snapshot holding the
+ *   cited row's own locator artifact must have (null = any), defect: code when a marked fact cites a
+ *   row it refuses, note: the rule's limits, unmarked: { code, rule, patterns } for an unmarked
+ *   sentence that reads like the kind (a minor warning only), or null }.
+ */
+export const CLAIM_KINDS = Object.freeze({
+	fact: kind({
+		prefix: null,
+		placeholder: "{{F12:label}}",
+		rowKinds: ["measured", "converted", "derived"],
+		sourceKinds: null,
+		defect: "claim_kind_mismatch",
+		note: "Accepts exactly what an unmarked numeral accepts, so marking fact is never stricter than not marking. Neither accepts an `assumed` row: an unmarked assumption reads as a fact, so it needs its `{{A:F12:label}}` mark (`claim_kind_mismatch` otherwise).",
+		unmarked: null,
+	}),
+	quote: kind({ prefix: null, placeholder: "{{Q7:label}}", rowKinds: ["quote"], sourceKinds: null, defect: "claim_kind_mismatch", note: "", unmarked: null }),
+	verified: kind({
+		prefix: "V",
+		placeholder: "{{V:F12:label}}",
+		rowKinds: ["measured", "quote"],
+		sourceKinds: ["command"],
+		defect: "unsupported_verification",
+		note: "The cited row itself must have a locator artifact inside `sources/<source_id>/` whose `meta.json` kind is `command`; another command row in the sentence never counts. Whether it is the right command for the claim is the meaning verifier's call (minor), not this gate's.",
+		unmarked: {
+			code: "verification_claim_unmarked",
+			rule: "a first-person run: we/I (have) ran, run, executed, verified by (not ran out of); by running after we/our in the sentence; \\uC6B0\\uB9AC or \\uC800\\uD76C as the subject word (+ \\uAC00, \\uB294, or \\uD300\\uC774), then \\uC2E4\\uD589\\uD588, \\uC2E4\\uD589\\uD558\\uC5EC, \\uC2E4\\uD589\\uD574, \\uB3CC\\uB838, or \\uB3CC\\uB824 in the clause with no third-party subject between; \\uC9C1\\uC811 with no third-party subject, then \\uC2E4\\uD589 or \\uB3CC\\uB9AC in the clause",
+			patterns: [
+				/\b(?:we|I)(?:'ve)?\s+(?:(?:have|had|also|then|first|just|again)\s+)*(?:ran|run|re-?ran|re-?run|executed|verified\s+by)\b(?!\s+out\s+of\b)/i,
+				/\b(?:we|our)\b.*?\bby\s+running\b/i,
+				new RegExp(`${KO_WE_SUBJECT}(?:(?!${KO_SUBJECT})[^\\s,.;!?]+\\s+)*?${KO_WE_RUN}`),
+				new RegExp(`(?:^|[,.;!?])\\s*(?:(?!${KO_SUBJECT})[^\\s,.;!?]+\\s+)*\uC9C1\uC811\\s*(?:[^\\s,.;!?]+\\s*)??${KO_RUN}`),
+			],
+		},
+	}),
+	derived: kind({ prefix: "D", placeholder: "{{D:F12:label}}", rowKinds: ["derived", "converted"], sourceKinds: null, defect: "claim_kind_mismatch", note: "", unmarked: null }),
+	assumed: kind({
+		prefix: "A",
+		placeholder: "{{A:F12:label}}",
+		rowKinds: ["assumed"],
+		sourceKinds: null,
+		defect: "claim_kind_mismatch",
+		note: "Numeric assumptions only (an assumed ledger row carries a decimal value); a qualitative assumption stays prose.",
+		unmarked: null,
+	}),
+})
+
+/** Whether a row satisfies a claim kind, given the meta.json kind of the snapshot holding its own locator artifact. */
+export function claimSatisfied(name, row, sourceKind) {
+	const entry = CLAIM_KINDS[name]
+	return Boolean(entry && row && entry.rowKinds.includes(row.kind) && (entry.sourceKinds === null || entry.sourceKinds.includes(sourceKind)))
+}
+
+/** The kind an unmarked element citing `row` must be marked with (an assumed row needs `assumed`), or null when unmarked is fine. */
+export function unmarkedRequires(row) {
+	if (!row || ["fact", "quote"].some((name) => CLAIM_KINDS[name].rowKinds.includes(row.kind))) return null
+	return Object.keys(CLAIM_KINDS).find((name) => CLAIM_KINDS[name].rowKinds.includes(row.kind)) ?? null
+}
+
+/** The kinds whose unmarked patterns match the sentence. */
+export function unmarkedKinds(text) {
+	return Object.entries(CLAIM_KINDS)
+		.filter(([, entry]) => entry.unmarked?.patterns.some((re) => re.test(text)))
+		.map(([name]) => name)
+}
+
+export const CLAIM_TABLE_BEGIN = "<!-- claim-kinds:begin (rendered from CLAIM_KINDS; do not edit by hand) -->"
+export const CLAIM_TABLE_END = "<!-- claim-kinds:end -->"
+
+const code = (text) => `\`${text}\``
+
+/** The Markdown table of references/fidelity-claim-kinds.md. */
+export function renderClaimKindTable() {
+	const head = ["| Kind | Placeholder | Attribute fill emits | Accepted row kinds | Required source kind | Defect when unsatisfied | Unmarked warning | Notes |", "|---|---|---|---|---|---|---|---|"]
+	const lines = Object.entries(CLAIM_KINDS).map(([name, entry]) => {
+		const attribute = entry.prefix === null ? `none (or ${code(`${CLAIM_ATTRIBUTE}="${name}"`)})` : code(`${CLAIM_ATTRIBUTE}="${name}"`)
+		const source = entry.sourceKinds === null ? "any" : entry.sourceKinds.map(code).join(", ")
+		const warn = entry.unmarked ? `${code(entry.unmarked.code)} on ${entry.unmarked.rule}` : "none"
+		return `| ${code(name)} | ${code(entry.placeholder)} | ${attribute} | ${entry.rowKinds.map(code).join(", ")} | ${source} | ${code(entry.defect)} | ${warn} | ${entry.note || "-"} |`
+	})
+	return `${[...head, ...lines].join("\n")}\n`
+}
+
+if (isCliEntry(import.meta.url)) {
+	if (process.argv[2] === "--render-doc" && process.argv.length === 3) process.stdout.write(renderClaimKindTable())
+	else {
+		process.stderr.write("usage: node claim-kinds.mjs --render-doc\n")
+		process.exitCode = 2
+	}
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/cli-support.mjs

@@ -1,7 +1,8 @@
 // cli-support.mjs - argument parsing, typed usage errors, exit-code mapping, and JSON file IO
 // shared by every report-tools subcommand. node: builtins only.
 
-import { readFileSync, renameSync, writeFileSync } from "node:fs"
+import { createHash } from "node:crypto"
+import { readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
 import { basename, dirname, join } from "node:path"
 
 /** A usage or input error: always exit code 2. */
@@ -87,11 +88,24 @@ export function readJsonFile(path) {
 	}
 }
 
-/** Write JSON through a sibling temp file + rename, so a crash never leaves a half-written file. */
-export function writeJsonAtomic(path, value) {
+/** The sha256 hex digest of a string or bytes: the one hash every record and receipt carries. */
+export const sha256Of = (content) => createHash("sha256").update(content).digest("hex")
+
+/** Write text through a sibling temp file + rename; a failed write removes the temp file. */
+export function writeTextAtomic(path, text) {
 	const temp = join(dirname(path), `.${basename(path)}.${process.pid}.${Date.now()}.tmp`)
-	writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`)
-	renameSync(temp, path)
+	try {
+		writeFileSync(temp, text)
+		renameSync(temp, path)
+	} catch (error) {
+		rmSync(temp, { force: true })
+		throw error
+	}
+}
+
+/** Write JSON through writeTextAtomic, so a crash never leaves a half-written file. */
+export function writeJsonAtomic(path, value) {
+	writeTextAtomic(path, `${JSON.stringify(value, null, 2)}\n`)
 }
 
 /** Print a result: JSON on stdout, one summary line on stderr. */

package/packages/omo-codex/plugin/skills/ulw-research/scripts/contracts.mjs

@@ -6,6 +6,16 @@
 
 export const SCHEMA_VERSION = 1
 
+/** The severity vocabulary in rank order; every DEFECT_CODES entry uses one of these. */
+export const SEVERITIES = Object.freeze(["blocker", "major", "minor"])
+
+/** Defect counts per severity, then total. */
+export function countDefects(defects) {
+	const counts = Object.fromEntries(SEVERITIES.map((severity) => [severity, 0]))
+	for (const defect of defects) counts[defect.severity] += 1
+	return { ...counts, total: defects.length }
+}
+
 function deepFreeze(value) {
 	if (value === null || typeof value !== "object") return value
 	for (const key of Object.keys(value)) deepFreeze(value[key])
@@ -48,7 +58,7 @@ export const DEFECT_CODES = deepFreeze({
 	pointer_label_mismatch: { severity: "blocker", integrity: true, hint: "The placeholder's label is not the row's label; check the id, then the label." },
 	quote_anchor_unresolved: { severity: "blocker", integrity: true, hint: "A from or to anchor is missing or occurs more than once in the quote; pick unique anchor words." },
 	unit_duplicated: { severity: "blocker", integrity: true, hint: "The unit after the placeholder repeats the row's unit; use :value or remove the unit." },
-	polish_diff_fail: { severity: "blocker", integrity: true, hint: "The polish pass changed numbers, tickers, or table rows; revert to the pre-polish artifact and apply the language fixes only." },
+	polish_diff_fail: { severity: "blocker", integrity: true, hint: "The polish pass changed numbers, tickers, table rows, claim ids, markup, or hidden content; revert to the pre-polish artifact and apply the language fixes only." },
 	fidelity_interview_incomplete: { severity: "blocker", integrity: true, hint: "A fidelity field is pending or missing in brief.md; answer the open question or record its default, then rerun." },
 	derived_not_allowed: { severity: "blocker", integrity: true, hint: "The brief allows no derived or assumed numbers; cite a source row directly or change the brief with the requester." },
 	source_outside_floor: { severity: "blocker", integrity: true, hint: "The row's source is outside the source floor the brief records; use a source the brief allows or remove the fact." },
@@ -57,7 +67,8 @@ export const DEFECT_CODES = deepFreeze({
 	quote_unbound: { severity: "blocker", integrity: true, hint: "A direct quotation has no ledger quote row; register it with fact quote and insert it through its placeholder." },
 	edition_unverified: { severity: "blocker", integrity: true, hint: "The delivered file has no matching fact verify record; run fact verify on that edition and record it with --verified-by." },
 	untraceable_number: { severity: "major", integrity: false, hint: "Replace the typed number with a {{F<n>}} placeholder backed by a ledger row, or register it as assumed with a rationale." },
-	unsupported_verification: { severity: "major", integrity: false, hint: "The sentence claims a tool check that no recorded command output backs; link the recorded output row or remove the claim." },
+	unsupported_verification: { severity: "major", integrity: false, hint: "A sentence marked verified (data-claim-kind=\"verified\") cites a row that is not recorded command output; cite the recorded output row or drop the verified mark." },
+	claim_kind_mismatch: { severity: "major", integrity: false, hint: "An element marked with a claim kind (data-claim-kind) cites a row that kind does not accept, or the kind is unknown; cite a row of that kind or fix the mark (references/fidelity-claim-kinds.md)." },
 	conflicting_readings: { severity: "major", integrity: false, hint: "Two ledger rows with different periods or qualifiers are cited as one fact; split the sentence or retire one row." },
 	hedge_dropped: { severity: "major", integrity: false, hint: "Restore the qualifier the source uses (estimated, about, not yet)." },
 	direction_flipped: { severity: "major", integrity: false, hint: "The source states the opposite direction; rewrite from the quote." },
@@ -65,7 +76,8 @@ export const DEFECT_CODES = deepFreeze({
 	qualifier_dropped: { severity: "major", integrity: false, hint: "The source bounds this value (up to, at least, about); restore the qualifier or use :q." },
 	unbound_sentence: { severity: "major", integrity: false, hint: "Bind the sentence to a fact, a quote, a citation, or a claim-graph node with data-claim." },
 	meaning_drift_confirmed: { severity: "major", integrity: false, hint: "Two independent readers found the same drift; rewrite from the quote or dispute with a reason." },
-	polish_edit_rejected: { severity: "major", integrity: false, hint: "The edit changed a number, a hedge, a qualifier, a link, or a claim id; re-propose the language fix only." },
+	meaning_unverified: { severity: "major", integrity: false, hint: "No meaning reader judged this pair, or no strong reader judged a force_strong pair; run the missing reader on pairs.json and rerun fact meaning-check." },
+	polish_edit_rejected: { severity: "major", integrity: false, hint: "The edit changed a number, a hedge, a qualifier, a link, or a claim id, or contained <, > or &; re-propose the language fix only, narrowed to the words around any entity or tag." },
 	polish_hedging_decreased: { severity: "major", integrity: false, hint: "The polish pass removed qualifiers; restore them." },
 	polish_text_churn: { severity: "major", integrity: false, hint: "More than half the text changed during polish; the pass composed instead of proofreading." },
 	snapshot_mismatch: { severity: "major", integrity: false, hint: "The operands come from different collection windows; use rows from one window or state the windows separately." },
@@ -73,6 +85,7 @@ export const DEFECT_CODES = deepFreeze({
 	quote_stale_version: { severity: "major", integrity: false, hint: "The quoted source revision differs from the revision the report targets; re-snapshot the target revision or date the quote." },
 	quote_fuzzy_match: { severity: "minor", integrity: false, hint: "The source text is OCR-noisy; confirm the snapshot and prefer the raw document." },
 	name_outside_quote: { severity: "minor", integrity: false, hint: "A name in the sentence is not in the cited quote; add the source or remove the name." },
+	verification_claim_unmarked: { severity: "minor", integrity: false, hint: "The sentence reads as a check we ran but carries no verified mark; mark it {{V:F<n>:label}} on a recorded command-output row, or reword it." },
 	scope_widened_warn: { severity: "minor", integrity: false, hint: "The sentence uses a broader scope word than the quote; confirm the scope or narrow it." },
 	particle_unverified: { severity: "minor", integrity: false, hint: "The particle after this value could not be checked; read it aloud and fix it by hand if wrong." },
 	fallback_without_entity: { severity: "minor", integrity: false, hint: "The replacement quote has no entity for attribution; set one on the row." },
@@ -87,10 +100,10 @@ export const FIDELITY_CODES = Object.freeze([
 	"unresolved_placeholder", "value_mismatch", "unit_mismatch", "quote_not_verbatim", "claim_status_invalid",
 	"incompatible_operands", "pointer_label_mismatch", "quote_anchor_unresolved", "unit_duplicated", "polish_diff_fail",
 	"fidelity_interview_incomplete", "derived_not_allowed", "source_outside_floor", "snapshot_hash_mismatch",
-	"chart_value_untraceable", "quote_unbound", "edition_unverified", "untraceable_number", "unsupported_verification",
+	"chart_value_untraceable", "quote_unbound", "edition_unverified", "untraceable_number", "unsupported_verification", "claim_kind_mismatch",
 	"conflicting_readings", "hedge_dropped", "direction_flipped", "causality_added", "qualifier_dropped", "unbound_sentence",
-	"meaning_drift_confirmed", "polish_edit_rejected", "polish_hedging_decreased", "polish_text_churn", "snapshot_mismatch",
-	"join_integrity_fail", "quote_stale_version", "quote_fuzzy_match", "name_outside_quote", "scope_widened_warn",
+	"meaning_drift_confirmed", "meaning_unverified", "polish_edit_rejected", "polish_hedging_decreased", "polish_text_churn", "snapshot_mismatch",
+	"join_integrity_fail", "quote_stale_version", "quote_fuzzy_match", "name_outside_quote", "verification_claim_unmarked", "scope_widened_warn",
 	"particle_unverified", "fallback_without_entity", "meaning_drift_warn", "polish_edit_unlocated", "polish_link_changed",
 	"polish_name_changed",
 ])
@@ -184,6 +197,14 @@ export function validateOutcomeManifest(manifest) {
 	if (isObject(manifest.gates)) {
 		for (const gate of GATE_NAMES) check(errors, GATE_STATUSES.includes(manifest.gates[gate]), `gates.${gate} must be one of ${GATE_STATUSES.join(", ")}`)
 	} else errors.push("gates must be an object")
+	if (manifest.gateHistory !== undefined) {
+		if (!Array.isArray(manifest.gateHistory)) errors.push("gateHistory must be an array")
+		else for (const entry of manifest.gateHistory) {
+			check(errors, isObject(entry) && GATE_NAMES.includes(entry.gate) && GATE_STATUSES.includes(entry.status)
+				&& typeof entry.at === "string" && ISO_DATE.test(entry.at)
+				&& (entry.reason === undefined || typeof entry.reason === "string"), "gateHistory entries must have a known gate, status, timestamp, and optional reason")
+		}
+	}
 	if (Array.isArray(manifest.residualDefects)) manifest.residualDefects.forEach((defect, index) => validateDefect(defect, `residualDefects[${index}]`, errors))
 	else errors.push("residualDefects must be an array")
 	check(errors, manifest.repair === null || isObject(manifest.repair), "repair must be null or an object")

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fact-commands-meaning.mjs

@@ -0,0 +1,191 @@
+// 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
+// `{ skipped: true }` when it is off. fact meaning-check ingests the readers' verdict files
+// (meaning-check.mjs), writes fidelity-meaning-defects.json (a fidelity record bound to the pairs'
+// artifact_sha256 and report, through writeFidelityRecord), and records the run in
+// fidelity-calibration.jsonl: a header with the promotion criterion on first write, then per run
+// one run line plus one line per flagged pair. The run id hashes the inputs only, so a rerun or a
+// --dispute rerun of the same inputs replaces that run's lines in place (disputes carry forward)
+// instead of counting a second run. Neither command calls a model or the network.
+
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+
+import { CliError, parseArgs, readJsonFile, sha256Of, writeJsonAtomic, writeTextAtomic } from "./cli-support.mjs"
+import { countDefects } from "./contracts.mjs"
+import { markdownAsHtml, readEdition } from "./fact-commands-verify.mjs"
+import { readLedger } from "./fact-ledger.mjs"
+import { validateLedger } from "./fact-ledger-schema.mjs"
+import { extractPairs, PAIR_KINDS } from "./fact-pairs.mjs"
+import { FIDELITY_INCOMPLETE, meaningCheckEnabled, requireLockedBrief } from "./fidelity-brief.mjs"
+import { MEANING_RECORD, writeFidelityRecord } from "./fidelity-records.mjs"
+import { blocksDelivery } from "./gates-fidelity.mjs"
+import { ingestVerdicts, unverifiedDefects, VERDICT_SCHEMA } from "./meaning-check.mjs"
+
+export const PAIRS_FILE = "pairs.json"
+export const CALIBRATION_FILE = "fidelity-calibration.jsonl"
+/** Starting values, recorded in the calibration log header; changed only with evidence. */
+export const PROMOTION = Object.freeze({ code: "meaning_drift_confirmed", to: "integrity", min_runs: 20, max_disputed_to_confirmed: 0.1, false_block_window: 20, max_report_false_blocks_in_window: 2 })
+
+/** The command status: fail when any defect blocks delivery under the registry policy. */
+export const meaningStatus = (defects) => (defects.some(blocksDelivery) ? "fail" : "pass")
+
+const sessionOf = (flags) => {
+	const dir = flags["session-dir"] ?? process.env.SESSION_DIR
+	return dir && dir !== true ? resolve(dir) : null
+}
+const inSession = (session, name, flag) => {
+	if (session === null) throw new CliError(`${flag} is required without --session-dir (or SESSION_DIR)`)
+	return join(session, name)
+}
+
+function readLedgerFrom(flags, session) {
+	if (flags.ledger === undefined) {
+		if (session === null) throw new CliError("--ledger is required without --session-dir (or SESSION_DIR)")
+		return readLedger(session)
+	}
+	const ledger = readJsonFile(flags.ledger)
+	const errors = validateLedger(ledger)
+	if (errors.length > 0) throw new CliError(`${flags.ledger} is not a valid fact ledger: ${errors[0]}`)
+	return ledger
+}
+
+function briefState(flags, session) {
+	const path = flags.brief ?? inSession(session, "brief.md", "--brief")
+	const lock = requireLockedBrief(path)
+	if (lock.exitCode === 2) throw new CliError(`${path}: malformed ## Fidelity block: ${lock.errors.join("; ")}`)
+	return { path, locked: lock.locked, off: !meaningCheckEnabled(lock.parsed) }
+}
+
+function runPairs(args) {
+	const [report] = args.positionals
+	const { flags } = args
+	if (!report) throw new CliError("usage: fact pairs <report> [--format html|md] [--ledger F] [--claims claims.json] [--changed-since <fill-map.json>] [--brief brief.md] [--out pairs.json]")
+	const session = sessionOf(flags)
+	const out = resolve(flags.out ?? inSession(session, PAIRS_FILE, "--out"))
+	const brief = briefState(flags, session)
+	if (!brief.locked) {
+		const json = { command: "fact pairs", status: "fail", exitCode: 1, error: "fidelity_interview_incomplete", message: `${brief.path} has no locked ## Fidelity block` }
+		return { json, summary: `fact pairs: ${json.message}`, exitCode: 1 }
+	}
+	if (brief.off) {
+		const record = { schemaVersion: 1, skipped: true, reason: "meaning check: off", pairs: [] }
+		writeJsonAtomic(out, record)
+		return { json: { command: "fact pairs", status: "skipped", exitCode: 0, data: { out, ...record } }, summary: "fact pairs: skipped (meaning check: off)", exitCode: 0 }
+	}
+	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 html = edition.format === "md" ? markdownAsHtml(edition.text, edition.entries, ledger).html : edition.text
+	const pairs = extractPairs(html, ledger, claims, changed)
+	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 }
+	writeJsonAtomic(out, record)
+	const summary = `fact pairs: ${counts.total} pair(s), ${counts.force_strong} routed to the strong reader`
+	return { json: { command: "fact pairs", status: "pass", exitCode: 0, data: { out, ...record, pairs: undefined } }, summary, exitCode: 0 }
+}
+
+/** Every line of the log after the header, in file order; a corrupt line is a usage error naming path:line. */
+function calibrationRows(path) {
+	if (!existsSync(path)) return []
+	const rows = []
+	for (const [index, line] of readFileSync(path, "utf8").split("\n").entries()) {
+		if (line.trim() === "") continue
+		try {
+			rows.push(JSON.parse(line))
+		} catch (error) {
+			throw new CliError(`${path}:${index + 1}: corrupt calibration log line (${error.message}); repair or move the file`)
+		}
+	}
+	return rows.filter((row) => row.header !== true)
+}
+
+/** The promotion criterion evaluated over the log: runs, disputed-to-confirmed, report-level false blocks. */
+export function promotionEligibility(rows) {
+	const runs = [...new Set(rows.map((row) => row.run_id))]
+	const confirmed = rows.filter((row) => row.run !== true && row.confirmed)
+	const disputed = confirmed.filter((row) => row.disputed).length
+	const ratio = confirmed.length === 0 ? null : disputed / confirmed.length
+	const falseBlocks = runs.slice(-PROMOTION.false_block_window).filter((run) => {
+		const blocking = confirmed.filter((row) => row.run_id === run)
+		return blocking.length > 0 && blocking.every((row) => row.disputed)
+	}).length
+	const eligible = runs.length >= PROMOTION.min_runs && ratio !== null && ratio < PROMOTION.max_disputed_to_confirmed && falseBlocks <= PROMOTION.max_report_false_blocks_in_window
+	return { runs: runs.length, confirmed: confirmed.length, disputed_confirmed: disputed, disputed_to_confirmed: ratio, report_false_blocks_in_window: falseBlocks, eligible }
+}
+
+/**
+ * Writes this run's lines: one run line (so a run with no flagged pair still counts) and one line per
+ * flagged pair. A run id already in the log is replaced in place, keeping its position in the false
+ * block window and any earlier dispute on a pair the new lines do not dispute.
+ */
+function recordCalibration(path, lines, runId, pairsSha) {
+	const before = calibrationRows(path)
+	const previous = before.filter((row) => row.run_id === runId)
+	const disputes = new Map(previous.filter((row) => row.disputed).map((row) => [row.pair_id, row.reason]))
+	const pairRows = lines.map((line) => {
+		const row = { ...JSON.parse(line), run_id: runId, pairs_sha256: pairsSha }
+		return !row.disputed && disputes.has(row.pair_id) ? { ...row, disputed: true, reason: disputes.get(row.pair_id) } : row
+	})
+	const rows = [{ run: true, run_id: runId, pairs_sha256: pairsSha, flagged: pairRows.length }, ...pairRows]
+	const at = previous.length === 0 ? before.length : before.indexOf(previous[0])
+	const after = [...before.slice(0, at).filter((row) => row.run_id !== runId), ...rows, ...before.slice(at).filter((row) => row.run_id !== runId)]
+	const header = { header: true, schemaVersion: 1, promotion: PROMOTION, note: "starting values; change them only with evidence" }
+	writeTextAtomic(path, `${[header, ...after].map((row) => JSON.stringify(row)).join("\n")}\n`)
+	return { written: pairRows.length, replaced: previous.length > 0, rows: after }
+}
+
+/** A `{ skipped: true }` pairs file is accepted only when the locked brief turns the meaning check off. */
+function skippedRefusal(flags, session) {
+	const brief = briefState(flags, session)
+	if (!brief.locked) return { error: FIDELITY_INCOMPLETE, message: `${brief.path} has no locked ## Fidelity block, so a skipped meaning check cannot be accepted` }
+	if (!brief.off) return { error: "meaning_check_required", message: `${flags.pairs} says skipped but ${brief.path} has meaning check on; rerun fact pairs` }
+	return null
+}
+
+function runMeaningCheck(args) {
+	const { flags } = args
+	const usage = "usage: fact meaning-check --pairs pairs.json --verdicts cheap.json [--verdicts strong.json] [--dispute P<n> --reason TEXT] [--run-id ID] [--calibration F] [--out F]"
+	if (flags.pairs === undefined || !Array.isArray(flags.verdicts)) throw new CliError(usage)
+	const session = sessionOf(flags)
+	const pairsText = readFileSync(flags.pairs, "utf8")
+	const pairsDoc = readJsonFile(flags.pairs)
+	if (pairsDoc?.skipped === true) {
+		const refusal = skippedRefusal(flags, session)
+		if (refusal !== null) return { json: { command: "fact meaning-check", status: "fail", exitCode: 1, ...refusal }, summary: `fact meaning-check: ${refusal.message}`, exitCode: 1 }
+		return { json: { command: "fact meaning-check", status: "skipped", exitCode: 0, defects: [] }, summary: JSON.stringify({ command: "fact meaning-check", status: "skipped" }), exitCode: 0 }
+	}
+	if (typeof pairsDoc?.artifact_sha256 !== "string" || typeof pairsDoc.report !== "string") throw new CliError(`${flags.pairs} names no artifact_sha256 and report, so the meaning record cannot be bound to an edition; rerun fact pairs`)
+	for (const file of flags.verdicts) readJsonFile(file)
+	const verdictTexts = flags.verdicts.map((file) => readFileSync(file, "utf8"))
+	const dispute = flags.dispute === undefined ? undefined : { pair_id: flags.dispute, reason: args.required("reason") }
+	let result
+	try {
+		result = ingestVerdicts(pairsDoc, flags.verdicts, dispute ? { dispute } : {})
+	} catch (error) {
+		throw new CliError(`invalid verdict input: ${error.message}`)
+	}
+	const out = resolve(flags.out ?? inSession(session, MEANING_RECORD, "--out"))
+	const calibration = resolve(flags.calibration ?? join(session ?? dirname(out), CALIBRATION_FILE))
+	const runId = flags["run-id"] ?? sha256Of([pairsText, ...verdictTexts].join("\0")).slice(0, 16)
+	const pairsSha = pairsDoc.pairs_sha256 ?? sha256Of(pairsText)
+	const log = recordCalibration(calibration, result.calibrationLines, runId, pairsSha)
+	const defects = [...result.defects, ...unverifiedDefects(result.unverified)]
+	const counts = countDefects(defects)
+	const status = meaningStatus(defects)
+	const exitCode = status === "fail" ? 1 : 0
+	const record = writeFidelityRecord(out, "meaning", { command: "fact meaning-check", status, exitCode, artifact_sha256: pairsDoc.artifact_sha256, report: pairsDoc.report, run_id: runId, pairs_sha256: pairsSha, defects, counts, dropped: result.dropped, unverified: result.unverified, calibration_path: calibration, calibration_written: log.written, calibration_replaced: log.replaced, promotion_eligibility: promotionEligibility(log.rows) })
+	const confirmed = result.defects.filter((defect) => defect.code === "meaning_drift_confirmed").length
+	const summary = JSON.stringify({ command: "fact meaning-check", status, defects: defects.length, confirmed, warn: result.defects.length - confirmed, dropped: result.dropped.length, unverified: result.unverified.length })
+	return { json: { ...record, out }, summary, exitCode }
+}
+
+/** @param {string[]} argv the arguments after `fact pairs` or `fact meaning-check` */
+export function runFactMeaning(sub, argv) {
+	const args = parseArgs(argv, { repeatable: ["verdicts"] })
+	return sub === "pairs" ? runPairs(args) : runMeaningCheck(args)
+}