lazycodex-ai 5.1.44 → 5.1.46

package/packages/shared-skills/skills/ulw-research/references/fact-ledger.md

@@ -0,0 +1,95 @@
+# Fact ledger
+
+`$SESSION_DIR/fact-ledger.json` holds every number and every direct quotation a research run may put in front of a reader. Rows come only from a source snapshot (through a deterministic locator), from a script-computed derivation, or from an explicit assumption with a rationale. A report source never carries a typed value: it carries a placeholder, and `fact fill` renders the row. The validity rules (ids, per-kind columns, the status machine) are in [fact-ledger-grammar.md](fact-ledger-grammar.md); this file is the working guide.
+
+Every command is `node "$SKILL_DIR/scripts/report-tools.mjs" <command> --session-dir "$SESSION_DIR"`; the flags and exit codes are in [deliverable-phase.md](deliverable-phase.md), sections 10 and 11.
+
+## Files
+
+| Path | Written by | Holds |
+| --- | --- | --- |
+| `sources/S<n>/text.txt` | `source snapshot` | the extracted text the locators read (one line per block; pages joined by a form feed); `sha256` covers this file |
+| `sources/S<n>/source.html` | `source snapshot` (page sources) | the captured page, read by the table locator |
+| `sources/S<n>/meta.json` | `source snapshot` | `source_id`, `url`, `observed_at`, `sha256`, `extractor`, `revision`, `kind`, `provenance` |
+| `sources/S<n>/sentences.jsonl`, `acronyms.json` | `source snapshot` | the sentence index (`S<n>:s<k>`) and the acronym table the fidelity gate reads |
+| `sources/S<n>/command.json` | `source snapshot --command` | argv, working directory, exit status, stdout and stderr hashes |
+| `fact-ledger.json` | `fact add`, `fact quote`, `fact derive`, `fact retract` | `{ schemaVersion: 1, rows, events }` |
+| `claims.json` | `claims index` | the claim table and the `verified-claims` membership |
+| `fidelity-defects.json` | `fact verify` | the verify record: the fidelity envelope (`record_kind: "fidelity"`, `artifact_sha256`, `report`, `written_at`, `defects`) plus `command`, `status`, `exitCode`, `format`, `counts`, `gatesRun` |
+| `fidelity-meaning-defects.json` | `fact meaning-check` | the meaning record: the fidelity envelope (`record_kind: "meaning"`) plus the run fields under Meaning verdicts |
+
+A source directory is immutable. Snapshotting the same id again with the same text is a no-op; different text fails with `snapshot_exists`, because rows pin the snapshot hash.
+
+## Row fields
+
+| Field | Meaning |
+| --- | --- |
+| `fact_id` | `F<n>` for a value, `Q<n>` for a quotation; assigned by the writer |
+| `kind` | `measured` (located in a snapshot), `quote`, `derived`, `converted`, or `assumed` |
+| `label` | the name a placeholder must repeat exactly (`[a-z0-9_-]`, up to 32 characters) |
+| `value`, `unit`, `exact` | the decimal value as written, its normalized unit, and the exact rational the arithmetic uses |
+| `raw`, `quote`, `value_span` | the source's own characters for the value, the whole containing sentence or cell, and where `raw` sits inside `quote` |
+| `qualifier` | a bounding word the source puts on the value: `upper_inclusive` (up to, at most), `lower_inclusive` (at least), `approximate` (about), `near` (nearly), `lower_exclusive` (over, more than), `upper_exclusive` (under, less than) |
+| `source_id`, `snapshot_sha256`, `sentence_id` | the snapshot the row was read from, its hash at that moment, and the sentence id |
+| `locator` | where `quote` sits in `text.txt` (`artifact`, `line`, `page`, `char_start`, `char_end`, and `table`, `row_label`, `col_label` for a table cell), plus the source's `source_kind`, `url`, `host`, and `pointed` (whether the brief's source floor names it) |
+| `extracted_by` | the snapshot's extractor: `tool:source-snapshot@1` (fetched or executed by the script), `model` (a capture the browser lane imported; lower trust), or `extractor:<name>@<version>`; `fact-derive` for a derivation |
+| `observed_at`, `valid_at` | when the row was registered, and the period the value describes (`--valid-at`) |
+| `entity`, `population`, `accounting_basis`, `observation_id` | declarations the derivations check (`--entity`, `--population`, `--accounting-basis`, `--observation O<n>`) |
+| `operation`, `operands`, `derived_from`, `formula`, `factor`, `render` | for a derived or converted row: what was computed from which rows, and the rendered text |
+| `rationale` | why an assumed value was chosen (required for `assumed`), or why an `expr` derivation is sound |
+| `status` | `active`, `retracted`, or `superseded`; rows are never deleted, and each change appends an event |
+
+## Locators
+
+| Flags | Resolves |
+| --- | --- |
+| `--find "<anchor>"` | one normalized anchor occurrence, then the first numeral starting within 80 characters after it, in the same sentence; `--unit-expected` checks the unit |
+| `--table <id or caption> --row <label> --col <label>` | the cell by header labels, never by index; duplicate labels fail |
+| `--page N --line N` | exactly one numeral on that line of an extracted document |
+| `--match "<words>"` (`fact quote`) | the unique sentence containing the words; the whole sentence is stored, so a later partial quote cannot drop its hedge |
+
+A locator that finds nothing returns `fact_not_located`, more than one candidate `fact_ambiguous`, and nothing is written. Read the printed row and its 60 characters of context on each side before using it; a wrong row is retracted, never edited.
+
+## Meaning verdicts
+
+`ingestVerdicts(pairs, verdictFiles, options)` (`scripts/meaning-check.mjs`) folds the meaning readers' verdict files over the pairs of `extractPairs` and returns four lists:
+
+| Field | Holds |
+| --- | --- |
+| `defects` | one `meaning_drift_confirmed` (both tiers named the same kind, never `other`) or `meaning_drift_warn` (one tier) per flagged pair, in pair order; the fragment comes from the verdict whose kind is reported |
+| `dropped` | every verdict that was not accepted, with its file, pair, tier, and reason (unknown pair, invalid tier or verdict, unknown or empty drift kind, a fragment missing from the sentence or the source) |
+| `unverified` | every pair no reader judged (`no_verdict`) and every `force_strong` pair no strong reader judged (`no_strong_verdict`), in pair order; a dropped verdict does not count as read |
+| `calibrationLines` | one JSON line per flagged pair, appended to `fidelity-calibration.jsonl` when `calibrationPath` is given |
+
+Coverage is fail-closed. A consumer treats a non-empty `unverified` list as blocking: those pairs were never read, so an empty `defects` list does not mean the report is clean. An unreadable verdict path or invalid JSON raises a `TypeError` naming the file, which the CLI maps to exit code 2.
+
+`fact meaning-check` writes these lists into `fidelity-meaning-defects.json` through the one fidelity record writer (`writeFidelityRecord` in `scripts/fidelity-records.mjs`). The record is the envelope every fidelity record carries, `record_kind` (`meaning`), `artifact_sha256` and `report` (copied from `pairs.json`, so the record names the edition the readers judged), `written_at`, and `defects` (the folded defects plus one `meaning_unverified` per unread pair), followed by the run fields `command`, `status`, `exitCode`, `run_id`, `pairs_sha256`, `counts`, `dropped`, `unverified`, `calibration_path`, `calibration_written`, `calibration_replaced`, and `promotion_eligibility`. Any other field makes the record malformed. A pairs file without `artifact_sha256` and `report` exits 2 before anything is written. The delivery barrier refuses the record when no delivered edition's source bytes hash to its `artifact_sha256`, so a rewrite needs a fresh `fact pairs` and reader run.
+
+## Operations
+
+- `fact add --source S<n> <locator> --label <label>` registers a measured row; `fact add --assumed <value> --unit <unit> --rationale <why> --label <label>` registers an assumption.
+- `fact quote --source S<n> --match "<words>" --label <label>` registers a quotation.
+- `fact derive --op <sum|diff|growth|ratio|share|convert|expr> ...` computes a new row from active rows and prints its id; the placeholder uses that id. Operands go by position for sum, diff, and convert (`--to <unit>`), as `--from/--to`, `--part/--whole`, or `--num/--den` for growth, share, and ratio, and as one formula argument for expr. Every op except convert declares its result unit with `--unit <unit>` (`--unit null` for dimensionless); a `%` sum also needs `--disjoint --reference <denominator> --rationale <why>`. The unit rules are in `unit-rules.md`.
+- `fact retract <id> --reason <why>` retires a row; `--replacement <id>` marks it superseded by another active row. Rows that depend on a retired row fail at fill time.
+- `fact export --csv --out <file>` writes `fact_id,label,plot_value,unit` for every active value row: the only data a chart may plot.
+- `fact fill <src> --out <file>` renders every placeholder from the ledger; `fact verify <file>` checks the filled edition against the ledger, the snapshots, and the claim index; `outcome set <format> delivered` records intent permissively, while the required `outcome verify` and `outcome finish` enforce the delivery barrier.
+- `fact pairs <file>` writes `pairs.json` for the meaning readers; `fact meaning-check --pairs pairs.json --verdicts <file> ...` ingests their verdicts.
+
+## Meaning command
+
+`pairs.json` is `{ schemaVersion, skipped, report, format, artifact_sha256, pairs_sha256, counts, verdict_schema, pairs }`. `verdict_schema` is the machine-read verdict contract (the allowed `model_tier`, `verdict`, and `drift_kind` values and the required fields), built from the registries in `meaning-check.mjs`; hand it to the reader with the pairs. Each pair has `pair_id` (`P<n>` in document order), `kind` (`quote`, `claim`, or `translation`), `sentence_key`, `sentence`, `source_lang`, `report_lang`, `force_strong`, and either `fact_ids` with `quote` or `claim_id` with `statement`.
+
+A reader writes one verdict file per tier: `{ "model_tier": "cheap" | "strong", "verdicts": [...] }` (a bare array works when each verdict names its own `model_tier`). One verdict per pair:
+
+| Field | Value |
+| --- | --- |
+| `pair_id` | a `pair_id` from `pairs.json`; any other id is dropped (`unknown_pair`) |
+| `verdict` | `ok` or `drift` |
+| `drift_kind` | for `drift`, exactly one of `subject_changed`, `scope_widened`, `hedge_dropped`, `certainty_added`, `causality_added`, `direction_flipped`, `population_changed`, `evidence_grade_raised`, `other` |
+| `fragment` | for `drift`, a non-empty verbatim substring of the pair's `sentence` (whitespace-normalized) |
+| `source_fragment` | for `drift`, a non-empty verbatim substring of the pair's `quote` or `statement` |
+| `explanation` | one sentence, for the briefing; never read by the scripts |
+
+A verdict that breaks any rule is dropped and listed in the record's `dropped` with its reason; it never becomes a defect. Both tiers naming the same `drift_kind` other than `other` on one pair is `meaning_drift_confirmed` (major); one tier, or two tiers that disagree, is `meaning_drift_warn` (minor). `--dispute P<n> --reason` keeps the defect and marks its calibration line `disputed`; the command still exits `1`, and the way forward is the repair loop described in deliverable-phase.md ("After a dispute"). A `{"skipped": true}` pairs file is accepted only when the locked brief says `meaning check: off`; with the check on (`meaning_check_required`) or no locked block (`fidelity_interview_incomplete`) it exits `1`. Every entry of `unverified` becomes one `meaning_unverified` defect (major), so a pair no reader judged fails the command (exit 1) through the same registry policy as any other defect. A malformed `pairs.json` or an unreadable verdict file exits 2.
+
+`fidelity-calibration.jsonl` starts with a header line `{ "header": true, "promotion": ... }` holding the promotion criterion, then per run one run line `{ "run": true, run_id, pairs_sha256, flagged }` (written even when nothing was flagged, so `min_runs` counts real runs) and one line per flagged pair: `kind`, `pair_id`, `tiers`, `drift_kind`, `confirmed`, `disputed`, `reason`, `run_id`, `pairs_sha256`. The run id (`--run-id`, or a hash of the pairs and verdict files only, never the dispute) keys the run: rerunning the same inputs, with or without `--dispute`, replaces that run's lines in place, and a dispute recorded earlier carries forward to the rewritten lines. A corrupt log line exits `2` naming `<path>:<line>`. The record's `promotion_eligibility` evaluates the criterion over the log, counting report-level false blocks over the last `false_block_window` runs.

package/packages/shared-skills/skills/ulw-research/references/fidelity-claim-kinds.md

@@ -0,0 +1,19 @@
+# Fidelity Claim Kinds
+
+A report sentence states a plain fact or quote by default. When it claims more than that (that we ran or checked something, that a number is derived, that it is an assumption), the writer marks the claim kind in the placeholder, fill renders the mark as the `data-claim-kind` attribute on the element it writes, and the fidelity gate checks that every marked fact cites a ledger row the kind accepts. The gate never infers a claim kind from wording: an unmarked sentence is checked as a plain fact or quote (so an unmarked `assumed` row is a `claim_kind_mismatch`: an unmarked assumption reads as a fact and needs its `{{A:F12:label}}` mark), and only the unmarked-warning rule raises a warning (severity minor, never blocking) when a sentence reads like the kind and cites a fact not marked with it.
+
+A mark binds per cited fact. Each `data-fact` element takes the kind of its nearest mark (its own attribute, else the closest marked ancestor), and only that kind is checked against its row; a parent mark applies to the facts it binds, never to the sentence as a whole. A fact under marks of two different kinds is a `claim_kind_mismatch`, and a mark that binds no fact of its own (all of them are shadowed by another kind, or it cites none) is its kind's defect: shadowing never satisfies a parent.
+
+A `verified` claim is satisfied only when the cited row itself has a locator artifact inside `sources/<source_id>/` whose snapshot `meta.json` has `kind: "command"` (recorded command or test output); a different command row elsewhere in the sentence never satisfies it. Korean phrases are shown as `\u` escapes, exactly as `claim-kinds.mjs` stores them. The defect codes are in [report-gates.md](report-gates.md).
+
+<!-- claim-kinds:begin (rendered from CLAIM_KINDS; do not edit by hand) -->
+| Kind | Placeholder | Attribute fill emits | Accepted row kinds | Required source kind | Defect when unsatisfied | Unmarked warning | Notes |
+|---|---|---|---|---|---|---|---|
+| `fact` | `{{F12:label}}` | none (or `data-claim-kind="fact"`) | `measured`, `converted`, `derived` | any | `claim_kind_mismatch` | none | 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). |
+| `quote` | `{{Q7:label}}` | none (or `data-claim-kind="quote"`) | `quote` | any | `claim_kind_mismatch` | none | - |
+| `verified` | `{{V:F12:label}}` | `data-claim-kind="verified"` | `measured`, `quote` | `command` | `unsupported_verification` | `verification_claim_unmarked` on 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 | 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. |
+| `derived` | `{{D:F12:label}}` | `data-claim-kind="derived"` | `derived`, `converted` | any | `claim_kind_mismatch` | none | - |
+| `assumed` | `{{A:F12:label}}` | `data-claim-kind="assumed"` | `assumed` | any | `claim_kind_mismatch` | none | Numeric assumptions only (an assumed ledger row carries a decimal value); a qualitative assumption stays prose. |
+<!-- claim-kinds:end -->
+
+Regenerate the table with `node scripts/claim-kinds.mjs --render-doc`.

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

@@ -1,6 +1,6 @@
 # Report-Gates Defect Glossary
 
-This reference catalogs every defect code the report gates (`static`, `layout`, `visual`, `proofread`) can raise, their severity and impact, and how to repair them.
+This reference catalogs every defect code the report gates (`static`, `fidelity`, `layout`, `visual`, `proofread`) can raise, their severity and impact, and how to repair them.
 
 ## Defect Codes by Category
 
@@ -29,6 +29,57 @@ This reference catalogs every defect code the report gates (`static`, `layout`,
 | `missing_required_section` | blocker | true | A section explicitly required by the brief (e.g., via `--require-section`) is absent. | Add the section the brief requires (matched by --require-section). |
 | `missing_promised_deliverable` | blocker | true | A deliverable (e.g., a slide deck, a chart, a data file) is promised in the brief but not delivered, not marked blocked_capability, and not skipped with a reason. | Produce the promised deliverable or record it as blocked_capability or skipped with a reason. |
 
+### Fidelity Gate (Facts, Quotes & Meaning)
+
+Raised only by the fidelity verifier (the fact ledger, fill, verify, meaning, and polish steps), never by `check`. Until that verifier ships in an edition, the manifest records `fidelity: not_run`.
+
+| Code | Severity | Integrity | What It Detects | How to Fix |
+|------|----------|-----------|-----------------|-----------|
+| `unresolved_placeholder` | blocker | true | A fact or quote placeholder is left in the artifact, names an unknown ledger id, is malformed, or uses an unsupported mode. | Register the fact with fact add or remove the sentence; a placeholder is never filled with a guess. |
+| `value_mismatch` | blocker | true | A displayed value differs from its ledger row's rendering, or a stored derived value differs from exact recomputation (a hand edit after fill). | Re-run fact fill; never edit a filled value by hand. |
+| `unit_mismatch` | blocker | true | A displayed, adjacent, or header unit conflicts with the ledger row's unit or scale. | Re-run fact fill, or derive a converted row with fact derive --op convert. |
+| `quote_not_verbatim` | blocker | true | A quotation bound to a quote row does not match the source snapshot contiguously after normalization, or a rendered cut is not the registered cut. | Re-insert the quote through its {{Q<n>}} placeholder; after a second failure the sentence is replaced by the quote. |
+| `claim_status_invalid` | blocker | true | A sentence's claim binding names an unknown claim, a refuted or unresolved claim outside Gaps and Contradictions, or a high-risk claim absent from the verified claims. | The claim id is unknown, refuted, unresolved, or not in verified-claims; move the sentence to Gaps or Contradictions, or remove it. |
+| `incompatible_operands` | blocker | true | A derivation's operands differ in unit, population, period, or accounting basis where the operation requires them to match; derive refuses and writes no row. | The operands differ in unit, population, period, or basis for this operation; fix the rows or declare the operation that fits. |
+| `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 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. |
+| `snapshot_hash_mismatch` | blocker | true | A pinned source snapshot's text no longer hashes to its recorded hash, or indexed slices no longer equal the snapshot text. | The source snapshot changed after it was pinned; re-snapshot the source and re-register its rows. |
+| `chart_value_untraceable` | blocker | true | A chart data label, axis tick, or chart data file does not match the ledger-backed data the chart declares, or the chart declares no data source. | 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` | 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 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. |
+| `causality_added` | major | false | The sentence carries a causal connective that no supporting quote or claim statement contains. | The source states no cause; state the correlation or quote the source. |
+| `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 (`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 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)
 
 | Code | Severity | Integrity | What It Detects | How to Fix |
@@ -46,13 +97,27 @@ Gates emit a manifest-level outcome with one of three statuses:
 | Status | Meaning |
 |--------|---------|
 | `pass` | All checks passed; no defects raised. |
-| `fail` | One or more defects raised (blocker, major, or minor severity). Repair is required before delivery. |
+| `fail` | At least one blocker defect was raised. Major and minor defects alone leave the gate at `pass`; they still go to the repair loop. |
 | `not_run` | The gate was not invoked (e.g., no probe file provided for layout, no visual inspection conducted). |
 
 ### Layout Gate Probe File Requirement
 
 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:
@@ -62,7 +127,7 @@ Defect codes and their hints are delivered via the outcome manifest under `resid
 
 Citations within reports follow one of two lineage modes:
 
-- **inline**: Source marks appear as `[Sn]` or `[Rn]` hyperlinks inline with the cited text.
+- **inline**: Source marks appear as `[Sn]`, `[Source n]`, or `[^n]` hyperlinks inline with the cited text.
 - **section**: Sources are listed in a dedicated section with numbered entries ([S1], [S2], etc.).
 
 Both modes are valid; choose based on the report's narrative flow.

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
+	}
+}