lazycodex-ai 5.1.45 → 5.1.46

package/packages/shared-skills/skills/ulw-research/references/report-gates.md

@@ -44,7 +44,7 @@ Raised only by the fidelity verifier (the fact ledger, fill, verify, meaning, an
 | `pointer_label_mismatch` | blocker | true | A placeholder's label differs from the referenced ledger row's label (a typo guard on the id). | The placeholder's label is not the row's label; check the id, then the label. |
 | `quote_anchor_unresolved` | blocker | true | A quote cut's from or to anchor is absent, occurs more than once, or appears in reverse order in the quote. | A from or to anchor is missing or occurs more than once in the quote; pick unique anchor words. |
 | `unit_duplicated` | blocker | true | A unit-bearing placeholder is followed by another copy of its own unit. | The unit after the placeholder repeats the row's unit; use :value or remove the unit. |
-| `polish_diff_fail` | blocker | true | The polish pass changed protected fact values, numerals outside fact spans, tickers, or table row counts. | The polish pass changed numbers, tickers, or table rows; revert to the pre-polish artifact and apply the language fixes only. |
+| `polish_diff_fail` | blocker | true | The polish pass changed protected fact spans, numerals or units, tickers, table rows, or any markup byte (including every attribute, comments, and script/style/template content). | Revert to the pre-polish artifact and apply text-node edits only; markup changes require the full fidelity gates. |
 | `fidelity_interview_incomplete` | blocker | true | A fidelity field in the brief is still pending or missing when a fidelity command runs. | A fidelity field is pending or missing in brief.md; answer the open question or record its default, then rerun. |
 | `derived_not_allowed` | blocker | true | A placeholder resolves to a derived, converted, or assumed row while the brief allows no derived numbers. | The brief allows no derived or assumed numbers; cite a source row directly or change the brief with the requester. |
 | `source_outside_floor` | blocker | true | A ledger row's source lies outside the source floor the brief records (pointed sources only, or the allowed source classes). | The row's source is outside the source floor the brief records; use a source the brief allows or remove the fact. |
@@ -53,7 +53,8 @@ Raised only by the fidelity verifier (the fact ledger, fill, verify, meaning, an
 | `quote_unbound` | blocker | true | A direct quotation in the report has no ledger quote row behind it; a citation marker alone does not bind it. | A direct quotation has no ledger quote row; register it with fact quote and insert it through its placeholder. |
 | `edition_unverified` | blocker | true | A delivered edition has no fact verify record whose artifact hash matches the delivered source. | The delivered file has no matching fact verify record; run fact verify on that edition and record it with --verified-by. |
 | `untraceable_number` | major | false | A number or date in prose or a table cell resolves to no ledger row and is not structural; a citation does not exempt it. | Replace the typed number with a {{F<n>}} placeholder backed by a ledger row, or register it as assumed with a rationale. |
-| `unsupported_verification` | major | false | A sentence asserts a command or tool check that no recorded command-output row backs. | The sentence claims a tool check that no recorded command output backs; link the recorded output row or remove the claim. |
+| `unsupported_verification` | major | false | A fact bound to a `verified` mark (`data-claim-kind="verified"`, from a `{{V:F<n>:label}}` placeholder) cites a row whose own locator artifact does not sit in a recorded command-output snapshot, or the mark binds no fact of its own. Another command row in the same sentence never counts. Unmarked prose is never raised here. | 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` | major | false | A fact bound to a claim kind cites a row of a kind that claim kind does not accept, a fact sits under marks of two different kinds (nested marks), a mark binds no fact of its own, or a mark names an unknown kind; the kinds are in [fidelity-claim-kinds.md](fidelity-claim-kinds.md). | 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` | major | false | Two active ledger rows with the same value and unit but different periods or qualifiers are cited as one fact. | Two ledger rows with different periods or qualifiers are cited as one fact; split the sentence or retire one row. |
 | `hedge_dropped` | major | false | A hedge, condition, or negation class present in the source quote is absent from the report sentence. | Restore the qualifier the source uses (estimated, about, not yet). |
 | `direction_flipped` | major | false | The source states an increase and the sentence a decrease, or the reverse. | The source states the opposite direction; rewrite from the quote. |
@@ -61,20 +62,22 @@ Raised only by the fidelity verifier (the fact ledger, fill, verify, meaning, an
 | `qualifier_dropped` | major | false | A bounding or approximation qualifier recorded on the ledger row (up to, at least, about) is absent near the value in the sentence. | The source bounds this value (up to, at least, about); restore the qualifier or use :q. |
 | `unbound_sentence` | major | false | A findings sentence carries no fact, quote, citation marker, or claim binding and is not marked as opinion or recommendation. | Bind the sentence to a fact, a quote, a citation, or a claim-graph node with data-claim. |
 | `meaning_drift_confirmed` | major | false | Two independent meaning readers flag the same drift kind on the same sentence and quote pair. | Two independent readers found the same drift; rewrite from the quote or dispute with a reason. |
+| `meaning_unverified` | major | false | `fact meaning-check` found a pair no reader judged, or a force_strong pair no strong reader judged; an empty drift list is not a clean check. | 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` | major | false | A proposed polish edit changes a protected number, hedge, qualifier, link, or claim id. | The edit changed a number, a hedge, a qualifier, a link, or a claim id; re-propose the language fix only. |
 | `polish_hedging_decreased` | major | false | The polish pass removed a hedge the source grounds. | The polish pass removed qualifiers; restore them. |
-| `polish_text_churn` | major | false | More than half of the visible prose changed during the polish pass. | More than half the text changed during polish; the pass composed instead of proofreading. |
+| `polish_text_churn` | major | false | More than half of the visible prose changed during the polish pass (`POLISH_CHURN_LIMIT` in `scripts/polish-rules.mjs`). | More than half the text changed during polish; the pass composed instead of proofreading. |
 | `snapshot_mismatch` | major | false | An operation that needs one collection window uses operands from unequal windows or observations outside the window. | The operands come from different collection windows; use rows from one window or state the windows separately. |
 | `join_integrity_fail` | major | false | A table row combines facts from different source observation rows, or a declared observation id contradicts the row's lineage. | A table row combines facts from different source observations; keep each row to one observation or split it. |
 | `quote_stale_version` | major | false | The quoted source revision differs from the revision the report targets for the same scope. | The quoted source revision differs from the revision the report targets; re-snapshot the target revision or date the quote. |
 | `quote_fuzzy_match` | minor | false | An exact quote match failed but a candidate with similarity of at least 0.95 and identical protected tokens exists (OCR noise); diagnostic only. | The source text is OCR-noisy; confirm the snapshot and prefer the raw document. |
 | `name_outside_quote` | minor | false | An uppercase Latin token of 2 to 6 letters in the sentence is absent from the supporting source text and that source's acronym table. | A name in the sentence is not in the cited quote; add the source or remove the name. |
+| `verification_claim_unmarked` | minor | false | A sentence reads as a first-person run ("we ran", "we have run", "I ran", "we executed", "we verified by", "by running" after we/our, or the Korean rule in fidelity-claim-kinds.md) and cites a fact not marked `verified` (or cites none and its block is unmarked). A warning only; it never blocks. | 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` | minor | false | The sentence uses a broader scope term than the quote's narrow term, and no supporting fact carries the broad scope. | The sentence uses a broader scope word than the quote; confirm the scope or narrow it. |
 | `particle_unverified` | minor | false | A particle after a filled value could not be checked against the value's final reading. | The particle after this value could not be checked; read it aloud and fix it by hand if wrong. |
 | `fallback_without_entity` | minor | false | A quote that replaced a twice-failed sentence has no entity for its attribution line. | The replacement quote has no entity for attribution; set one on the row. |
 | `meaning_drift_warn` | minor | false | One meaning reader flags a change of scope, subject, or certainty without independent agreement. | A separate reader found the sentence changes scope, subject, or certainty; rewrite from the quote. |
 | `polish_edit_unlocated` | minor | false | A polish edit's before-text matches zero or several places in the current text. | The edit's before-text was not found exactly once; re-propose against the current text. |
-| `polish_link_changed` | minor | false | The polish pass altered or removed a link target, or an internal target stopped resolving. | A link was altered or removed during polish; restore it. |
+| `polish_link_changed` | minor | false | The polish pass altered or removed an href link target, or an internal target stopped resolving. | A link was altered or removed during polish; restore it. |
 | `polish_name_changed` | minor | false | A ledger-backed proper noun present before polish is absent afterward. | A proper noun changed during polish; restore it. |
 
 ### Layout Gate (Rendering & Presentation)
@@ -101,6 +104,20 @@ Gates emit a manifest-level outcome with one of three statuses:
 
 The `layout` gate only runs when a probe file (a rendering artifact: PDF, PNG, or HTML snapshot) is provided alongside the manifest. If no probe file is available, the manifest records `layout: not_run` and the gate does not emit defects.
 
+## Polish Text-Node Contract
+
+Polish edits change text nodes only; markup changes go through the full fidelity gates, not polish.
+
+The primary rule is a whole-document skeleton comparison. Both gates scan the pre-polish and the polished document with the same tokenizer (`scripts/html-markup.mjs`) and require the skeleton to be byte-identical in document order: every tag token, comment, bogus comment, the frozen content of `script`, `style` and `template`, and every character reference of a text node (`&` up to the first `;` or non-name character). An accepted edit carries no `<`, `>` or `&` and may not touch a character reference, so an edited span holds no skeleton token and a legitimate polish never moves this sequence. Any difference names the first differing token and its byte offset: `polish-apply` refuses the edit, and `polish-diff` reports the blocker `polish_diff_fail` ("skeleton changed at token ..."). The character guards below are the early, actionable refusals; this comparison is what makes the guarantee complete, so a hand edit from `R&amp;D` to `R&lt;D` is blocked even though no edit was involved.
+
+An edit's `before` and `after` may not contain `<`, `>` or `&` at all. `polish-apply` refuses such an edit before any other check, as `polish_edit_rejected` with the reason `edit contains markup characters (<, >, &): route this section through the full fidelity gates`, so the refusal is visible, never a silent drop. The rule holds whatever the tokenizer models: an edit without these characters cannot create, alter, close or escape a tag, comment, bogus comment, CDATA section, entity or script. The characters alone are not enough, because a located region can start right after an existing `&` or inside a character reference: `polish-apply` also refuses, as `edit touches a character reference: route this section through the full fidelity gates`, any edit whose located region overlaps a character reference or opens one. Literal `&` and `<` in prose are entities in the source (`R&amp;D`, `p &lt; 0.05`) and stay usable only by leaving their bytes untouched: the proofread lane narrows an edit to the words around an entity or tag (`budget grew` to `budget rose`), never one that spans it. Wording that cannot be fixed without touching an entity or markup goes through the full fidelity gates.
+
+Before comparing, both gates refuse with `polish_diff_fail` ("ambiguous markup: ...") any document holding a construct the polish tokenizer does not model exactly: `</` followed by a non-letter (`</>` included), `<!--` inside a `script` or `style` element, `<![CDATA[`, `<?`, `--!>`, or `<` inside a tag or attribute value. Renderer output contains none of these. The tokenizer still follows the HTML spec for the bogus comment (`</` + non-letter, `<?`, `<!` up to the next `>`), the abrupt comment closes `<!-->` and `<!--->`, and the script-data escaped and double-escaped states.
+
+The shared rule in `scripts/polish-rules.mjs` runs per edit against the current and original report in `polish-apply`, and against the whole document in `polish-diff`. The sequence of opening and closing tags, every attribute name and value (including `href`, `id`, `class`, and `style`), comments, declarations, and all content of `script`, `style`, and `template` elements must be byte-identical. Attribute reordering, different quoting, tag case, whitespace inside a tag, and a self-closing slash are markup changes too. Any difference raises the blocker `polish_diff_fail`; apply rejects it with reason `markup changed`.
+
+Text nodes remain subject to the existing fact-span, number/unit, ticker, hedge, qualifier, name, and churn checks. Protected numbers, tickers, and required hedges cannot migrate between text nodes. A text edit inside an existing fact span is still a fact-span change, including under `aria-hidden`. Script/style/template content is frozen through the end of input when unclosed. No CSS or HTML visibility model is used by polish.
+
 ## Lineage and Citation Markers
 
 Defect codes and their hints are delivered via the outcome manifest under `residualDefects` (if repair did not exhaust). Each defect entry includes:

package/packages/shared-skills/skills/ulw-research/references/report-visualization.md

@@ -44,6 +44,8 @@ uv run --with numpy --with polars --with matplotlib python plot_<name>.py
 - Keep chart text as real text: set `matplotlib.rcParams["svg.fonttype"] = "none"` before saving an SVG. The default converts text to paths, and the static gate then sees a chart with no title, ticks, or labels.
 - Use the design spec's font family and palette tokens (`rcParams["font.family"]`, explicit colors from the spec). One accent color for the series that carries the finding; neutral tones for the rest.
 - Title, axis labels with units, value labels on bars or end points, ticks at round values computed from the data range.
+- Plot only from the fact ledger: export the rows with `node "$SKILL_DIR/scripts/report-tools.mjs" fact export --csv --out "$SESSION_DIR/assets/<chart>.csv" --session-dir "$SESSION_DIR"`, draw from that CSV, and give the chart figure `data-chart-source="assets/<chart>.csv"`.
+- Emit the axis tick labels inside one `<g class="ticks" data-tick-step=".." data-tick-min=".." data-tick-max="..">` group, so the fidelity gate can check every tick against the declared grid and every value label against the ledger.
 - One message per chart. A chart that needs a paragraph to explain is two charts.
 - For a web deliverable, HTML/CSS bars or an inline SVG built from the same table are preferred over an image.
 

package/packages/shared-skills/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/shared-skills/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/shared-skills/skills/ulw-research/scripts/claim-kinds.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, test } from "bun:test"
+import { spawnSync } from "node:child_process"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { CLAIM_ATTRIBUTE, CLAIM_KINDS, CLAIM_TABLE_BEGIN, CLAIM_TABLE_END, renderClaimKindTable, unmarkedKinds } from "./claim-kinds.mjs"
+import { DEFECT_CODES } from "./contracts.mjs"
+import { valueChecks } from "./fidelity-values.mjs"
+import { buildContext } from "./gates-static.mjs"
+import { parseHtml } from "./html-lite.mjs"
+
+// Protects the claim-kind contract the writer (fill) and the gate share: a fact marked with a
+// claim kind must cite a row that kind accepts, a mark binds only the facts it owns, and the doc
+// table writers read is rendered from CLAIM_KINDS. Expectations come from ORACLE below, written by
+// hand from the design, never from the table under test.
+
+type Defect = { code: string; severity: string }
+type Row = Record<string, unknown> & { fact_id: string; kind: string; source_id: string | null; raw?: string; quote?: string }
+
+const FIX = join(import.meta.dir, "tests", "fixtures", "fidelity")
+const BASE: { rows: Row[] } = JSON.parse(readFileSync(join(FIX, "ledger-verify.json"), "utf8"))
+const byId = (id: string) => BASE.rows.find((row) => row.fact_id === id) as Row
+const [F1, F7, F8, Q1] = ["F1", "F7", "F8", "Q1"].map(byId) as [Row, Row, Row, Row]
+const plain = { render: null, operation: null, operands: [], derived_from: [], formula: null, factor: null }
+const F9: Row = { ...F8, ...plain, fact_id: "F9", kind: "assumed", label: "growth_rate", raw: "15%", value: "15", unit: "%", exact: { num: "15", den: "1" }, rationale: "planning assumption" }
+const F10: Row = { ...F8, ...plain, fact_id: "F10", kind: "derived", label: "share_sum", raw: "39%", value: "39", unit: "%", exact: { num: "39", den: "1" }, operation: "sum", operands: ["F5", "F6"] }
+const F11: Row = { ...F7, fact_id: "F11", locator: null }
+const F12: Row = { ...F7, fact_id: "F12", locator: { artifact: "missing.txt", char_start: 0, char_end: 9 } }
+const F13: Row = { ...F7, fact_id: "F13", locator: { artifact: "../S4/text.txt", char_start: 0, char_end: 9 } }
+const LEDGER = { ...BASE, rows: [...BASE.rows, F9, F10, F11, F12, F13] }
+const SUBJECTS = [F1, F7, F8, F9, F10, F11, F12, F13, Q1]
+
+/** Hand-written oracle: the ledger row kinds each claim kind accepts, and whether the cited row must be command-backed. */
+const ORACLE: Record<string, { rows: string[]; command: boolean }> = {
+	fact: { rows: ["measured", "converted", "derived"], command: false },
+	quote: { rows: ["quote"], command: false },
+	verified: { rows: ["measured", "quote"], command: true },
+	derived: { rows: ["derived", "converted"], command: false },
+	assumed: { rows: ["assumed"], command: false },
+}
+/** Rows an unmarked element refuses (an unmarked numeral reads as a fact, so an assumption needs its A mark). */
+const UNMARKED_REFUSED = new Set(["F9"])
+/** Rows whose own locator artifact sits in a snapshot whose meta.json kind is command (S5/text.txt). */
+const COMMAND_BACKED = new Set(["F7"])
+const MAJOR_FOR: Record<string, string> = { fact: "claim_kind_mismatch", quote: "claim_kind_mismatch", verified: "unsupported_verification", derived: "claim_kind_mismatch", assumed: "claim_kind_mismatch" }
+const expected = (kind: string, row: Row) => {
+	const rule = ORACLE[kind] as { rows: string[]; command: boolean }
+	return rule.rows.includes(row.kind) && (!rule.command || COMMAND_BACKED.has(row.fact_id)) ? [] : [MAJOR_FOR[kind] as string]
+}
+
+const CLAIM_CODES = new Set(["claim_kind_mismatch", "unsupported_verification", "verification_claim_unmarked"])
+const run = (body: string) => valueChecks(buildContext(parseHtml(`<h2>Findings</h2>\n${body}`), { baseDir: FIX }), LEDGER, null, join(FIX, "sources"), {}) as Defect[]
+const claims = (body: string) => run(body).filter((d) => CLAIM_CODES.has(d.code))
+const codes = (body: string) => claims(body).map((d) => d.code).sort()
+
+const value = (row: Row, kind?: string) => {
+	const mark = kind ? ` ${CLAIM_ATTRIBUTE}="${kind}"` : ""
+	return row.kind === "quote" ? `<q data-fact="${row.fact_id}"${mark} data-quote-sel="full">${row.quote}</q>` : `<data class="fact"${mark} data-fact="${row.fact_id}">${row.raw}</data>`
+}
+const prose = (inner: string, lead = "The figure is") => `<p>${lead} ${inner} [S4].</p>`
+const cell = (inner: string) => `<table><tr><th>Item</th><td>${inner}</td></tr></table>`
+
+describe("every claim kind against the hand-written oracle", () => {
+	for (const kind of Object.keys(ORACLE)) {
+		for (const row of SUBJECTS) {
+			const want = expected(kind, row)
+			const label = want.length === 0 ? "no claim defect" : `${want[0]} major`
+			test(`#given ${kind} marked on ${row.fact_id} (${row.kind}) in prose and in a table cell #then ${label}`, () => {
+				for (const body of [prose(value(row, kind)), cell(value(row, kind))]) {
+					expect(codes(body)).toEqual(want)
+					for (const defect of claims(body)) expect(defect.severity).toBe("major")
+				}
+			})
+			test(`#given ${kind} marked on an enclosing element over ${row.fact_id} #then the parent's mark binds it: ${label}`, () => {
+				expect(codes(`<p><span ${CLAIM_ATTRIBUTE}="${kind}">The figure is ${value(row)}</span> [S4].</p>`)).toEqual(want)
+			})
+			test(`#given ${kind} marked on ${row.fact_id} beside an unmarked command row #then the neighbour never satisfies it: ${label}`, () => {
+				expect(codes(prose(`${value(row, kind)}, and the suite reported ${value(F7)}`))).toEqual(want)
+			})
+			for (const inner of Object.keys(ORACLE).filter((other) => other !== kind)) {
+				test(`#given ${inner} nested inside ${kind} over ${row.fact_id} #then mismatch, the parent owns nothing, and the inner kind is still checked`, () => {
+					const body = `<p><span ${CLAIM_ATTRIBUTE}="${kind}">The figure is ${value(row, inner)}</span> [S4].</p>`
+					expect(codes(body)).toEqual(["claim_kind_mismatch", MAJOR_FOR[kind] as string, ...expected(inner, row)].sort())
+				})
+			}
+		}
+	}
+
+	for (const row of SUBJECTS) {
+		const refused = UNMARKED_REFUSED.has(row.fact_id) ? ["claim_kind_mismatch:major"] : []
+		const refusedLabel = refused.length ? "claim_kind_mismatch major" : "no claim code"
+		test(`#given ${row.fact_id} unmarked in a first-person run sentence #then the minor verification_claim_unmarked, plus ${refusedLabel}`, () => {
+			const found = claims(prose(value(row), "We ran the check and it reported"))
+			expect(found.map((d) => `${d.code}:${d.severity}`).sort()).toEqual([...refused, "verification_claim_unmarked:minor"].sort())
+		})
+		test(`#given ${row.fact_id} unmarked in a plain sentence in prose and in a table cell #then ${refusedLabel}`, () => {
+			for (const body of [prose(value(row)), cell(value(row))]) expect(claims(body).map((d) => `${d.code}:${d.severity}`)).toEqual(refused)
+		})
+	}
+
+	test("#given an unknown claim kind #then claim_kind_mismatch", () => {
+		expect(codes(prose(value(F1, "rumoured")))).toEqual(["claim_kind_mismatch"])
+	})
+
+	test("#given every defect and warning code the table names #then contracts defines it, and warnings are never major", () => {
+		for (const entry of Object.values(CLAIM_KINDS) as { defect: string; unmarked: { code: string } | null }[]) {
+			expect(DEFECT_CODES[entry.defect]).toBeDefined()
+			if (entry.unmarked) expect(DEFECT_CODES[entry.unmarked.code].severity).toBe("minor")
+		}
+	})
+})
+
+describe("design-check regressions", () => {
+	test("#given verified wrapping a fact-marked page row (F1 shadowing) #then the parent is unsupported and the nesting is a mismatch", () => {
+		expect(codes(`<p><span ${CLAIM_ATTRIBUTE}="verified">The inspection put the span at ${value(F1, "fact")}</span> [S4].</p>`)).toEqual(["claim_kind_mismatch", "unsupported_verification"])
+	})
+
+	test("#given one verified value and an unmarked value in the same run sentence (F2) #then the unmarked one still warns", () => {
+		expect(codes(prose(`${value(F7, "verified")}, and the span is ${value(F1)}`, "We ran the suite and it reported"))).toEqual(["verification_claim_unmarked"])
+	})
+
+	test("#given a truthful converted and derived value marked fact (F3) #then no stricter than unmarked", () => {
+		for (const row of [F8, F9, F10]) expect(codes(prose(value(row, "fact")))).toEqual(codes(prose(value(row))))
+		expect(codes(prose(value(F8, "fact")))).toEqual([])
+	})
+
+	test("#given the assumed row F9 unmarked or marked fact #then both refuse it, and the unmarked message names the A mark", () => {
+		expect(codes(prose(value(F9)))).toEqual(["claim_kind_mismatch"])
+		expect(codes(prose(value(F9, "fact")))).toEqual(["claim_kind_mismatch"])
+		expect(JSON.stringify(claims(prose(value(F9))))).toContain("{{A:F9}}")
+	})
+
+	test("#given the assumed row F9 marked {{A:F9}} (data-claim-kind=assumed) #then no claim defect", () => {
+		expect(codes(prose(value(F9, "assumed")))).toEqual([])
+		expect(codes(cell(value(F9, "assumed")))).toEqual([])
+	})
+
+	test("#given verified citing a command-sourced row with no, a missing, or an escaping locator artifact (F4) #then unsupported_verification", () => {
+		for (const row of [F11, F12, F13]) expect(codes(prose(value(row, "verified")))).toEqual(["unsupported_verification"])
+	})
+})
+
+describe("unmarked phrases", () => {
+	const fires = [
+		"We verified the span by running the measurement script.",
+		"We ran the suite twice.",
+		"We executed the export.",
+		"We verified by hand-counting the rows.",
+		"We have run the tests.",
+		"I ran the suite.",
+		"Our numbers were obtained by running the script.",
+		"우리가 실행해 확인한 길이",
+		"저희가 스크립트를 실행하여 검증한 값",
+		"저희가 테스트를 돌렸다",
+		"우리 팀이 벤치마크를 돌려 얻은 값",
+		"그래서 우리는 스크립트를 실행했다",
+		"직접 실행한 결과",
+	]
+	const quiet = [
+		"The tests showed a 12 % drop.",
+		"The bridge, which ran across the river, spans 320 m.",
+		"The span, as confirmed with the annual inspection report, is 320 m.",
+		"Clinical tests confirmed the diagnosis.",
+		"The authors obtained estimates by running simulations.",
+		"We ran out of time.",
+		"확인된 길이는 최대 320 m",
+		"개발자가 직접 실행한 결과를 보고했다",
+		"실행해 확인한 길이",
+		"우리나라에서 실행된 정책은 320개다",
+		"우리 정부가 실행한 예산",
+		"우리가 의뢰한 업체가 테스트를 돌렸다",
+		"우리는 결과를 확인했다",
+	]
+	for (const text of fires) test(`#given "${text}" #then verified`, () => expect(unmarkedKinds(text)).toEqual(["verified"]))
+	for (const text of quiet) test(`#given "${text}" #then nothing`, () => expect(unmarkedKinds(text)).toEqual([]))
+})
+
+describe("references/fidelity-claim-kinds.md is rendered from CLAIM_KINDS", () => {
+	const doc = readFileSync(join(import.meta.dir, "..", "references", "fidelity-claim-kinds.md"), "utf8")
+
+	test("the committed table section equals renderClaimKindTable() byte for byte", () => {
+		const [begin, end] = [doc.indexOf(CLAIM_TABLE_BEGIN), doc.indexOf(CLAIM_TABLE_END)]
+		expect(begin).toBeGreaterThanOrEqual(0)
+		expect(end).toBeGreaterThan(begin)
+		expect(doc.slice(begin + CLAIM_TABLE_BEGIN.length + 1, end)).toBe(renderClaimKindTable())
+	})
+
+	test("node claim-kinds.mjs --render-doc prints the same table", () => {
+		const result = spawnSync("node", [join(import.meta.dir, "claim-kinds.mjs"), "--render-doc"], { encoding: "utf8" })
+		expect(result.status).toBe(0)
+		expect(result.stdout).toBe(renderClaimKindTable())
+	})
+})

package/packages/shared-skills/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. */