lazycodex-ai 5.1.43 → 5.1.45

package/packages/shared-skills/skills/ulw-research/SKILL.md

@@ -346,12 +346,12 @@ Assembly worker — `task(category="deep-low", load_skills=["frontend", "visual-
 
 ### The delivery gates — every gate for the QA tier must PASS, in order
 
-Nothing reaches the user until the gates pass. Record each result with `node "$SKILL_DIR/scripts/report-tools.mjs" outcome gate <static|layout|visual|proofread> <pass|fail|not_run> --session-dir "$SESSION_DIR"`; a gate this harness does not provide is recorded `not_run`. A chat or post answer (light tier) runs the static gates and one render; every paginated or web deliverable runs them all (the reference's sections 3 and 7).
+Nothing reaches the user until the gates pass. Record each result with `node "$SKILL_DIR/scripts/report-tools.mjs" outcome gate <static|fidelity|layout|visual|proofread> <pass|fail|not_run> --session-dir "$SESSION_DIR"`; `fidelity` is recorded not_run until the fidelity verifier ships in this edition; a gate this harness does not provide is recorded `not_run`. A chat or post answer (light tier) runs the static gates and one render; every paginated or web deliverable runs them all (the reference's sections 3 and 7).
 
 1. **Static gates (always, before anyone looks at pixels).** `node "$SKILL_DIR/scripts/report-tools.mjs" check "$SESSION_DIR/report.html" --design-spec "$SESSION_DIR/design-spec.md" > "$SESSION_DIR/defects.json"`: keep-all, palette tokens, emoji, em dashes, heading length, unsourced numbers, figure containers, chart text, a report with no visual, images without alt text, gothic-only fonts, citations, the closing and sources sections, broken assets. Codes and fixes: [references/report-gates.md](references/report-gates.md).
 2. **Layout gates.** Print the probe with `node "$SKILL_DIR/scripts/report-tools.mjs" layout-probe --json`, evaluate its `source` in the rendered page through the `browser` skill's owned headless engine, save the result as `$SESSION_DIR/boxes.json`, and re-run `check` with `--layout "$SESSION_DIR/boxes.json"` (overflow, clipped text, distorted images, overlapping siblings).
 3. **Visual QA.** Render the produced artifact back to images — PDF pages to PNG, the HTML through the browser skill at desktop and phone widths — and look at them: missing or broken figures, images stretched or spilling their containers, diagram or chart text rendered off the spec's font or palette, clipped tables, overflowing CJK text, blank pages, unlabeled chart values, wrong page breaks. Reading the source markup is not visual QA; inspect the pixels.
-4. **Proofread gate — `task(category="writing", ...)`.** Hand the final text to a dedicated `writing` worker whose only job is language: grammar, spelling, punctuation, terminology consistency, and whether the prose reads NATIVELY in the report's own language. It proofreads only and never composes. It returns a defect list; fix every item and re-run the gate on the delta. Deliver only on a clean pass — this gate runs BEFORE the first delivery, not after the user finds the typo.
+4. **Proofread gate: `task(category="writing", ...)`.** Hand the final text to a dedicated `writing` worker whose only job is language: grammar, spelling, punctuation, terminology consistency, and whether the prose reads NATIVELY in the report's own language. It proofreads only and never composes. It returns a defect list; fix every item and re-run the gate on the delta. Deliver only on a clean pass. This gate runs BEFORE the first delivery, not after the user finds the typo.
 
 **Repair is bounded.** After every gate run that found defects, ask `node "$SKILL_DIR/scripts/report-tools.mjs" repair decide --state "$SESSION_DIR/repair-state.json" --defects "$SESSION_DIR/defects.json" --artifact-bytes <bytes> --renders <pages> --session-dir "$SESSION_DIR"` and obey it: `repair` means fix and re-run; `deliver` means stop and ship with the residual defects the manifest now lists; `block` means a content-integrity defect remains (or there is no usable artifact), so do not deliver: tell the user what blocks it and record the row as `failed` with the reason. Never repair past a stop decision (3 attempts, a 2-attempt plateau, an oscillation, or 15 minutes; the reference's section 8).
 

package/packages/shared-skills/skills/ulw-research/references/deliverable-phase.md

@@ -50,7 +50,7 @@ The request and its destination usually answer the format question already. Deri
 | A prior report of the same kind in this workspace, not pointed at | that report's format, offered as the Q1 default | `template-vibe` | full |
 | A complete existing deliverable for this question (section 2) | its existing format | `edit-existing` | the original's tier |
 
-QA tiers: **light** runs the static gates and one render check of the answer. **Full** runs the static gates, the layout gates, visual QA of every page, and the proofread gate (section 7).
+QA tiers: **light** runs the static gates and one render check of the answer, and records the fidelity gate as `not_run` until Markdown deliverable support ships for it. **Full** runs the static gates, the fidelity gate, the layout gates, visual QA of every page, and the proofread gate (section 7).
 
 ## 4. The empty-info interview
 
@@ -123,14 +123,15 @@ Nothing reaches the requester until the gates for its QA tier pass, in this orde
    node "$SKILL_DIR/scripts/report-tools.mjs" check "$SESSION_DIR/report.html" --design-spec "$SESSION_DIR/design-spec.md" > "$SESSION_DIR/defects.json"
    ```
    It checks keep-all, palette tokens, emoji, em dashes in prose (en dashes outside numeric ranges are advisory), heading length and generic headings, unsourced numbers (section 6), figure containers and captions, chart SVG text, a report with no visual at all, images without alt text, Korean serif fonts, sections without citations, the closing section, the sources section, broken local assets, and any `--require-section <regex>` the brief requires. Every code, severity, and fix is in [report-gates.md](report-gates.md).
-2. **Layout gates.** Print the probe, evaluate it in the rendered page through the browser skill's owned headless engine, save the returned object as `$SESSION_DIR/boxes.json`, and re-run `check` with `--layout "$SESSION_DIR/boxes.json"`. It adds overflow past the container, clipped text, scroll containers, distorted images, and overlapping siblings.
+2. **Fidelity gate.** The fidelity verifier checks every number, quote, and claim binding against the fact ledger and the source snapshots; its codes are the Fidelity Gate table in [report-gates.md](report-gates.md). It runs before layout and visual QA because a content failure would otherwise force an expensive re-render. Until the fidelity verifier ships in this edition, record `outcome gate fidelity not_run`.
+3. **Layout gates.** Print the probe, evaluate it in the rendered page through the browser skill's owned headless engine, save the returned object as `$SESSION_DIR/boxes.json`, and re-run `check` with `--layout "$SESSION_DIR/boxes.json"`. It adds overflow past the container, clipped text, scroll containers, distorted images, and overlapping siblings.
    ```bash
    node "$SKILL_DIR/scripts/report-tools.mjs" layout-probe --json   # .source is one async expression
    ```
-3. **Visual QA.** Render the artifact to images (PDF pages to PNG, the HTML in the browser skill's engine at desktop and phone widths) and look at the pixels for what a machine cannot see: composition, hierarchy, page breaks, figure legibility.
-4. **Proofread.** A dedicated writing lane proofreads the final text only (grammar, spelling, punctuation, terminology, native register); it never composes or rewrites content.
+4. **Visual QA.** Render the artifact to images (PDF pages to PNG, the HTML in the browser skill's engine at desktop and phone widths) and look at the pixels for what a machine cannot see: composition, hierarchy, page breaks, figure legibility.
+5. **Proofread.** A dedicated writing lane proofreads the final text only (grammar, spelling, punctuation, terminology, native register); it never composes or rewrites content.
 
-The light tier runs gate 1 and one render (recorded as `visual`) and records `layout` and `proofread` as `not_run`. The full tier runs all four.
+The light tier runs gate 1 and one render (recorded as `visual`) and records `fidelity`, `layout`, and `proofread` as `not_run`; `fidelity` stays `not_run` in the light tier until Markdown deliverable support ships for the fidelity verifier. The full tier runs all five.
 
 ## 8. Bounded repair loop
 
@@ -142,7 +143,7 @@ node "$SKILL_DIR/scripts/report-tools.mjs" repair decide --state "$SESSION_DIR/r
 
 - `action: repair`: fix the listed defects, re-render, re-run the gate, and ask again.
 - `action: deliver`: stop repairing and deliver. `reason` is `clean` or the stop condition that fired; the residual defects are written into the manifest and listed in the closing briefing.
-- `action: block` (exit `1`): do not deliver. Either a content-integrity defect remains (`missing_closing_section`, `missing_citation_section`, `broken_asset_reference`, `missing_required_section`, `missing_promised_deliverable`), or a stop fired without proof of a usable artifact (`--artifact-bytes` and `--renders`). Tell the requester what blocks delivery and record the affected rows as `failed` with the reason.
+- `action: block` (exit `1`): do not deliver. Either a content-integrity defect remains (`missing_closing_section`, `missing_citation_section`, `broken_asset_reference`, `missing_required_section`, `missing_promised_deliverable`, or a fidelity integrity code: `unresolved_placeholder`, `value_mismatch`, `unit_mismatch`, `quote_not_verbatim`, `claim_status_invalid`, `incompatible_operands`, `pointer_label_mismatch`, `quote_anchor_unresolved`, `unit_duplicated`, `polish_diff_fail`, `fidelity_interview_incomplete`, `derived_not_allowed`, `source_outside_floor`, `snapshot_hash_mismatch`, `chart_value_untraceable`, `quote_unbound`, `edition_unverified`), or a stop fired without proof of a usable artifact (`--artifact-bytes` and `--renders`). Tell the requester what blocks delivery and record the affected rows as `failed` with the reason.
 
 Defaults: 3 repair attempts, a plateau of 2 consecutive attempts that do not improve the (blocker, major, minor) counts compared in that order, and 15 minutes of wall clock from the first decision. A defect set that repeats an earlier attempt exactly stops the loop as an oscillation. When several conditions hold at once the reported reason follows `clean`, `blocking`, `oscillation`, `plateau`, `max_attempts`, `wall_clock`.
 

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

@@ -0,0 +1,116 @@
+# Fact ledger grammar
+
+`fact-ledger.json` is the single source of numbers and quotes for a research run. This file is
+the one definition of what a valid ledger is. `scripts/fact-ledger-schema.mjs` encodes it as
+data (`TRANSITIONS`, `transitionError`, `provenanceErrors`), and both the validator
+(`validateLedger`) and every writer (`addRow`, `retractRow`, `supersedeRow`, `writeLedger`)
+call that same code. A writer can therefore never produce a ledger the validator rejects, and
+the validator can never accept a ledger no writer could produce.
+
+## Ledger
+
+```
+ledger := { schemaVersion: 1, rows: row[], events: event[] }
+```
+
+`rows` is append-only: a row is never deleted or reordered. `events` is append-only and
+ordered; an event's position is its time.
+
+## Ids
+
+```
+fact_id   := "F" digits      for kind in measured | derived | assumed | converted
+           | "Q" digits      for kind = quote
+source_id := "S" digits
+```
+
+`nextId` returns the prefix plus one more than the largest number already used for that
+prefix. `C<n>` is reserved for claim-graph nodes and never appears in the ledger. Fact ids are
+unique across all rows.
+
+## Rows
+
+Every row carries every field of `ROW_FIELDS`; unknown fields are rejected.
+
+The per-kind table below is rendered from `KIND_RULES` in `scripts/fact-ledger-kinds.mjs`
+(`node scripts/fact-ledger-kinds.mjs --render-grammar`); the validator checks every per-kind
+column through that same table, and a test keeps this copy equal to the rendered output.
+
+Always required, never null: `fact_id`, `kind`, `raw` (string), `quote` (string),
+`extracted_by` (non-empty), `observed_at` (ISO timestamp), `label` (`[a-z0-9_-]{1,32}`),
+`status`.
+
+<!-- kind-rules:begin (rendered from KIND_RULES; do not edit by hand) -->
+| field | measured | quote | derived | assumed | converted |
+|---|---|---|---|---|---|
+| `fact_id` | `F<n>` | `Q<n>` | `F<n>` | `F<n>` | `F<n>` |
+| `value` | decimal | null | decimal | decimal | decimal |
+| `source_id` | `S<n>` | `S<n>` | `S<n>` or null | `S<n>` or null | `S<n>` or null |
+| `locator` | object | object | object or null | object or null | object or null |
+| `snapshot_sha256` | sha256 | sha256 | sha256 or null | sha256 or null | sha256 or null |
+| `rationale` | string or null | string or null | string or null | non-empty | string or null |
+| `exact` | from `value` | null | written by derive (rational or null) | rational or null | written by derive (rational or null) |
+<!-- kind-rules:end -->
+
+- `exact` is `{ num: integer string, den: positive integer string }` or null. A measured row's
+  `exact` must equal the reduced rational of its `value` (`exactFromDecimal`); `addRow` fills
+  it when the caller leaves it null. Derived and converted rows get it from
+  derive (plan todo 9): a converted value's rational comes from the original and the factor,
+  not from the rounded `value`, so `addRow` never computes it from `value`.
+- `locator` is `{ artifact, char_start <= char_end, page?, line?, table?, row_label?,
+  col_label? }`.
+- All other fields are nullable with the types in `fact-ledger-schema.mjs`.
+
+## Labels
+
+A label is unique across ALL rows, whatever their status. Retracting or superseding a row does
+not free its label.
+
+## Provenance
+
+`operands` and `derived_from` are arrays of fact ids. Every id must name an existing row and
+must not be the row's own id. Taken together over all rows, these references form a directed
+graph that must have no cycle.
+
+## Status machine
+
+```
+TRANSITIONS:  active -> retracted
+              active -> superseded
+              retracted, superseded: terminal (no outgoing edge)
+```
+
+No edge leads back to `active`; every row starts as `active`.
+
+## Events
+
+```
+event := { fact_id, from, to, replacement, reason }
+```
+
+An event is valid against the statuses S at its position (every row active, then each earlier
+event applied in order) when:
+
+1. `fact_id` names a row.
+2. `from` equals S[fact_id], so an event can only start from the state the previous event left.
+3. `from -> to` is an edge of `TRANSITIONS`.
+4. `replacement` is non-null exactly when `to = superseded`. A superseded event's replacement
+   is a different row (never `fact_id` itself) and S[replacement] is `active`.
+5. `reason` is a non-empty string.
+6. The event has no other keys.
+
+A writer builds the event with `from` set to the row's current status and checks it with the
+same `transitionError` before it appends anything.
+
+## History invariants
+
+For each row, the events naming it form a chain: the first starts at `active`, and each later
+`from` equals the previous `to`. This holds for every event, not just the last one. Then:
+
+- The row's `status` equals the `to` of its last event.
+- An `active` row has no events. Since no edge returns to `active`, any event leaves the row
+  non-active.
+- A `retracted` or `superseded` row has at least one event (in fact exactly one, because both
+  states are terminal).
+
+Every error message names the fact id it concerns.

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,54 @@ 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 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. |
+| `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 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. |
+| `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. |
+| `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. |
+| `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. |
+| `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_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,7 +94,7 @@ 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
@@ -62,7 +110,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/scripts/claims-index.mjs

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

package/packages/shared-skills/skills/ulw-research/scripts/claims-index.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { indexClaims } from "./claims-index.mjs"
+
+const FIXTURE = join(import.meta.dir, "tests", "fixtures", "fidelity", "claim-graph.md")
+
+describe("indexClaims", () => {
+	test("indexes the fixture claim graph", () => {
+		const { claims, errors } = indexClaims(readFileSync(FIXTURE, "utf8"))
+		expect(errors).toEqual([])
+		expect(claims.map((claim: { claim_id: string; in_verified: boolean }) => claim.claim_id)).toEqual(["C1", "C2", "C3"])
+		expect(claims.filter((claim: { claim_id: string; in_verified: boolean }) => claim.in_verified).map((claim: { claim_id: string; in_verified: boolean }) => claim.claim_id)).toEqual(["C1"])
+		expect(claims[0]).toEqual({
+			claim_id: "C1",
+			statement: "The bridge span is up to 320 m.",
+			risk: "high",
+			status: "supported",
+			in_verified: true,
+		})
+		expect(claims[2].status).toBe("refuted")
+	})
+
+	test("a malformed table returns errors", () => {
+		const bad = [
+			"| claim_id | statement | risk tier | status |",
+			"|---|---|---|---|",
+			"| X1 | bad id | high | supported |",
+			"| C2 | too few cells |",
+		].join("\n")
+		const { errors } = indexClaims(bad)
+		expect(errors.length).toBeGreaterThanOrEqual(2)
+	})
+
+	test("fenced code blocks are skipped: a fenced heading does not end the digest and a fenced entry does not verify", () => {
+		const text = [
+			"| claim_id | statement | risk tier | status |",
+			"|---|---|---|---|",
+			"| C1 | one | high | supported |",
+			"| C2 | two | low | supported |",
+			"",
+			"## verified-claims",
+			"```",
+			"# not a heading",
+			"- C2",
+			"```",
+			"- C1",
+		].join("\n")
+		const { claims, errors } = indexClaims(text)
+		expect(errors).toEqual([])
+		expect(claims.map((claim: { in_verified: boolean }) => claim.in_verified)).toEqual([true, false])
+	})
+
+	test("a document without the claim table returns an error", () => {
+		const { claims, errors } = indexClaims("# claim graph\n\nno table here\n")
+		expect(claims).toEqual([])
+		expect(errors.length).toBe(1)
+	})
+
+	test("a verified id with no claim row is an error", () => {
+		const text = "## verified-claims\n\n- C9\n\n| claim_id | statement | risk tier | status |\n|---|---|---|---|\n| C1 | a | high | supported |\n"
+		expect(indexClaims(text).errors.some((e: string) => e.includes("C9"))).toBe(true)
+	})
+
+	test("only the leading claim id of a verified entry is verified", () => {
+		const text = [
+			"## verified-claims",
+			"",
+			"- C1 (merged from C2)",
+			"",
+			"| claim_id | statement | risk tier | status |",
+			"|---|---|---|---|",
+			"| C1 | a, see C2 | high | supported |",
+			"| C2 | b | high | unresolved |",
+		].join("\n")
+		const { claims, errors } = indexClaims(text)
+		expect(errors).toEqual([])
+		expect(claims.map((claim: { claim_id: string; in_verified: boolean }) => [claim.claim_id, claim.in_verified])).toEqual([
+			["C1", true],
+			["C2", false],
+		])
+	})
+
+	test("a verified-claims line verifies only as a list item or a table row, never as prose", () => {
+		const text = [
+			"## verified-claims",
+			"",
+			"- C1",
+			"C2 is pending review",
+			"1) C3",
+			"| C4 | merged |",
+			"",
+			"| claim_id | statement | risk tier | status |",
+			"|---|---|---|---|",
+			"| C1 | a | high | supported |",
+			"| C2 | b | high | unresolved |",
+			"| C3 | c | high | supported |",
+			"| C4 | d | high | supported |",
+		].join("\n")
+		const { claims, errors } = indexClaims(text)
+		expect(errors).toEqual([])
+		expect(claims.map((claim: { claim_id: string; in_verified: boolean }) => [claim.claim_id, claim.in_verified])).toEqual([
+			["C1", true],
+			["C2", false],
+			["C3", true],
+			["C4", true],
+		])
+	})
+
+	test("the SKILL.md synthesis heading 'Verified claims' is recognized", () => {
+		const text = "## Verified claims\n\n- C1\n\n| claim_id | statement | risk tier | status |\n|---|---|---|---|\n| C1 | a | high | supported |\n"
+		expect(indexClaims(text).claims[0].in_verified).toBe(true)
+	})
+
+	test("a digest heading with a suffix is an error naming the heading, not a silently empty digest", () => {
+		const text = "## Verified claims (2)\n\n- C1\n\n| claim_id | statement | risk tier | status |\n|---|---|---|---|\n| C1 | a | high | supported |\n"
+		const { claims, errors } = indexClaims(text)
+		expect(claims[0].in_verified).toBe(false)
+		expect(errors.some((e: string) => e.startsWith("line 1:") && e.includes('"## Verified claims (2)"'))).toBe(true)
+	})
+
+	test("the verified-claims section ends at the claim table", () => {
+		const text = [
+			"## verified-claims",
+			"- C1",
+			"",
+			"| claim_id | statement | risk tier | status |",
+			"|---|---|---|---|",
+			"| C1 | a | high | supported |",
+			"| C2 | b | high | unresolved |",
+			"",
+			"C2 still pending",
+		].join("\n")
+		const { claims, errors } = indexClaims(text)
+		expect(errors).toEqual([])
+		expect(claims.map((claim: { claim_id: string; in_verified: boolean }) => [claim.claim_id, claim.in_verified])).toEqual([
+			["C1", true],
+			["C2", false],
+		])
+	})
+
+	test("a GFM two-dash separator row is accepted and the first data row is read", () => {
+		const text = "| claim_id | statement | risk tier | status |\n|--|--|--|--|\n| C1 | a | high | supported |\n| C2 | b | normal | unresolved |\n"
+		const { claims, errors } = indexClaims(text)
+		expect(errors).toEqual([])
+		expect(claims.map((claim: { claim_id: string }) => claim.claim_id)).toEqual(["C1", "C2"])
+	})
+})