lazycodex-ai 5.1.44 → 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/claims-index.mjs

@@ -0,0 +1,125 @@
+// claims-index.mjs - deterministic index of claim-graph.md: the one Markdown table whose header
+// names claim_id, statement, risk tier, and status, plus the ids listed under the
+// `## verified-claims` digest. Pure function of the text; node: builtins only.
+
+const CLAIM_ID = /^C\d+$/
+const REQUIRED_COLUMNS = Object.freeze({ claim_id: "claim_id", statement: "statement", risk: "risk tier", status: "status" })
+
+/** Split one table line on unescaped pipes; drops the leading and trailing border cells. */
+function splitRow(line) {
+	const cells = []
+	let current = ""
+	for (let index = 0; index < line.length; index += 1) {
+		const char = line[index]
+		if (char === "\\" && line[index + 1] === "|") {
+			current += "|"
+			index += 1
+		} else if (char === "|") {
+			cells.push(current)
+			current = ""
+		} else current += char
+	}
+	cells.push(current)
+	const trimmed = cells.map((value) => value.trim())
+	if (line.trim().startsWith("|")) trimmed.shift()
+	if (line.trim().endsWith("|")) trimmed.pop()
+	return trimmed
+}
+
+function normalizeHeader(value) {
+	return value.replace(/`/g, "").trim().toLowerCase().replace(/[\s_-]+/g, " ")
+}
+
+function columnIndexes(header) {
+	const names = header.map(normalizeHeader)
+	const indexes = {}
+	for (const [key, name] of Object.entries(REQUIRED_COLUMNS)) indexes[key] = names.indexOf(normalizeHeader(name))
+	return Object.values(indexes).every((index) => index >= 0) ? indexes : null
+}
+
+function isSeparator(line) {
+	return /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$/.test(line)
+}
+
+const DIGEST_HEADING = normalizeHeader("verified-claims")
+
+/** `offset` is the index of `lines[0]` in the document, for line numbers in errors. */
+function verifiedIds(lines, offset, errors) {
+	const ids = []
+	let inside = false
+	for (const [index, line] of lines.entries()) {
+		const heading = /^(#{1,6})\s+(.*)$/.exec(line)
+		if (heading) {
+			const name = normalizeHeader(heading[2])
+			inside = name === DIGEST_HEADING
+			if (!inside && name.startsWith(DIGEST_HEADING)) {
+				errors.push(`line ${offset + index + 1}: heading "${line.trim()}" is not the digest heading "## verified-claims"; drop the suffix so its entries are read`)
+			}
+			continue
+		}
+		if (!inside) continue
+		// An entry is a list item or a table row; prose lines never verify. Only the id an entry
+		// starts with is verified; ids mentioned later in the line are not.
+		const leading = /^\s*(?:(?:[-*+]|\d+[.)])\s+|\|\s*)`?(C\d+)\b/.exec(line)
+		if (leading && !ids.includes(leading[1])) ids.push(leading[1])
+	}
+	return ids
+}
+
+/** Blank every line of a fenced code block (``` or ~~~, fences included) so nothing in it is read. */
+function unfenced(lines) {
+	let fence = null
+	return lines.map((line) => {
+		const marker = /^\s{0,3}(`{3,}|~{3,})/.exec(line)
+		if (fence === null) {
+			if (marker) fence = marker[1]
+			return marker ? "" : line
+		}
+		const closes = marker && marker[1][0] === fence[0] && marker[1].length >= fence.length && line.trim() === marker[1]
+		if (closes) fence = null
+		return ""
+	})
+}
+
+/** @returns {{ claims: { claim_id: string, statement: string, risk: string, status: string, in_verified: boolean }[], errors: string[] }} */
+export function indexClaims(markdown) {
+	const lines = unfenced(markdown.split(/\r?\n/))
+	const errors = []
+	const headerAt = lines.findIndex((line) => line.trim().startsWith("|") && columnIndexes(splitRow(line)) !== null)
+	if (headerAt < 0) {
+		return { claims: [], errors: ["no claim table: a Markdown table with claim_id, statement, risk tier, and status columns is required"] }
+	}
+	const header = splitRow(lines[headerAt])
+	const columns = columnIndexes(header)
+	const hasSeparator = isSeparator(lines[headerAt + 1] ?? "")
+	if (!hasSeparator) errors.push(`line ${headerAt + 2}: claim table header must be followed by a separator row`)
+	const firstRow = headerAt + (hasSeparator ? 2 : 1)
+	const rows = []
+	let tableEnd = firstRow
+	for (let index = firstRow; index < lines.length && lines[index].trim().startsWith("|"); index += 1) {
+		tableEnd = index + 1
+		const cells = splitRow(lines[index])
+		const at = `line ${index + 1}`
+		if (cells.length !== header.length) {
+			errors.push(`${at}: expected ${header.length} cells, found ${cells.length}`)
+			continue
+		}
+		const claimId = cells[columns.claim_id].replace(/`/g, "")
+		if (!CLAIM_ID.test(claimId)) {
+			errors.push(`${at}: claim_id "${claimId}" must match C<n>`)
+			continue
+		}
+		if (rows.some((row) => row.claim_id === claimId)) {
+			errors.push(`${at}: duplicate claim_id ${claimId}`)
+			continue
+		}
+		rows.push({ claim_id: claimId, statement: cells[columns.statement], risk: cells[columns.risk], status: cells[columns.status] })
+	}
+	// The digest section ends at the claim table: scan each side on its own so it cannot carry across.
+	const verified = [...new Set([...verifiedIds(lines.slice(0, headerAt), 0, errors), ...verifiedIds(lines.slice(tableEnd), tableEnd, errors)])]
+	for (const id of verified) {
+		if (!rows.some((row) => row.claim_id === id)) errors.push(`verified-claims lists ${id}, which has no claim row`)
+	}
+	const claims = rows.map((row) => ({ ...row, in_verified: verified.includes(row.claim_id) }))
+	return { claims, errors }
+}

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])
@@ -39,12 +49,72 @@ export const DEFECT_CODES = deepFreeze({
 	layout_scroll_container: { severity: "minor", integrity: false, hint: "Scrolling content prints clipped; make the content fit or wrap the table in a scroll wrapper only for HTML deliverables." },
 	layout_image_distorted: { severity: "major", integrity: false, hint: "Preserve the image aspect ratio (object-fit: contain inside a fixed container)." },
 	layout_sibling_overlap: { severity: "major", integrity: false, hint: "Separate the overlapping elements (margins, grid, or a slide split)." },
+	unresolved_placeholder: { severity: "blocker", integrity: true, hint: "Register the fact with fact add or remove the sentence; a placeholder is never filled with a guess." },
+	value_mismatch: { severity: "blocker", integrity: true, hint: "Re-run fact fill; never edit a filled value by hand." },
+	unit_mismatch: { severity: "blocker", integrity: true, hint: "Re-run fact fill, or derive a converted row with fact derive --op convert." },
+	quote_not_verbatim: { severity: "blocker", integrity: true, hint: "Re-insert the quote through its {{Q<n>}} placeholder; after a second failure the sentence is replaced by the quote." },
+	claim_status_invalid: { severity: "blocker", integrity: true, hint: "The claim id is unknown, refuted, unresolved, or not in verified-claims; move the sentence to Gaps or Contradictions, or remove it." },
+	incompatible_operands: { severity: "blocker", integrity: true, hint: "The operands differ in unit, population, period, or basis for this operation; fix the rows or declare the operation that fits." },
+	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, 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." },
+	snapshot_hash_mismatch: { severity: "blocker", integrity: true, hint: "The source snapshot changed after it was pinned; re-snapshot the source and re-register its rows." },
+	chart_value_untraceable: { severity: "blocker", integrity: true, hint: "A chart value, tick, or data file does not match its ledger-backed data source; re-render the chart from the exported data." },
+	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: "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." },
+	causality_added: { severity: "major", integrity: false, hint: "The source states no cause; state the correlation or quote the source." },
+	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." },
+	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." },
+	join_integrity_fail: { severity: "major", integrity: false, hint: "A table row combines facts from different source observations; keep each row to one observation or split it." },
+	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." },
+	meaning_drift_warn: { severity: "minor", integrity: false, hint: "A separate reader found the sentence changes scope, subject, or certainty; rewrite from the quote." },
+	polish_edit_unlocated: { severity: "minor", integrity: false, hint: "The edit's before-text was not found exactly once; re-propose against the current text." },
+	polish_link_changed: { severity: "minor", integrity: false, hint: "A link was altered or removed during polish; restore it." },
+	polish_name_changed: { severity: "minor", integrity: false, hint: "A proper noun changed during polish; restore it." },
 })
 
+/** Codes only the fidelity verifier raises (fact ledger, fill, verify, meaning, polish). */
+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", "claim_kind_mismatch",
+	"conflicting_readings", "hedge_dropped", "direction_flipped", "causality_added", "qualifier_dropped", "unbound_sentence",
+	"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",
+])
+const FIDELITY_SET = new Set(FIDELITY_CODES)
+
 const LAYOUT_PREFIX = "layout_"
 /** Codes checkStatic can raise (G1-G17). */
 export const STATIC_CODES = Object.freeze(
-	Object.keys(DEFECT_CODES).filter((code) => !code.startsWith(LAYOUT_PREFIX) && code !== "missing_promised_deliverable"),
+	Object.keys(DEFECT_CODES).filter(
+		(code) => !code.startsWith(LAYOUT_PREFIX) && code !== "missing_promised_deliverable" && !FIDELITY_SET.has(code),
+	),
 )
 /** Codes checkLayout can raise (L1-L5). */
 export const LAYOUT_CODES = Object.freeze(Object.keys(DEFECT_CODES).filter((code) => code.startsWith(LAYOUT_PREFIX)))
@@ -59,10 +129,10 @@ export const LANES = Object.freeze(["template-strict", "template-vibe", "no-form
 export const STATES = Object.freeze(["none", "partial", "complete"])
 export const DELIVERABLE_FORMATS = Object.freeze(["pdf", "docx", "html", "md", "latex", "slides", "post"])
 export const DELIVERABLE_STATUSES = Object.freeze(["pending", "delivered", "blocked_capability", "skipped", "failed"])
-export const GATE_NAMES = Object.freeze(["static", "layout", "visual", "proofread"])
+export const GATE_NAMES = Object.freeze(["static", "fidelity", "layout", "visual", "proofread"])
 export const GATE_STATUSES = Object.freeze(["pass", "fail", "not_run"])
 export const LINEAGE_MODES = Object.freeze(["inline", "section"])
-export const ANSWERED_BY = Object.freeze(["user", "default", "request"])
+export const ANSWERED_BY = Object.freeze(["user", "default", "request", "pending"])
 export const REPAIR_DEFAULTS = Object.freeze({ maxAttempts: 3, plateauLimit: 2, wallClockMs: 15 * 60 * 1000 })
 export const DESIGN_SPEC_SECTIONS = Object.freeze([
 	"Extracted from",
@@ -127,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")
@@ -134,6 +212,14 @@ export function validateOutcomeManifest(manifest) {
 	return { ok: errors.length === 0, errors }
 }
 
+/** A copy of a manifest written before a gate existed: every absent gate key becomes not_run. */
+export function normalizeManifest(manifest) {
+	if (!isObject(manifest) || !isObject(manifest.gates)) return manifest
+	const gates = { ...manifest.gates }
+	for (const gate of GATE_NAMES) if (!Object.hasOwn(gates, gate)) gates[gate] = "not_run"
+	return { ...manifest, gates }
+}
+
 function isMeasure(value) {
 	return Array.isArray(value) && value.length === 3 && value.every((n) => Number.isInteger(n) && n >= 0)
 }