watertight 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hosung Kang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# watertight
+
+**Reports that hold water — every number carries its receipt, and ungrounded
+claims fail the build.**
+
+```
+$ watertight report.md metrics.json
+
+watertight v0.1.0 · 20 grounded metrics · 4 claims · 5 identifiers
+holds water → report.html
+```
+
+A number typed into prose has no memory of where it came from. Two weeks
+later nobody can say which query produced it, whether it was rounded, or
+whether it was ever true — and when an LLM helps write the report, "never
+true" is a live possibility. watertight treats a report like source code:
+the narrative references metrics, the metrics carry provenance, and a
+compiler refuses to build anything it cannot trace.
+
+An ungrounded number is a **leak**. A report with zero leaks **holds water**.
+
+## Why this exists
+
+This came out of writing a real ad-revenue verification report with an AI
+assistant. Compiling the draft surfaced three distinct failure classes in
+one document:
+
+- a human had written **+15%** for a delta that computed to **+15.5%** —
+  a rounding transcription error nobody had caught;
+- a stated revenue total did not equal the sum of its per-platform parts;
+- the assistant confidently "remembered" a figure that appeared nowhere in
+  any export.
+
+All three are the same disease — a number with no receipt — and all three
+are mechanically detectable. So: detect them, every build.
+
+## Install
+
+```bash
+npm install -g watertight
+# or per-run
+npx watertight report.md metrics.json
+```
+
+Node 18+, zero runtime dependencies.
+
+## How it works
+
+You write two files.
+
+**`metrics.json` — the IR.** Every value, with its receipt:
+
+```json
+{
+  "metrics": {
+    "conversion_before": {
+      "value": 0.031,
+      "unit": "ratio",
+      "definition": "purchases / sessions entering checkout",
+      "source": { "type": "sql", "query": "reports/checkout.sql" },
+      "window": "2026-08-15 ~ 2026-08-31",
+      "fetched_at": "2026-09-15"
+    },
+    "conversion_after": {
+      "value": 0.036,
+      "unit": "ratio",
+      "definition": "purchases / sessions entering checkout",
+      "source": { "type": "sql", "query": "reports/checkout.sql" },
+      "window": "2026-09-01 ~ 2026-09-14",
+      "fetched_at": "2026-09-15"
+    },
+    "lift": {
+      "value": 0.161,
+      "unit": "ratio-point",
+      "definition": "relative change in conversion",
+      "derived": { "op": "pct_change", "before": "conversion_before", "after": "conversion_after" }
+    },
+    "revenue_total": {
+      "value": 1428,
+      "unit": "USD",
+      "derived": { "op": "sum", "of": ["revenue_ios", "revenue_android"] }
+    },
+    "revenue_target": {
+      "value": [1000, 5000],
+      "unit": "USD",
+      "source": { "type": "hypothesis", "doc": "PLAN-42" },
+      "window": "planning estimate",
+      "fetched_at": "-"
+    }
+  },
+  "identifiers": {
+    "app_version": "3.2.0",
+    "flag": "checkout_v2"
+  }
+}
+```
+
+**`report.md` — the narrative.** No literal figures, only references:
+
+```markdown
+Rolled out in `{{id:app_version}}` behind `{{id:flag}}`.
+
+Conversion moved from {{m:conversion_before}} to {{m:conversion_after}},
+a lift of {{m:lift}}. Revenue impact was {{m:revenue_total}}, within the
+hypothesised {{m:revenue_target}}.
+
+{{claim: the experiment met its success criteria | evidence: lift, revenue_total}}
+
+Support runs {{raw:24/7}}.
+```
+
+Compile:
+
+```bash
+watertight report.md metrics.json    # → report.html (self-contained, hover for receipts)
+watertight . --format md             # → grounded markdown: superscripts + receipts appendix
+watertight . --check                 # verify only, write nothing (CI)
+watertight . --json                  # machine-readable result
+```
+
+Any leak fails the build (exit 1) and names the line:
+
+```
+2 leak(s) — the report does not hold water:
+
+  ✗ [naked-number] "15%" appears in the narrative without a receipt
+  ✗ [derived-mismatch] metric "revenue_total" is 1440, but its parts sum to 1428
+```
+
+## What it checks
+
+| check | catches |
+|---|---|
+| `naked-number` | any digit in prose not covered by a reference (dates, headings, code spans and `{{raw:}}` are exempt) |
+| `unknown-ref` | `{{m:...}}` / `{{id:...}}` pointing at nothing |
+| `missing-field` | a measured metric without `source`, `window`, or `fetched_at` |
+| `definition-required` | a `ratio` / `ratio-point` metric with no stated basis — this is how a fill rate of 107% stays honest |
+| `derived-mismatch` | a `sum` that doesn't add up; a `pct_change` that doesn't recompute — to the stored value's own precision, so `0.161` passes as 16.1% but `0.15` for 15.5% fails |
+| `claim-without-evidence` | a `{{claim:}}` with no `evidence:` keys, or keys that don't exist |
+| `bad-derived` | derived ops referencing missing or non-numeric inputs |
+| `empty-ir` | a report "grounded" in nothing |
+
+## Re-verification
+
+Numbers age. `watertight refresh .` re-fetches every metric whose source it
+can reach, rewrites `value` and `fetched_at`, and recomputes derived values:
+
+- `csv` sources — `{ "type": "csv", "file": "data.csv", "cell": "B2" }`
+- `json` sources — `{ "type": "json", "file": "kpi.json", "path": "revenue.total" }`
+- `command` sources — run **only** with the explicit `--allow-commands` flag,
+  because refreshing an IR you didn't author must never execute its shell
+  commands
+- everything else (dashboards, vendor reports, hypotheses) is **named as
+  skipped** — never silently assumed fresh
+
+`--dry-run` previews changes without writing.
+
+## For AI-authored reports
+
+[`SKILL.md`](./SKILL.md) is an authoring contract for coding agents: gather
+receipts first, build the IR from real sources only, reference — never type —
+figures, and fix leaks by re-fetching, not by weakening the text. The compile
+step turns "please don't hallucinate numbers" from a request into a gate.
+
+## What it deliberately does not do
+
+- **Judge whether evidence supports a claim.** `{{claim:}}` proves evidence
+  is *attached* and *exists*; whether it actually supports the conclusion is
+  the author's judgment. The tool makes that judgment inspectable, not
+  automatic.
+- **Verify a source is truthful.** A receipt says where a number came from,
+  not that the origin was right.
+- **Use an LLM.** Every check is deterministic. The point is to be the fixed
+  ground an LLM-assisted workflow can push against.
+
+## Related work
+
+- [Proof-Carrying Numbers (arXiv:2509.06902)](https://arxiv.org/abs/2509.06902)
+  proposes numbers as claim-bound tokens verified at render time — the same
+  philosophy applied to LLM output streams. watertight applies it to the
+  document build step instead.
+- [Evidence](https://evidence.dev) compiles markdown + SQL into reports, and
+  proves the "reports as source code" mechanism — but doesn't enforce that
+  prose figures stay grounded.
+
+## License
+
+MIT © [Hosung Kang](https://github.com/camosss)

package/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: watertight
+description: Write reports where every number carries its receipt. Use when authoring any document that states metrics — experiment verifications, incident reviews, performance reports — so that no figure appears without a recorded source, and hallucinated or stale numbers fail the build instead of shipping.
+---
+
+# watertight
+
+You are writing a report that must hold water: every number in it either
+carries a receipt or the compile fails. Your job is not to make the compiler
+pass — it is to make the report true, and use the compiler to prove it.
+
+## Setup
+
+```bash
+npm install -g watertight   # or: npx watertight
+```
+
+## The workflow
+
+**1. Gather receipts before writing prose.**
+For every figure the report will state, record where it came from *at the
+moment you obtain it* — the query, the export, the dashboard URL, the
+document. If you cannot say where a number came from, you do not have the
+number yet.
+
+**2. Write the IR (`metrics.json`).**
+
+```json
+{
+  "metrics": {
+    "conversion_after": {
+      "value": 0.036,
+      "unit": "ratio",
+      "definition": "purchases / sessions entering checkout",
+      "source": { "type": "sql", "query": "reports/checkout.sql" },
+      "window": "2026-09-01 ~ 2026-09-14",
+      "fetched_at": "2026-09-15"
+    },
+    "revenue_total": {
+      "value": 1428, "unit": "USD",
+      "derived": { "op": "sum", "of": ["revenue_ios", "revenue_android"] }
+    },
+    "lift": {
+      "value": 0.161, "unit": "ratio-point",
+      "definition": "relative change in conversion",
+      "derived": { "op": "pct_change", "before": "conversion_before", "after": "conversion_after" }
+    }
+  },
+  "identifiers": { "app_version": "3.2.0", "flag": "checkout_v2" }
+}
+```
+
+- `source.type` is free-form (`sql`, `mixpanel`, `csv`, `hypothesis`, …);
+  put enough alongside it that a stranger could re-fetch the value.
+- Numbers that *name* rather than *measure* (versions, flags, unit IDs) go
+  in `identifiers`, not `metrics`.
+- Anything computed from other metrics must be `derived` — the compiler
+  recomputes it and rejects mismatches beyond the value's own precision.
+- `ratio` / `ratio-point` metrics require a `definition`. Ratios above 1.0
+  are legal but the definition must explain the basis.
+- A hypothesis or plan figure is still a metric — source it as
+  `{ "type": "hypothesis", ... }` pointing at the planning doc.
+
+**3. Write the narrative (`report.md`).**
+Never type a figure into prose. Reference it:
+
+- `{{m:conversion_after}}` — renders the value with its receipt
+- `{{id:app_version}}` — identifier
+- `{{claim: the fallback works on both platforms | evidence: recovery_ios, recovery_android}}`
+  — a qualitative conclusion, pinned to the metrics that support it
+- `{{raw:24/7}}` — escape hatch for rhetorical numbers; it is greppable,
+  so use it rarely and honestly
+
+**4. Compile, and treat every leak as a question about the data.**
+
+```bash
+watertight report.md metrics.json          # writes report.html
+watertight . --format md                    # grounded markdown (Notion / PR / Slack)
+watertight . --check                        # CI mode: verify, write nothing
+```
+
+Fix leaks by *going and getting the receipt* — running the query, opening
+the export — never by deleting the number, weakening the claim, or wrapping
+a measurement in `{{raw:}}` to silence the checker. A `derived-mismatch` is
+the tool telling you a stated total or delta does not follow from its
+inputs: recompute at the source and correct whichever side is wrong.
+
+**5. Re-verify later with `watertight refresh .`** — re-fetches csv/json
+sources, updates `fetched_at`, recomputes derived values, and names every
+metric it could *not* refresh. `command` sources run only under
+`--allow-commands`; never pass that flag on an IR you did not author.
+
+## What stays yours
+
+The compiler proves every number has a source and every arithmetic step
+checks out. It does not judge whether the evidence actually supports the
+claim — that judgment is the author's, and pinning claims to named metrics
+exists to make that judgment inspectable, not to automate it away.
+
+## Hard rules
+
+- Never invent, estimate, or "recall" a value into the IR. No source, no number.
+- Never edit a `value` to make a `derived-mismatch` pass. Fix the inputs.
+- Real company data stays in private storage; fixtures and examples are fictional.

package/dist/cli.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+import { access, readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { compile } from './compile.js';
+import { refresh } from './refresh.js';
+const USAGE = `watertight — reports that hold water. Every number carries its receipt;
+an ungrounded claim is a leak, and a report with leaks does not build.
+
+Usage
+  watertight <dir>             compile <dir>/report.md + <dir>/metrics.json → <dir>/report.html
+  watertight <report> <ir>     explicit file paths
+  watertight refresh <dir>     re-fetch metric values from their sources, update metrics.json
+
+Options
+  --format <html|md> output format (default: html). md is grounded markdown with a
+                     receipts appendix — pastes into Notion, PR bodies or Slack intact
+  --out <file>       where to write the output (default: report.html / report.grounded.md)
+  --check            verify only, write nothing
+  --dry-run          refresh only: show what would change, write nothing
+  --allow-commands   refresh only: let "command" sources run shell (off by default —
+                     an IR from someone else's repo must not execute code on your machine)
+  --json          machine-readable result on stdout
+  -v, --version   print the version
+  -h, --help      show this message
+
+watertight only reads the two input files and writes the one output file — nothing else.
+`;
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    const positional = [];
+    let out;
+    let check = false;
+    let json = false;
+    let dryRun = false;
+    let allowCommands = false;
+    let format = 'html';
+    let help = false;
+    let version = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--out')
+            out = args[++i];
+        else if (arg === '--check')
+            check = true;
+        else if (arg === '--dry-run')
+            dryRun = true;
+        else if (arg === '--allow-commands')
+            allowCommands = true;
+        else if (arg === '--format')
+            format = args[++i] === 'md' ? 'md' : 'html';
+        else if (arg === '--json')
+            json = true;
+        else if (arg === '-h' || arg === '--help')
+            help = true;
+        else if (arg === '-v' || arg === '--version')
+            version = true;
+        else if (!arg.startsWith('-'))
+            positional.push(arg);
+    }
+    const command = positional[0] === 'refresh' ? 'refresh' : 'compile';
+    if (command === 'refresh')
+        positional.shift();
+    return { command, positional, out, check, json, help, version, dryRun, allowCommands, format };
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function main() {
+    const opts = parseArgs(process.argv);
+    const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    if (opts.version)
+        return console.log(pkg.version);
+    if (opts.help)
+        return console.log(USAGE);
+    // a mistyped path must fail loudly, never read as an empty report
+    let reportPath;
+    let irPath;
+    if (opts.positional.length === 2) {
+        ;
+        [reportPath, irPath] = opts.positional.map((p) => resolve(p));
+    }
+    else {
+        const dir = resolve(opts.positional[0] ?? '.');
+        reportPath = join(dir, 'report.md');
+        irPath = join(dir, 'metrics.json');
+    }
+    for (const path of [reportPath, irPath]) {
+        if (!(await exists(path))) {
+            console.error(`Not found: ${path}`);
+            console.error('Expected report.md and metrics.json — see --help.');
+            process.exit(2);
+        }
+    }
+    if (opts.command === 'refresh') {
+        const r = await refresh(irPath, { allowCommands: opts.allowCommands, dryRun: opts.dryRun });
+        for (const c of r.changes)
+            console.log(`  ${c.key}: ${c.before.toLocaleString()} → ${c.after.toLocaleString()}`);
+        for (const s of r.skipped)
+            console.log(`  ~ ${s.key} skipped — ${s.reason}`);
+        for (const e of r.errors)
+            console.error(`  ✗ ${e.key}: ${e.message}`);
+        console.log(r.errors.length > 0
+            ? `\n${r.errors.length} fetch error(s) — metrics.json ${r.wrote ? 'partially updated' : 'not written'}`
+            : `\n${r.changes.length} change(s)${opts.dryRun ? ' (dry run — nothing written)' : r.wrote ? ` — updated ${irPath}` : ''}`);
+        process.exit(r.errors.length > 0 ? 1 : 0);
+    }
+    const result = await compile(reportPath, irPath, opts.format);
+    const defaultName = opts.format === 'md' ? 'report.grounded.md' : 'report.html';
+    const outPath = resolve(opts.out ?? join(reportPath, '..', defaultName));
+    if (opts.json) {
+        console.log(JSON.stringify({ version: pkg.version, ...result, output: undefined, wrote: result.output && !opts.check ? outPath : undefined }, null, 2));
+    }
+    else {
+        console.log(`\nwatertight v${pkg.version} · ${result.grounded.metrics} grounded metrics · ${result.grounded.claims} claims · ${result.grounded.identifiers} identifiers`);
+        if (result.leaks.length > 0) {
+            console.log(`\n${result.leaks.length} leak(s) — the report does not hold water:\n`);
+            for (const leak of result.leaks) {
+                console.log(`  ✗ [${leak.rule}] ${leak.message}`);
+                if (leak.detail)
+                    console.log(`    ${leak.detail}`);
+            }
+            console.log();
+        }
+    }
+    if (result.output && !opts.check) {
+        await writeFile(outPath, result.output);
+        if (!opts.json)
+            console.log(`holds water → ${outPath}\n`);
+    }
+    else if (result.output && opts.check && !opts.json) {
+        console.log('holds water (check only — nothing written)\n');
+    }
+    process.exit(result.leaks.length > 0 ? 1 : 0);
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(2);
+});

package/dist/compile.js

@@ -0,0 +1,20 @@
+import { readFile } from 'node:fs/promises';
+import { parseIr } from './ir.js';
+import { render } from './render.js';
+import { renderMarkdown } from './renderMd.js';
+import { scanNakedNumbers, scanRefs } from './scan.js';
+export async function compile(reportPath, irPath, format = 'html') {
+    const report = await readFile(reportPath, 'utf8');
+    const { ir, leaks } = parseIr(JSON.parse(await readFile(irPath, 'utf8')));
+    const grounded = {
+        metrics: [...report.matchAll(/\{\{m:/g)].length,
+        identifiers: [...report.matchAll(/\{\{id:/g)].length,
+        claims: [...report.matchAll(/\{\{claim:/g)].length,
+    };
+    leaks.push(...scanNakedNumbers(report));
+    if (ir)
+        leaks.push(...scanRefs(report, new Set(Object.keys(ir.metrics)), new Set(Object.keys(ir.identifiers))));
+    if (leaks.length > 0 || !ir)
+        return { leaks, grounded };
+    return { leaks, output: format === 'md' ? renderMarkdown(report, ir) : render(report, ir), grounded };
+}

package/dist/ir.js

@@ -0,0 +1,96 @@
+/** Units whose meaning depends on how they were aggregated — a bare value misleads. */
+const DEFINITION_REQUIRED = new Set(['ratio', 'ratio-point']);
+function decimals(n) {
+    const s = String(n);
+    const dot = s.indexOf('.');
+    return dot === -1 ? 0 : s.length - dot - 1;
+}
+/**
+ * A stored derived value must be correctly rounded to its own precision: writing 0.15
+ * for a computed 0.155 is a mismatch, writing 0.155 for 0.15517 is fine. This is what
+ * caught a rounding error in the first real document this schema was tested against.
+ */
+function roundsTo(stored, computed) {
+    return Math.abs(stored - computed) < 0.5 * 10 ** -decimals(stored);
+}
+export function parseIr(raw) {
+    const leaks = [];
+    const root = (raw ?? {});
+    const identifiers = {};
+    for (const [k, v] of Object.entries(root['identifiers'] ?? {})) {
+        identifiers[k] = String(v);
+    }
+    const metrics = root['metrics'] ?? {};
+    if (Object.keys(metrics).length === 0) {
+        leaks.push({
+            severity: 'error',
+            rule: 'empty-ir',
+            message: 'The IR declares no metrics',
+            detail: 'A report with nothing grounded is not a watertight report.',
+        });
+        return { leaks };
+    }
+    for (const [key, m] of Object.entries(metrics)) {
+        if (m.value === undefined) {
+            leaks.push({ severity: 'error', rule: 'missing-field', message: `metric "${key}" has no value` });
+            continue;
+        }
+        if (typeof m.unit !== 'string' || m.unit.length === 0) {
+            leaks.push({ severity: 'error', rule: 'missing-field', message: `metric "${key}" has no unit` });
+        }
+        if (DEFINITION_REQUIRED.has(m.unit) && !m.definition) {
+            leaks.push({
+                severity: 'error',
+                rule: 'definition-required',
+                message: `metric "${key}" is a ${m.unit} without a definition`,
+                detail: 'Ratios mislead without their aggregation basis — a fill rate above 100% is either a bug or a definition, and the reader must be told which.',
+            });
+        }
+        if (m.derived) {
+            if (Array.isArray(m.value)) {
+                leaks.push({ severity: 'error', rule: 'bad-derived', message: `metric "${key}": a range cannot be derived` });
+                continue;
+            }
+            if (m.derived.op === 'sum') {
+                let computed = 0;
+                let broken = false;
+                for (const ref of m.derived.of) {
+                    const part = metrics[ref];
+                    if (!part || typeof part.value !== 'number') {
+                        leaks.push({ severity: 'error', rule: 'bad-derived', message: `metric "${key}" sums unknown or non-scalar metric "${ref}"` });
+                        broken = true;
+                        continue;
+                    }
+                    computed += part.value;
+                }
+                if (!broken && computed !== m.value) {
+                    leaks.push({
+                        severity: 'error',
+                        rule: 'derived-mismatch',
+                        message: `metric "${key}" is ${m.value}, but its parts sum to ${computed}`,
+                    });
+                }
+            }
+            else if (m.derived.op === 'pct_change') {
+                const computed = (m.derived.after - m.derived.before) / m.derived.before;
+                if (!roundsTo(m.value, computed)) {
+                    leaks.push({
+                        severity: 'error',
+                        rule: 'derived-mismatch',
+                        message: `metric "${key}" is ${m.value}, but ${m.derived.before} → ${m.derived.after} computes to ${computed.toFixed(4)}`,
+                        detail: 'A derived value must be correctly rounded to its own precision.',
+                    });
+                }
+            }
+        }
+        else {
+            // a measured value must say where it came from and when
+            for (const field of ['source', 'window', 'fetched_at']) {
+                if (m[field] === undefined) {
+                    leaks.push({ severity: 'error', rule: 'missing-field', message: `metric "${key}" has no ${field}` });
+                }
+            }
+        }
+    }
+    return { ir: { identifiers, metrics }, leaks };
+}

package/dist/refresh.js

@@ -0,0 +1,125 @@
+import { execSync } from 'node:child_process';
+import { readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+/** "B4" → row 4, column B. The spreadsheet convention people already know. */
+function cellToIndex(cell) {
+    const m = /^([A-Z]+)(\d+)$/i.exec(cell.trim());
+    if (!m)
+        throw new Error(`not an A1-style cell: "${cell}"`);
+    let col = 0;
+    for (const ch of m[1].toUpperCase())
+        col = col * 26 + (ch.charCodeAt(0) - 64);
+    return { row: Number(m[2]) - 1, col: col - 1 };
+}
+/** Minimal CSV: quoted fields with embedded commas supported, embedded newlines not. */
+function parseCsvLine(line) {
+    const out = [];
+    let field = '';
+    let quoted = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (quoted) {
+            if (ch === '"' && line[i + 1] === '"') {
+                field += '"';
+                i++;
+            }
+            else if (ch === '"')
+                quoted = false;
+            else
+                field += ch;
+        }
+        else if (ch === '"')
+            quoted = true;
+        else if (ch === ',') {
+            out.push(field);
+            field = '';
+        }
+        else
+            field += ch;
+    }
+    out.push(field);
+    return out;
+}
+function toNumber(raw, where) {
+    const n = Number(String(raw).replace(/[,\s]/g, ''));
+    if (!Number.isFinite(n))
+        throw new Error(`${where} is not a number: "${raw}"`);
+    return n;
+}
+async function fetchCsv(source, baseDir) {
+    const text = await readFile(resolve(baseDir, String(source['file'])), 'utf8');
+    const { row, col } = cellToIndex(String(source['cell']));
+    const lines = text.split(/\r?\n/);
+    if (row >= lines.length)
+        throw new Error(`row ${row + 1} is past the end of ${source['file']}`);
+    const fields = parseCsvLine(lines[row]);
+    if (col >= fields.length)
+        throw new Error(`column ${source['cell']} is past the end of row ${row + 1}`);
+    return toNumber(fields[col], `${source['file']}!${source['cell']}`);
+}
+async function fetchJson(source, baseDir) {
+    const data = JSON.parse(await readFile(resolve(baseDir, String(source['file'])), 'utf8'));
+    let node = data;
+    const path = String(source['path']);
+    for (const part of path.split(/[.[\]]+/).filter(Boolean)) {
+        node = node?.[part];
+    }
+    return toNumber(node, `${source['file']} → ${path}`);
+}
+function fetchCommand(source, baseDir) {
+    const stdout = execSync(String(source['run']), { cwd: baseDir, encoding: 'utf8', timeout: 30_000 });
+    return toNumber(stdout.trim().split('\n').at(-1), `command output`);
+}
+export async function refresh(irPath, options) {
+    const raw = JSON.parse(await readFile(irPath, 'utf8'));
+    const baseDir = dirname(resolve(irPath));
+    const result = { changes: [], skipped: [], errors: [], wrote: false };
+    const now = new Date().toISOString();
+    for (const [key, m] of Object.entries(raw.metrics)) {
+        if (m.derived || !m.source || Array.isArray(m.value))
+            continue;
+        try {
+            let value;
+            if (m.source.type === 'csv')
+                value = await fetchCsv(m.source, baseDir);
+            else if (m.source.type === 'json')
+                value = await fetchJson(m.source, baseDir);
+            else if (m.source.type === 'command') {
+                if (!options.allowCommands) {
+                    result.skipped.push({ key, reason: 'command sources run only with --allow-commands' });
+                    continue;
+                }
+                value = fetchCommand(m.source, baseDir);
+            }
+            else {
+                result.skipped.push({ key, reason: `no built-in adapter for source type "${m.source.type}"` });
+                continue;
+            }
+            if (value !== m.value)
+                result.changes.push({ key, before: m.value, after: value });
+            m.value = value;
+            m.fetched_at = now;
+        }
+        catch (err) {
+            result.errors.push({ key, message: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    // parts may have moved, so stored sums are recomputed rather than left to go stale
+    for (const [key, m] of Object.entries(raw.metrics)) {
+        if (m.derived?.op !== 'sum' || Array.isArray(m.value))
+            continue;
+        const computed = m.derived.of.reduce((acc, ref) => {
+            const part = raw.metrics[ref];
+            return acc + (part && typeof part.value === 'number' ? part.value : NaN);
+        }, 0);
+        if (Number.isFinite(computed) && computed !== m.value) {
+            result.changes.push({ key, before: m.value, after: computed });
+            m.value = computed;
+        }
+    }
+    if (!options.dryRun && (result.changes.length > 0 || result.errors.length === 0)) {
+        await writeFile(irPath, `${JSON.stringify(raw, null, 2)}\n`);
+        result.wrote = true;
+    }
+    return result;
+}

package/dist/render.js

@@ -0,0 +1,66 @@
+function escapeHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+export function formatValue(m) {
+    if (Array.isArray(m.value)) {
+        const [lo, hi] = m.value;
+        return `${lo.toLocaleString()}~${hi.toLocaleString()}${m.unit === 'ratio' ? '%' : ` ${m.unit}`}`;
+    }
+    if (m.unit === 'ratio')
+        return `${(m.value * 100).toFixed(m.value < 0.01 ? 2 : 1)}%`;
+    if (m.unit === 'ratio-point')
+        return `${m.value >= 0 ? '+' : ''}${(m.value * 100).toFixed(1)}%p`;
+    return `${m.value.toLocaleString()} ${m.unit}`.trim();
+}
+export function receipt(m) {
+    const source = m.derived
+        ? m.derived.op === 'sum'
+            ? `= ${m.derived.of.join(' + ')} (recomputed)`
+            : `= ${m.derived.before} → ${m.derived.after} (recomputed)`
+        : [m.source?.type, ...Object.entries(m.source ?? {}).filter(([k]) => k !== 'type').map(([, v]) => String(v))].filter(Boolean).join(' · ');
+    return [source, m.window, m.fetched_at && `fetched ${m.fetched_at}`, m.definition].filter(Boolean).join(' · ');
+}
+/** Minimal markdown: headings, paragraphs, bold, unordered lists. The narrative layer is deliberately thin. */
+function markdown(src) {
+    return src
+        .split(/\n{2,}/)
+        .map((block) => {
+        const h = block.match(/^(#{1,3}) (.*)$/s);
+        if (h)
+            return `<h${h[1].length}>${h[2]}</h${h[1].length}>`;
+        if (/^- /m.test(block)) {
+            return `<ul>${block.split('\n').map((l) => `<li>${l.replace(/^- /, '')}</li>`).join('')}</ul>`;
+        }
+        return `<p>${block.replace(/\n/g, '<br>')}</p>`;
+    })
+        .join('\n')
+        .replace(/\*\*([^*]+)\*\*/g, '<b>$1</b>');
+}
+export function render(report, ir) {
+    const grounded = escapeHtml(report)
+        .replace(/\{\{m:([\w-]+)\}\}/g, (_, key) => {
+        const m = ir.metrics[key];
+        return `<b class="w" title="${escapeHtml(receipt(m))}">${formatValue(m)}<sup>†</sup></b>`;
+    })
+        .replace(/\{\{id:([\w-]+)\}\}/g, (_, key) => `<code>${escapeHtml(ir.identifiers[key])}</code>`)
+        .replace(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g, (_, text, evidence) => {
+        const keys = evidence.split(',').map((k) => k.trim()).filter(Boolean);
+        const receipts = keys
+            .map((k) => `${k} = ${formatValue(ir.metrics[k])} (${receipt(ir.metrics[k])})`)
+            .join(' | ');
+        return `<span class="c" title="${escapeHtml(receipts)}">${text.trim()}<sup>‡</sup></span>`;
+    })
+        .replace(/\{\{raw:([^}]*)\}\}/g, (_, text) => escapeHtml(text));
+    return `<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<style>
+  body{font:15px/1.75 -apple-system,system-ui,sans-serif;max-width:720px;margin:40px auto;padding:0 16px;color:#1a1a1a}
+  @media(prefers-color-scheme:dark){body{background:#111;color:#ddd}code{background:#222}}
+  h1,h2,h3{line-height:1.3}
+  .w{border-bottom:2px solid #4a9;cursor:help;font-weight:600}
+  .c{border-bottom:2px dotted #4a9;cursor:help}
+  code{background:#eee;padding:1px 5px;border-radius:4px;font-size:.9em}
+  sup{font-size:.65em;color:#4a9}
+</style>
+<body>${markdown(grounded)}
+<hr><p style="color:#888;font-size:.85em">Compiled by watertight — every underlined figure carries its receipt (hover to see it).</p>`;
+}

package/dist/renderMd.js

@@ -0,0 +1,27 @@
+import { formatValue, receipt } from './render.js';
+/**
+ * Grounded markdown: the portable render target. Every figure is bold with a superscript
+ * that points into a receipts appendix, so the output pastes into Notion, a PR body, or
+ * Slack without losing its provenance. Posting is deliberately left to the caller —
+ * keeping publishing out of the tool is what keeps the tool free of anyone's auth.
+ */
+export function renderMarkdown(report, ir) {
+    const used = [];
+    const body = report
+        .replace(/\{\{m:([\w-]+)\}\}/g, (_, key) => {
+        if (!used.includes(key))
+            used.push(key);
+        return `**${formatValue(ir.metrics[key])}** ⁽${used.indexOf(key) + 1}⁾`;
+    })
+        .replace(/\{\{id:([\w-]+)\}\}/g, (_, key) => `\`${ir.identifiers[key]}\``)
+        .replace(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g, (_, text, evidence) => `**${text.trim()}** *(evidence: ${evidence.trim()})*`)
+        .replace(/\{\{raw:([^}]*)\}\}/g, (_, text) => text);
+    const appendix = used
+        .map((key, i) => {
+        const m = ir.metrics[key];
+        const definition = m.definition ? ` — ${m.definition}` : '';
+        return `${i + 1}. **${key}** = ${formatValue(m)}${definition}\n   ${receipt(m)}`;
+    })
+        .join('\n');
+    return `${body}\n\n---\n\n### Receipts (${used.length} metrics)\n\n${appendix}\n`;
+}

package/dist/scan.js

@@ -0,0 +1,71 @@
+/**
+ * Find numbers in the narrative that are not bound to the IR. These are the leaks the
+ * tool exists to catch: a typed, transcribed, or hallucinated figure reads exactly like
+ * a real one, so none are allowed outside a reference.
+ */
+export function scanNakedNumbers(report) {
+    const stripped = report
+        .replace(/\{\{(m|id):[\w-]+\}\}/g, ' ')
+        // a claim's prose stays scanned — only its syntax is removed, so a number
+        // smuggled into claim text is still a leak
+        .replace(/\{\{claim:([^|}]*)\|[^}]*\}\}/g, (_, text) => ` ${text} `)
+        .replace(/\{\{raw:[^}]*\}\}/g, ' ') // explicit, greppable escape hatch
+        .replace(/```[\s\S]*?```/g, ' ') // fenced code
+        .replace(/`[^`\n]*`/g, ' ') // inline code
+        .replace(/\d{4}-\d{2}-\d{2}/g, ' ') // ISO dates locate, they do not measure
+        .replace(/^#+ .*$/gm, ' ') // headings
+        .replace(/^\s*\d+\.\s/gm, ' '); // ordered-list markers
+    const leaks = [];
+    for (const m of stripped.matchAll(/\d[\d,.]*\s*(%p?|[가-힣]{1,2})?/g)) {
+        const token = m[0].trim();
+        if (!token)
+            continue;
+        leaks.push({
+            severity: 'error',
+            rule: 'naked-number',
+            message: `"${token}" appears in the narrative without a receipt`,
+            detail: 'Bind it to the IR as {{m:…}} or {{id:…}}, or mark deliberate prose as {{raw:…}}.',
+        });
+    }
+    return leaks;
+}
+/** Every reference in the narrative must resolve; a dangling one is authoring drift. */
+export function scanRefs(report, metricKeys, idKeys) {
+    const leaks = [];
+    for (const [, text, evidence] of report.matchAll(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g)) {
+        const keys = evidence.split(',').map((k) => k.trim()).filter(Boolean);
+        if (keys.length === 0) {
+            leaks.push({
+                severity: 'error',
+                rule: 'claim-without-evidence',
+                message: `claim "${text.trim()}" names no evidence`,
+                detail: 'A conclusion must point at the metrics it rests on. Whether they support it stays a human judgement — but they must be attached.',
+            });
+        }
+        for (const key of keys) {
+            if (!metricKeys.has(key)) {
+                leaks.push({ severity: 'error', rule: 'unknown-ref', message: `claim "${text.trim()}" cites unknown metric "${key}"` });
+            }
+        }
+    }
+    // a claim marker missing its evidence clause entirely is malformed, not exempt
+    for (const [, text] of report.matchAll(/\{\{claim:([^|}]*)\}\}/g)) {
+        leaks.push({
+            severity: 'error',
+            rule: 'claim-without-evidence',
+            message: `claim "${text.trim()}" names no evidence`,
+            detail: 'Write it as {{claim: … | evidence: metric_key}}.',
+        });
+    }
+    for (const [, key] of report.matchAll(/\{\{m:([\w-]+)\}\}/g)) {
+        if (!metricKeys.has(key)) {
+            leaks.push({ severity: 'error', rule: 'unknown-ref', message: `{{m:${key}}} is not in the IR` });
+        }
+    }
+    for (const [, key] of report.matchAll(/\{\{id:([\w-]+)\}\}/g)) {
+        if (!idKeys.has(key)) {
+            leaks.push({ severity: 'error', rule: 'unknown-ref', message: `{{id:${key}}} is not in the IR` });
+        }
+    }
+    return leaks;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "watertight",
+  "version": "0.1.0",
+  "description": "Reports that hold water \u2014 every number carries its receipt, and ungrounded claims fail the build.",
+  "type": "module",
+  "bin": {
+    "watertight": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "SKILL.md"
+  ],
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "keywords": [
+    "report",
+    "provenance",
+    "grounding",
+    "metrics",
+    "verification",
+    "hallucination",
+    "documentation",
+    "ci"
+  ],
+  "author": "Hosung Kang (https://github.com/camosss)",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "tsx": "^4.23.12",
+    "typescript": "^7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/camosss/watertight.git"
+  },
+  "homepage": "https://github.com/camosss/watertight#readme",
+  "bugs": {
+    "url": "https://github.com/camosss/watertight/issues"
+  }
+}