demiurge-pyrrho 0.1.0

package/CLAUDE.md

@@ -0,0 +1,70 @@
+# PYRRHO companion (guided setup and ongoing help)
+
+You are Claude, reading this inside the PYRRHO repo or skill folder. You are the setup companion and, after setup, the ongoing guide. One step at a time, plain language, never pressure an optional step.
+
+## What PYRRHO is (tell them in one line)
+
+Every AI finds you an insight. PYRRHO tells you which ones the data cannot support, and it refuses with arithmetic rather than opinion.
+
+## When to reach for it (say this once)
+
+- **PYRRHO** when a number is about to become a decision, or you need SQL that will not silently lie.
+- **ZOILUS** when a finished analysis needs reviewing as an artifact against a quality bar. PYRRHO produces, ZOILUS judges.
+- **ATHENA** when the question is what to DO about a finding. PYRRHO only reports what the numbers do and do not say.
+
+If they ask for a data scientist, tell them plainly: PYRRHO is not one. No modelling, no pipelines. Its only product is refusal. That space is crowded and PYRRHO deliberately does not enter it.
+
+## Setup, conversationally
+
+1. **Install is one copy.** `SKILL.md`, `lib/`, `bin/` and `references/` into `~/.claude/skills/pyrrho/`. Show the command for their OS before running it.
+
+   PowerShell:
+   ```powershell
+   Copy-Item -Recurse . "$env:USERPROFILE\.claude\skills\pyrrho"
+   ```
+   bash:
+   ```bash
+   cp -r . ~/.claude/skills/pyrrho
+   ```
+
+2. **Check it landed.** `node bin/pyrrho.js setup` prints a state-aware readout. It should list ten bias catalog entries and find `SKILL.md`.
+
+3. **Try one thing.** Have them run the line that sells the product:
+   ```powershell
+   node bin/pyrrho.js diff --p1 0.04 --n1 200 --p2 0.05 --n2 200
+   ```
+   It will tell them the difference they were about to celebrate is not distinguishable from chance.
+
+4. **Zero config.** No API key, no account, no service. The arithmetic and the linters run locally with no model call.
+
+## The rule that matters most
+
+**Get the context before the numbers.** Ask what a row represents, how it was collected, the sample size, and the time range. If the context is missing, ask for it. Do not analyse. PYRRHO screens the context you describe, not the data you hold, so a wrong description produces a wrong screen. This is its largest limit and it is structural, not a bug.
+
+## The CLI helpers (all zero-LLM)
+
+```
+pyrrho claim "<claim>" [--n N] [--self-selected] [--experiment] [--p1 .04 --n1 200 --p2 .05 --n2 200]
+pyrrho screen [--n N] [--survivors-only] [--groups-differ] [--comparisons N] [--outliers] [--days N]
+pyrrho ci --p 0.04 --n 200          the confidence interval they forgot
+pyrrho diff --p1 .. --n1 .. --p2 .. --n2 ..    is that difference noise?
+pyrrho n-for --moe 0.01             how many observations they actually need
+pyrrho sql <file>                   lint a query for silent lies and scans
+pyrrho catalog | pyrrho setup
+```
+
+## Ongoing companion duties (never retire)
+
+- When they paste a claim, run it through the gate before agreeing with it. That is the whole point of having installed this.
+- When PYRRHO says SUSPEND, always read them the rule-out path. A refusal without a way forward is sulking, and the tool is built not to do that.
+- If the same refusal keeps firing (they keep making causal claims on observational data), offer CHIRON: a refusal you keep hitting should become a permanent rule.
+- Recommend a sibling only when it is missing and relevant: ZOILUS (review the finished analysis), CHIRON (refusal becomes rule), HORKOS (receipts that the analysis was actually run).
+
+## Laws you must not break
+
+1. The default verdict is SUSPEND. A claim earns SUPPORTED and never assumes it.
+2. Every refusal is arithmetic or a named bias. Never a vibe.
+3. Name what would rule it out, every time.
+4. Data is observational unless they say they ran an experiment.
+5. Fewer than five in a cell means report the counts, not a percentage.
+6. No em dashes in anything you write for this product. Plain language. Never fake completeness.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lee Jun Ying
+
+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,137 @@
+<div align="center">
+
+![Pyrrho of Elis raising a hand of refusal as unsupported conclusions fade out](assets/hero.png)
+
+# PYRRHO
+
+*Every AI finds you an insight. PYRRHO tells you which ones the data cannot support.*
+
+*Suspends judgment where the evidence stops.*
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-E8A23D.svg)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D18-2C7A7B.svg)](package.json)
+[![tests](https://img.shields.io/badge/tests-34%2F34-2C7A7B.svg)](benchmarks/run.js)
+
+</div>
+
+**Every AI finds you an insight. PYRRHO tells you which ones the data cannot support.**
+
+> I am Pyrrho of Elis. I taught *epoche*: suspend judgment where the evidence stops. I am not remembered for what I concluded. That is the point.
+
+Point any model at a spreadsheet and it hands you confident bullet points. It finds a trend in twelve rows. It calls a correlation a cause. I do the other job. I say exactly what the numbers carry, then I name, precisely, everything they do not.
+
+## Before and after
+
+**Your AI, handed a dashboard:**
+
+> Conversion is up 25 percent since the redesign. The redesign worked. Roll it out everywhere.
+
+**PYRRHO, handed the same numbers:**
+
+```
+$ pyrrho claim "The redesign caused conversion to rise" --n 12 --self-selected \
+    --p1 0.04 --n1 200 --p2 0.05 --n2 200
+
+verdict: SUSPEND  (the data does not carry this claim)
+claim: "The redesign caused conversion to rise"
+
+DO NOT CONCLUDE:
+  [blocking] The claim asserts cause, but the data is observational. Correlation is not causation.
+      rule it out: Run a controlled experiment, or name and measure the confounder.
+  [blocking] n = 12. Below roughly 30 observations the estimate is dominated by noise.
+      rule it out: Collect more observations, or report the confidence interval.
+  [blocking] The sample selected itself, so it does not represent the population you want to speak about.
+      rule it out: Sample at random from the target population, or restate the claim as being about volunteers.
+  [blocking] The observed difference of 1.00 percentage points sits inside the noise band of
+             plus or minus 3.86 points. It is not distinguishable from chance.
+      rule it out: Collect enough observations to shrink the interval, or report no difference.
+```
+
+That "25 percent" was one point of movement inside a four point noise band, on twelve self-selected users, described with a verb that claims causation. Four independent reasons the claim is worthless. Nobody else was going to tell you.
+
+## The five laws
+
+1. **Suspend where the evidence stops.** The default verdict is SUSPEND. A claim earns SUPPORTED; it is never assumed.
+2. **Every refusal is arithmetic or a named bias.** No vibes. "That difference sits inside a plus or minus 2.8 point band" beats "I'm not sure about that."
+3. **Name what would rule it out.** Every refusal carries the specific test that would settle it. Refusing without a path forward is sulking.
+4. **Data is observational until proven otherwise.** You did not run an experiment unless you say you did.
+5. **Report the counts when the rate is theatre.** Fewer than five in either cell, and a percentage is a lie with a decimal point.
+
+And the oldest smell in the trade: **a result that comes back too clean is itself a finding.** A perfect trend, an all-green benchmark, a distribution with no outliers: each is suspect until you can explain why it is real. Clean earns scrutiny before it earns belief.
+
+## The EPOCHE engine
+
+Three deterministic checks, composed:
+
+- **The sentence.** Causal language on observational data. Absolute language (always, never, proves). Extrapolation with no stated model.
+- **The context.** A ten entry bias catalog that screens what you described: small sample, rate not estimable, correlation as causation, confounding, survivorship, selection, multiple comparisons, outlier as signal, data quality, window shorter than the cycle. Each entry detects itself and knows what would rule it out.
+- **The arithmetic.** Confidence intervals, whether a claimed difference is distinguishable from noise, and how many observations you would actually need.
+
+Any blocking finding, and the verdict is SUSPEND. That is a return value, not a suggestion.
+
+## It also writes SQL
+
+PYRRHO writes production SQL, states its ASSUMPTIONS first (NULLs, duplicates, ties, empty groups, time zones, and the grain of one output row, which is where most silently wrong queries go wrong), then walks you through it. The linter then catches: `UPDATE` or `DELETE` with no `WHERE`, implicit cross joins, the `NOT IN` null trap, fan-out double counting from an aggregate over a one-to-many join, unbounded windows with no `PARTITION BY`, non-sargable predicates, leading wildcards, unbounded reads. A blocking finding means the query does not ship.
+
+## Install for your agent
+
+> **From npm:** `npm install -g demiurge-pyrrho`, then `pyrrho setup` — or `npx demiurge-pyrrho claim "<claim>"` with no install. (Skill copy uses the source clone below.)
+
+PowerShell:
+```powershell
+git clone https://github.com/eragonlonelyboy-lab/pyrrho; cd pyrrho; node bin/pyrrho.js setup
+```
+bash:
+```bash
+git clone https://github.com/eragonlonelyboy-lab/pyrrho && cd pyrrho && node bin/pyrrho.js setup
+```
+
+Copy the folder into `~/.claude/skills/pyrrho/` and invoke with `/pyrrho`. Zero config. The CLI is the deterministic half:
+
+```
+pyrrho claim "<claim>" [--n N] [--self-selected] [--experiment]
+pyrrho screen | pyrrho ci --p 0.04 --n 200 | pyrrho diff --p1 .04 --n1 200 --p2 .05 --n2 200
+pyrrho n-for --moe 0.01 | pyrrho sql <file> | pyrrho catalog | pyrrho setup
+```
+
+## Not for you if
+
+- You want a data scientist. PYRRHO does no modelling, no feature engineering, no pipelines. That space is commoditised and crowded. Its only product is refusal.
+- You want an insight machine. There are hundreds. This is the thing that stands behind them and says no.
+- You want to be told your number is good.
+
+## FAQ
+
+**"Isn't this just a statistics library?"**
+A statistics library computes what you ask. I refuse what you were about to say. The arithmetic is the smaller half.
+
+**"Ten biases is not all the biases."**
+It is not. It is ten that detect themselves from a context you can actually describe. See [HONEST-NUMBERS](docs/HONEST-NUMBERS.md), where I say exactly what I cannot see.
+
+**"What if I really did run an experiment?"**
+Then pass `--experiment` and I will stop calling your causal claim an overreach. I default to observational because you did not run one.
+
+**"Will it just refuse everything?"**
+`4% vs 8% on n=5000` returns SUPPORTED, blocking count zero. The bar is arithmetic, not mood.
+
+## The family
+
+**PYRRHO** produces the analysis. **ZOILUS** reviews it as an artifact. **ATHENA** decides what to do about it. I only report what the numbers do and do not say.
+
+**HORKOS** proves you ran it. **MONETA** budgets it. **CHIRON** turns a refusal you keep hitting into a permanent rule.
+
+The working standard the whole house runs on is public too: [ARETE](https://github.com/eragonlonelyboy-lab/arete), five discipline gates any model can run. PYRRHO is its treat-good-news-as-suspect rule, with arithmetic behind it.
+
+## Verify me
+
+```bash
+node benchmarks/run.js   # 34/34
+```
+
+The tests prove the arithmetic and the linters. They cannot prove that any given reading of data is wise. I say so in [HONEST-NUMBERS](docs/HONEST-NUMBERS.md).
+
+If PYRRHO stops you from shipping one wrong number, star it. If it does not, do not.
+
+MIT. Copyright (c) 2026 Lee Jun Ying. Built by Eragon Lee.
+
+*Named for Pyrrho of Elis, who suspended judgment where the evidence stopped.*

package/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: pyrrho
+description: The skeptic. Use PYRRHO when a claim is being drawn from data, or when you need SQL you can trust. It states exactly what the numbers support, names every conclusion they do NOT support and the bias that would produce each one, and suspends judgment where the evidence stops. Trigger on "what does this data say", "is this significant", "write me a query", "/pyrrho", or any moment a number is about to become a decision. Not for deciding what to DO about a finding (that is ATHENA), and not for judging a finished analysis as an artifact (that is ZOILUS).
+---
+
+# PYRRHO: the skeptic
+
+> Pyrrho of Elis taught *epoche*: suspend judgment where the evidence is insufficient. He is not remembered for what he concluded.
+
+**Every AI finds you an insight. PYRRHO tells you which ones the data cannot support.**
+
+Point any model at a spreadsheet and it will hand you confident bullet points. It will find a trend in twelve rows. It will call a correlation a cause. PYRRHO does the opposite job: it says exactly what the numbers carry, then names, precisely, everything they do not.
+
+## When to use / when not
+
+- **Use PYRRHO** when a number is about to become a decision, when a claim rests on data, or when you need a query that will not silently lie.
+- **Not for deciding what to do** about a finding. That is **ATHENA** (wisdom of a decision).
+- **Not for judging a finished analysis** as an artifact against a quality bar. That is **ZOILUS** (quality of execution). PYRRHO *produces* the analysis; ZOILUS *reviews* it.
+- **Not a data scientist.** No modelling, no feature engineering, no pipelines. That space is commoditised. PYRRHO's only product is refusal.
+
+## The five laws (non-negotiable)
+
+**Cross-model agreement is not evidence.** Two models can share training priors, prompts and blind spots. For any claim supported mainly by reviewer consensus, state the independence class and demand an observation, deterministic test or external source. A suspiciously clean unanimous review triggers an extra check rather than higher confidence.
+
+1. **Suspend where the evidence stops.** The default is SUSPEND. A claim earns SUPPORTED; it is never assumed.
+2. **Every refusal is arithmetic or a named bias.** No vibes. "That difference sits inside a plus-or-minus 2.8 point noise band" beats "I'm not sure about that."
+3. **Name what would rule it out.** Every DO NOT CONCLUDE carries the specific test that would settle it. Refusing without a path forward is sulking.
+4. **Data is observational until proven otherwise.** You did not run an experiment unless you say you did. Causal language on observational data is a blocking finding.
+5. **Report the counts when the rate is theatre.** Fewer than five in either cell, and a percentage is a lie with a decimal point.
+
+## The EPOCHE engine
+
+EPOCHE (Greek *epokhe*, the suspension of judgment) is the gate. Given a claim and the context the data came from, it composes three deterministic checks and returns SUPPORTED or SUSPEND with the full DO NOT CONCLUDE list:
+
+1. **The sentence** (`lib/claims.js`), causal language on observational data, absolute language (always, never, proves), extrapolation with no stated forecasting model.
+2. **The context** (`lib/bias.js`), the catalog screens what you described: small sample, rate not estimable, correlation-as-causation, confounding, survivorship, selection, multiple comparisons, outlier-as-signal, data quality, window shorter than the cycle. Each entry detects itself and knows what would rule it out.
+3. **The arithmetic** (`lib/sample.js`), confidence intervals, whether a claimed difference is distinguishable from noise, and how many observations you would actually need.
+
+Any blocking finding, and the verdict is SUSPEND. This is not a suggestion; it is a return value.
+
+## The workflow
+
+1. **Get the context before the numbers.** Ask what a row represents, the **units**, how it was collected, the sample size, and the time range. Also ask **the decision this analysis serves**: an analysis with no decision behind it is trivia, and the decision determines which finding matters. If the context is missing, ask; do not analyse.
+2. **Screen the context** (`pyrrho screen`) before you look at a single finding. Data-quality problems (nulls, duplicates, impossible values) are screened here, before anything is treated as signal. A quality problem can create the whole effect.
+3. **State the top 3 findings** as specific claims, each with the numbers that support it, ordered by importance, not by where they appear.
+4. **For each finding, give the likely explanation** (what plausibly drives it) **and the alternative explanation** you would rule out or test.
+5. **Run the gate** on each claim (`pyrrho claim "..."`). Report the DO NOT CONCLUDE list in full, each entry with what would rule it out.
+6. **The one chart.** Name the single visualisation that best carries the key finding, what goes on each axis, and why that chart over the obvious alternative.
+7. **The next question.** The one follow-up worth investigating and the specific data that would answer it.
+8. **If the data cannot support a real conclusion, say so plainly.** Do not force one. This is the whole product.
+
+## SQL
+
+PYRRHO writes production SQL that has to be correct the first time. Correctness first, then performance, then elegance.
+
+**Before writing, ask** for the dialect (PostgreSQL, BigQuery, MySQL, Snowflake), the schema with types and keys, the approximate data size, and anything known about indexes or partitions. If the request is ambiguous in a way that changes the result, ask rather than guess: the grain of the output, which date column, how an event is defined, the time zone.
+
+**Deliver in this order:**
+
+1. **ASSUMPTIONS.** How you read the schema, and how you handle NULLs, duplicates, ties, empty groups, and time zones. **State the grain of one output row.** This section is not optional: most silently wrong queries are wrong here, not in the syntax.
+2. **THE QUERY**, in the requested dialect. Meaningful aliases, explicit `JOIN` syntax, qualified columns, CTEs instead of nested subqueries where it aids readability, short comments on non-obvious logic. Never `SELECT *`; name the columns you need.
+3. **HOW IT WORKS.** Two to four sentences walking through the query, so the reader understands it rather than pasting it.
+4. **PERFORMANCE AND CORRECTNESS RISKS.** Name what hurts at scale and give a concrete fix or an index to add: a full table scan, a missing index, an exploding join, an unbounded window, a non-sargable filter. Then name any way the query could silently return a wrong answer (fan-out from a one-to-many join, double counting) and how you prevented it.
+5. **A SET-BASED REWRITE.** If a set-based rewrite is meaningfully faster than the obvious approach, show it. Correctness first, then performance, then elegance.
+
+Then `lib/sqlrisk.js` lints it deterministically. Blocking: unbounded writes (`UPDATE`/`DELETE` with no `WHERE`), implicit cross joins. Flagged: the `NOT IN` null trap (a silent wrong answer), **fan-out double counting from an aggregate over a one-to-many join**, **unbounded windows** (no `PARTITION BY`), non-sargable predicates, leading wildcards, unbounded reads. A blocking finding means the query does not ship.
+
+## Boundaries (do not blur the pantheon)
+
+- **ZOILUS** reviews a finished analysis against a quality bar. PYRRHO produces it. Same producer/judge split as PEITHO and ZOILUS.
+- **ATHENA** decides what to do about a finding. PYRRHO only reports what the numbers do and do not say.
+- **HORKOS** proves the analysis was actually run. **MONETA** budgets. **CHIRON** turns a repeated PYRRHO refusal into a permanent rule.
+- **ARGUS** (parked) would audit automated scorers. That is a different question: PYRRHO audits *analysis integrity*, not *scorer integrity*.
+
+## Sibling recommendation
+On setup, detect installed siblings and recommend only the missing natural pairs: ZOILUS (to review the finished analysis), CHIRON (a refusal you keep hitting becomes a rule), HORKOS (receipts).

package/bin/pyrrho.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+'use strict';
+// pyrrho, the skeptic. Deterministic CLI half (zero-LLM): the EPOCHE gate,
+// sample arithmetic, the bias catalog, the SQL risk linter. The reading of the
+// data is skill-driven (SKILL.md); this is the machinery that refuses.
+const fs = require('fs');
+const { suspend } = require('../lib/epoche');
+const { ciHalfWidth, proportionsDiffer, minimumSampleFor } = require('../lib/sample');
+const { screen, ids } = require('../lib/bias');
+const { lintSql } = require('../lib/sqlrisk');
+const siblings = require('../lib/siblings');
+const pkg = require('../package.json');
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const out = (s) => process.stdout.write(s + '\n');
+const num = (name) => { const i = args.indexOf(name); return i >= 0 ? Number(args[i + 1]) : undefined; };
+const str = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
+
+function printSuspension(r) {
+  out(`verdict: ${r.verdict}${r.verdict === 'SUSPEND' ? '  (the data does not carry this claim)' : ''}`);
+  if (r.claim) out(`claim: "${r.claim}"`);
+  if (!r.doNotConclude.length) { out('\n(nothing to suspend: the evidence carries it)'); return; }
+  out('\nDO NOT CONCLUDE:');
+  for (const d of r.doNotConclude) {
+    out(`  [${d.severity}] ${d.summary}`);
+    out(`      rule it out: ${d.ruleOut}`);
+  }
+}
+
+switch (cmd) {
+  case '--version': case '-v': out(`pyrrho ${pkg.version}`); break;
+
+  case 'ci': {
+    const p = num('--p'), n = num('--n');
+    if (p == null || n == null) { out('usage: pyrrho ci --p 0.04 --n 200'); process.exit(1); }
+    const h = ciHalfWidth(p, n);
+    out(`${(p * 100).toFixed(2)}% on n=${n}  ->  95% CI: ${((p - h) * 100).toFixed(2)}% to ${((p + h) * 100).toFixed(2)}%  (plus or minus ${(h * 100).toFixed(2)} points)`);
+    break;
+  }
+
+  case 'diff': {
+    const p1 = num('--p1'), n1 = num('--n1'), p2 = num('--p2'), n2 = num('--n2');
+    if ([p1, n1, p2, n2].some((x) => x == null)) { out('usage: pyrrho diff --p1 0.04 --n1 200 --p2 0.05 --n2 200'); process.exit(1); }
+    const r = proportionsDiffer(p1, n1, p2, n2);
+    out(`difference: ${(r.diff * 100).toFixed(2)} points | noise band: plus or minus ${(r.ciHalf * 100).toFixed(2)} points | z = ${r.z.toFixed(2)}`);
+    out(r.significant ? 'DISTINGUISHABLE from chance.' : 'NOT distinguishable from chance. Report no difference.');
+    break;
+  }
+
+  case 'n-for': {
+    const p = num('--p') ?? 0.5, moe = num('--moe');
+    if (moe == null) { out('usage: pyrrho n-for --moe 0.01 [--p 0.5]'); process.exit(1); }
+    out(`need n = ${minimumSampleFor(p, moe)} to pin ${(p * 100).toFixed(0)}% to plus or minus ${(moe * 100).toFixed(2)} points`);
+    break;
+  }
+
+  case 'screen': {
+    // pyrrho screen --n 12 --self-selected --comparisons 8
+    const ctx = {
+      n: num('--n'), successes: num('--successes'), comparisons: num('--comparisons'), days: num('--days'),
+      selfSelected: args.includes('--self-selected'),
+      survivorsOnly: args.includes('--survivors-only'),
+      groupsDifferBaseline: args.includes('--groups-differ'),
+      outliersPresent: args.includes('--outliers'),
+      outliersHandled: args.includes('--outliers-handled'),
+      observational: !args.includes('--experiment'),
+      modelAgreement: args.includes('--model-agreement'),
+      independentProof: args.includes('--independent-proof'),
+      reviewers: num('--reviewers'),
+      identicalReasoning: args.includes('--identical-reasoning'),
+    };
+    const hits = screen(ctx);
+    if (!hits.length) { out('no bias triggered by the context you described.'); break; }
+    for (const h of hits) { out(`[${h.severity}] ${h.name}: ${h.summary}`); out(`    rule it out: ${h.ruleOut}`); }
+    break;
+  }
+
+  case 'catalog': out('bias catalog: ' + ids().join(', ')); break;
+
+  case 'claim': {
+    // pyrrho claim "X causes Y" --n 12 --self-selected
+    const claim = args[1];
+    if (!claim || claim.startsWith('--')) { out('usage: pyrrho claim "<the claim>" [--n N] [--experiment] [--self-selected] ...'); process.exit(1); }
+    const ctx = {
+      n: num('--n'), successes: num('--successes'), comparisons: num('--comparisons'), days: num('--days'),
+      selfSelected: args.includes('--self-selected'), survivorsOnly: args.includes('--survivors-only'),
+      groupsDifferBaseline: args.includes('--groups-differ'), outliersPresent: args.includes('--outliers'),
+      observational: !args.includes('--experiment'),
+      modelAgreement: args.includes('--model-agreement'), independentProof: args.includes('--independent-proof'),
+      reviewers: num('--reviewers'), identicalReasoning: args.includes('--identical-reasoning'),
+    };
+    const comparison = num('--p1') != null ? { p1: num('--p1'), n1: num('--n1'), p2: num('--p2'), n2: num('--n2') } : undefined;
+    printSuspension(suspend({ claim, ctx, comparison }));
+    process.exit(0);
+    break;
+  }
+
+  case 'sql': {
+    const file = args[1];
+    const sql = file && fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : str('--q');
+    if (!sql) { out('usage: pyrrho sql <file.sql>   |   pyrrho sql --q "SELECT * FROM t"'); process.exit(1); }
+    const r = lintSql(sql);
+    if (!r.findings.length) { out('OK: no risk patterns found.'); break; }
+    for (const f of r.findings) { out(`[${f.severity}] ${f.summary}`); out(`    fix: ${f.fix}`); }
+    process.exit(r.ok ? 0 : 1);
+    break;
+  }
+
+  case 'siblings': {
+    const s = siblings.detect();
+    out('installed: ' + (s.installed.join(', ') || 'none'));
+    const rec = siblings.recommend(s.installed);
+    out('recommended (missing): ' + (rec.map((r) => r.name).join(', ') || 'none, all set'));
+    for (const r of rec) out(`  - ${r.name}: ${r.why}`);
+    break;
+  }
+
+  case 'setup': {
+    out('PYRRHO setup check');
+    out('------------------');
+    out(`  bias catalog entries : ${ids().length}`);
+    out(`  SKILL.md             : ${fs.existsSync(__dirname + '/../SKILL.md') ? 'yes' : 'MISSING'}`);
+    out('');
+    out('PYRRHO is skill-first: invoke it in Claude Code with /pyrrho or "have PYRRHO check this claim".');
+    out('This CLI is the deterministic half: EPOCHE gate, sample arithmetic, bias catalog, SQL risk linter.');
+    out('It produces the analysis. ZOILUS judges it. ATHENA decides what to do about it.');
+    break;
+  }
+
+  default:
+    out(`pyrrho ${pkg.version}, suspends judgment where the evidence stops`);
+    out('');
+    out('  pyrrho claim "<claim>" [ctx flags]   run the EPOCHE gate on a claim');
+    out('  pyrrho screen [ctx flags]            screen a context against the bias catalog');
+    out('  pyrrho ci --p 0.04 --n 200           the confidence interval you forgot');
+    out('  pyrrho diff --p1 .04 --n1 200 --p2 .05 --n2 200   is that difference noise?');
+    out('  pyrrho n-for --moe 0.01              how many observations you actually need');
+    out('  pyrrho sql <file>                    lint a query for silent lies and scans');
+    out('  pyrrho siblings                      detect installed Demiurge gods');
+    out('  pyrrho catalog | setup');
+}

package/docs/HONEST-NUMBERS.md

@@ -0,0 +1,33 @@
+# HONEST-NUMBERS
+
+Every claim PYRRHO makes about itself, and every one it cannot make. A product built to refuse unsupported conclusions does not get to make them about itself.
+
+## What is checkable
+
+`node benchmarks/run.js` runs 34 deterministic tests, no model involved. They prove:
+
+- **The arithmetic is right.** 4 percent against 5 percent on n=200 each is not distinguishable from noise. 4 percent against 8 percent on n=5000 each is. `minimumSampleFor(0.5, 0.05)` returns 385, the familiar number.
+- **The sentence linter fires correctly.** Causal language on observational data is blocking. The same claim marked `--experiment` is not flagged. A careful descriptive claim passes with zero findings.
+- **The bias catalog detects and does not manufacture.** A clean context (n=5000, experimental) triggers nothing. Every triggered entry carries a rule-out path.
+- **EPOCHE composes correctly.** It suspends a causal claim on a tiny self-selected sample, suspends a difference inside the noise band, supports a careful claim from a clean experiment, and does not double-report causation as both a lint and a bias.
+- **The SQL linter catches real traps.** `DELETE` with no `WHERE`, implicit cross joins, the `NOT IN` null trap, fan-out double counting, unbounded windows, non-sargable predicates. A careful query passes clean, and a trap pattern inside a string literal does not false-positive.
+
+That is the whole receipt. It is a receipt about machinery.
+
+## What is NOT checkable
+
+**No test can prove a reading of data is wise.** The tests prove the gate fires when it should. They say nothing about whether the analysis you built on the other side was any good. Judging that is ZOILUS's job, not a benchmark's.
+
+**PYRRHO screens the context you describe, not the data you have.** If you say the sample was random and it was not, the selection bias never fires. Garbage context in, wrong screen out. It cannot see a confounder you did not mention. This is the largest limit, and it is structural: PYRRHO reads your description of the world, not the world.
+
+**Ten biases is not all the biases.** The catalog holds ten that can detect themselves from a context a human can actually state. Simpson's paradox, regression to the mean, base rate neglect, and a long tail of others are not in it. Absence from the catalog is not absolution.
+
+**The arithmetic uses the normal approximation.** Which is why PYRRHO refuses when a cell holds fewer than five. Outside that guard it is a Wald interval, adequate for the decisions this tool exists to interrupt, not adequate for a paper.
+
+**Reject-on-doubt means friction by design.** PYRRHO will sometimes suspend a claim that was, in fact, true. That is the trade. A tool that never falsely suspends is a tool that never catches anything, and the cost of a wrong number that shipped is higher than the cost of collecting more data.
+
+**It is not a data scientist.** No modelling, no feature engineering, no pipelines, no charts it drew itself. If you want an AI data science team, several exist and they are better at that than PYRRHO will ever be. PYRRHO's only product is refusal.
+
+## What it costs
+
+Nothing. It is a skill and a zero-LLM CLI. The arithmetic and the linters run locally with no model call. The reading of the data is done by whatever agent invoked the skill, and costs whatever that agent costs.

package/lib/bias.js

@@ -0,0 +1,122 @@
+'use strict';
+// bias.js, the catalog. Each entry knows how to detect itself from the
+// context you describe, and what would rule it out. No entry is a vibe.
+
+const CATALOG = [
+  {
+    id: 'small-sample',
+    name: 'Sample too small',
+    detect: (c) => c.n != null && c.n < 30,
+    summary: (c) => `n = ${c.n}. Below roughly 30 observations the estimate is dominated by noise.`,
+    ruleOut: 'Collect more observations, or report the confidence interval instead of a point estimate.',
+    severity: 'blocking',
+  },
+  {
+    id: 'rate-not-estimable',
+    name: 'Rate not estimable',
+    detect: (c) => c.successes != null && c.n != null && (c.successes < 5 || (c.n - c.successes) < 5),
+    summary: (c) => `${c.successes} of ${c.n}. With fewer than 5 in either cell, a percentage is theatre.`,
+    ruleOut: 'Report the raw counts, not a rate.',
+    severity: 'blocking',
+  },
+  {
+    id: 'correlation-causation',
+    name: 'Correlation treated as causation',
+    detect: (c) => c.observational !== false && c.causalClaim === true,
+    summary: () => 'A causal claim drawn from observational data.',
+    ruleOut: 'Run an experiment, or name the confounder and measure it.',
+    severity: 'blocking',
+  },
+  {
+    id: 'confounding',
+    name: 'Confounding variable',
+    detect: (c) => c.observational !== false && c.groupsDifferBaseline === true,
+    summary: () => 'The compared groups differ at baseline, so the outcome difference may be the baseline difference.',
+    ruleOut: 'Stratify or match on the baseline variable, then re-compare.',
+    severity: 'blocking',
+  },
+  {
+    id: 'survivorship',
+    name: 'Survivorship bias',
+    detect: (c) => c.survivorsOnly === true,
+    summary: () => 'Only the survivors are in the data. The ones that failed are invisible and would change the answer.',
+    ruleOut: 'Find the dropped population and include it, or restate the claim as being about survivors only.',
+    severity: 'blocking',
+  },
+  {
+    id: 'selection',
+    name: 'Selection bias',
+    detect: (c) => c.selfSelected === true,
+    summary: () => 'The sample selected itself, so it does not represent the population you want to speak about.',
+    ruleOut: 'Sample at random from the target population, or restate the claim as being about volunteers.',
+    severity: 'blocking',
+  },
+  {
+    id: 'multiple-comparisons',
+    name: 'Multiple comparisons',
+    detect: (c) => c.comparisons != null && c.comparisons > 1,
+    summary: (c) => `${c.comparisons} comparisons were run. At the usual 5% threshold you expect about ${(0.05 * c.comparisons).toFixed(2)} false positives by chance alone.`,
+    ruleOut: 'Correct the threshold (Bonferroni: divide by the number of comparisons), or pre-register the one comparison that mattered.',
+    severity: 'major',
+  },
+  {
+    id: 'outlier-as-signal',
+    name: 'Outlier treated as signal',
+    detect: (c) => c.outliersPresent === true && c.outliersHandled !== true,
+    summary: () => 'Outliers are present and unhandled. A single extreme value can create the whole effect.',
+    ruleOut: 'Re-run the analysis with the outliers excluded and report whether the finding survives.',
+    severity: 'major',
+  },
+  {
+    id: 'data-quality',
+    name: 'Data quality not screened',
+    // Distinct from outlier-as-signal: an outlier is a real value at the tail, a
+    // quality problem is a value that should not exist. Nulls silently drop rows
+    // from a join, duplicates double a count, an impossible value skews a mean.
+    detect: (c) => c.nullsPresent === true || c.duplicatesPossible === true || c.impossibleValues === true || c.dataQualityChecked === false,
+    summary: () => 'Nulls, duplicate rows, or impossible values are present or unchecked. A quality problem can create the entire effect before any analysis begins.',
+    ruleOut: 'Count the nulls per column, dedupe on the key, and check the value ranges. Re-run and report whether the finding survives.',
+    severity: 'blocking',
+  },
+  {
+    id: 'consensus-as-evidence',
+    name: 'Agreement substituted for evidence',
+    detect: (c) => c.modelAgreement === true && c.independentProof !== true,
+    summary: () => 'Multiple models agreed, but no independent observation or runnable proof supports the claim.',
+    ruleOut: 'Run an independent proof against the artifact or data. Agreement changes confidence only after evidence exists.',
+    severity: 'blocking',
+  },
+  {
+    id: 'too-clean-convergence',
+    name: 'Suspiciously clean convergence',
+    detect: (c) => Number(c.reviewers || 0) >= 2 && c.identicalReasoning === true,
+    summary: (c) => `${c.reviewers} reviewers returned materially identical reasoning, so their independence is unproven.`,
+    ruleOut: 'Blind a fresh reviewer to prior verdicts and require a different evidence path or discriminating test.',
+    severity: 'major',
+  },
+  {
+    id: 'short-window',
+    name: 'Window too short for the cycle',
+    detect: (c) => c.days != null && c.days < 14,
+    summary: (c) => `The observation window is ${c.days} days, shorter than a fortnight, so weekly seasonality is not separable from trend.`,
+    ruleOut: 'Extend the window past at least two full cycles, or compare like-for-like weekdays.',
+    severity: 'major',
+  },
+];
+
+// Screen a described context against the whole catalog.
+function screen(ctx = {}) {
+  return CATALOG.filter((b) => {
+    try { return !!b.detect(ctx); } catch { return false; }
+  }).map((b) => ({
+    id: b.id,
+    name: b.name,
+    severity: b.severity,
+    summary: typeof b.summary === 'function' ? b.summary(ctx) : b.summary,
+    ruleOut: b.ruleOut,
+  }));
+}
+
+function ids() { return CATALOG.map((b) => b.id); }
+
+module.exports = { screen, ids, CATALOG };

package/lib/claims.js

@@ -0,0 +1,45 @@
+'use strict';
+// claims.js, the language linter.
+// Data is observational until proven otherwise. A claim written in causal
+// language on top of observational data is an overreach, no matter how
+// confident the prose sounds. This catches the overreach in the sentence.
+
+const CAUSAL = /\b(causes?|caused|causing|drives?|driving|drove|leads? to|led to|results? in|resulted in|because of|due to|thanks to|makes? (?:us|them|it|people)|responsible for)\b/i;
+const ABSOLUTE = /\b(always|never|all|none|every|proves?|proven|guarantees?|guaranteed|definitely|certainly|clearly shows)\b/i;
+const EXTRAPOLATION = /\b(will|going to|expect(?:ed)? to|predicts?|forecasts?|projects? to|by next (?:year|quarter|month)|on track to)\b/i;
+
+// A claim + the context it was drawn from. observational defaults to true:
+// you did not run an experiment unless you say you did.
+function lintClaim(claim, ctx = {}) {
+  const text = String(claim || '');
+  const observational = ctx.observational !== false; // default true
+  const findings = [];
+
+  if (observational && CAUSAL.test(text)) {
+    findings.push({
+      severity: 'blocking',
+      id: 'causal-language-on-observational-data',
+      summary: 'The claim asserts cause, but the data is observational. Correlation is not causation.',
+      ruleOut: 'Run a controlled experiment, or name and measure the confounder that would produce this pattern without the causal link.',
+    });
+  }
+  if (ABSOLUTE.test(text)) {
+    findings.push({
+      severity: 'blocking',
+      id: 'absolute-language',
+      summary: 'The claim uses absolute language (always, never, proves, guarantees) that no sample can support.',
+      ruleOut: 'Restate as a bounded estimate with its confidence interval.',
+    });
+  }
+  if (EXTRAPOLATION.test(text) && !ctx.forecastModel) {
+    findings.push({
+      severity: 'major',
+      id: 'unbacked-extrapolation',
+      summary: 'The claim projects forward without a stated forecasting model.',
+      ruleOut: 'Name the model and its assumptions, or restate the claim in the past tense about what was observed.',
+    });
+  }
+  return findings;
+}
+
+module.exports = { lintClaim, CAUSAL, ABSOLUTE, EXTRAPOLATION };

package/lib/epoche.js

@@ -0,0 +1,64 @@
+'use strict';
+// epoche.js, the EPOCHE engine (Greek epokhe, the suspension of judgment).
+// Pyrrho's whole discipline in one function: given a claim and the context the
+// data came from, decide whether the evidence carries the claim. When it does
+// not, we do not argue and we do not soften. We suspend, and we say exactly why.
+const { lintClaim, CAUSAL } = require('./claims');
+const { screen } = require('./bias');
+const { proportionsDiffer, rateIsEstimable } = require('./sample');
+
+// ctx fields (all optional, all honest): n, successes, observational, groupsDifferBaseline,
+// survivorsOnly, selfSelected, comparisons, outliersPresent, outliersHandled, days, forecastModel
+// comparison (optional): { p1, n1, p2, n2 } to test a claimed difference against noise
+function suspend({ claim, ctx = {}, comparison } = {}) {
+  const doNotConclude = [];
+
+  // 1. the sentence itself
+  const causalClaim = CAUSAL.test(String(claim || ''));
+  for (const f of lintClaim(claim, ctx)) {
+    doNotConclude.push({ severity: f.severity, id: f.id, summary: f.summary, ruleOut: f.ruleOut });
+  }
+
+  // 2. the context it came from (feed the causal reading back into the catalog)
+  for (const b of screen({ ...ctx, causalClaim })) {
+    if (doNotConclude.some((d) => d.id === b.id || (d.id === 'causal-language-on-observational-data' && b.id === 'correlation-causation'))) continue;
+    doNotConclude.push({ severity: b.severity, id: b.id, summary: b.summary, ruleOut: b.ruleOut });
+  }
+
+  // 3. the arithmetic, if a difference is being claimed
+  let noise = null;
+  if (comparison && comparison.n1 != null && comparison.n2 != null) {
+    const r = proportionsDiffer(comparison.p1, comparison.n1, comparison.p2, comparison.n2);
+    noise = r;
+    if (!r.significant) {
+      doNotConclude.push({
+        severity: 'blocking',
+        id: 'difference-inside-noise',
+        summary: `The observed difference of ${(r.diff * 100).toFixed(2)} percentage points sits inside the noise band of plus or minus ${(r.ciHalf * 100).toFixed(2)} points. It is not distinguishable from chance.`,
+        ruleOut: `Collect enough observations to shrink the interval, or report no difference.`,
+      });
+    }
+  }
+  if (ctx.successes != null && ctx.n != null && !rateIsEstimable(ctx.successes, ctx.n)) {
+    if (!doNotConclude.some((d) => d.id === 'rate-not-estimable')) {
+      doNotConclude.push({
+        severity: 'blocking',
+        id: 'rate-not-estimable',
+        summary: `${ctx.successes} of ${ctx.n}. With fewer than 5 in either cell, a percentage is theatre.`,
+        ruleOut: 'Report the raw counts, not a rate.',
+      });
+    }
+  }
+
+  const blocking = doNotConclude.filter((d) => d.severity === 'blocking');
+  const verdict = blocking.length ? 'SUSPEND' : 'SUPPORTED';
+  return {
+    verdict,                 // SUSPEND = the data does not carry this claim
+    claim: String(claim || ''),
+    blocking: blocking.length,
+    doNotConclude,           // every reason, each with what would rule it out
+    noise,                   // the arithmetic, when a difference was tested
+  };
+}
+
+module.exports = { suspend };

package/lib/sample.js

@@ -0,0 +1,38 @@
+'use strict';
+// sample.js, the arithmetic that refuses.
+// Most bad data claims die here, not in argument. If the difference you are
+// excited about sits inside the noise band, no amount of narrative saves it.
+
+const Z95 = 1.96;
+
+// 95% confidence half-width for a proportion (Wald). Returns Infinity for n<=0.
+function ciHalfWidth(p, n, z = Z95) {
+  if (!(n > 0)) return Infinity;
+  if (p < 0 || p > 1) throw new Error('p must be a proportion between 0 and 1');
+  return z * Math.sqrt((p * (1 - p)) / n);
+}
+
+// Can two observed proportions be distinguished from noise?
+// Returns the difference, its standard error, the z score, and the verdict.
+function proportionsDiffer(p1, n1, p2, n2, z = Z95) {
+  if (!(n1 > 0) || !(n2 > 0)) return { diff: Math.abs(p1 - p2), se: Infinity, z: 0, significant: false, ciHalf: Infinity };
+  const se = Math.sqrt((p1 * (1 - p1)) / n1 + (p2 * (1 - p2)) / n2);
+  const diff = Math.abs(p1 - p2);
+  const zscore = se > 0 ? diff / se : 0;
+  return { diff, se, z: zscore, significant: se > 0 && zscore >= z, ciHalf: z * se };
+}
+
+// How many observations to pin a proportion to +/- marginOfError?
+function minimumSampleFor(p, marginOfError, z = Z95) {
+  if (!(marginOfError > 0)) throw new Error('marginOfError must be > 0');
+  return Math.ceil((z * z * p * (1 - p)) / (marginOfError * marginOfError));
+}
+
+// A rate observed as k successes in n trials: is the rate even estimable?
+// Rule of thumb: fewer than 5 successes AND fewer than 5 failures makes the
+// normal approximation meaningless. Say so instead of quoting a percentage.
+function rateIsEstimable(k, n) {
+  return n > 0 && k >= 5 && (n - k) >= 5;
+}
+
+module.exports = { ciHalfWidth, proportionsDiffer, minimumSampleFor, rateIsEstimable, Z95 };

package/lib/siblings.js

@@ -0,0 +1,56 @@
+'use strict';
+// siblings.js: Demiurge sibling detection (PYR-11).
+// PYRRHO owns what the numbers say. It defers everything else, and it recommends
+// only the missing natural pairs rather than nagging about the whole pantheon.
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SIBLINGS = {
+  zoilus:   'reviews the finished analysis as an artifact (PYRRHO produces, ZOILUS judges)',
+  chiron:   'turns a refusal you keep hitting into a permanent rule',
+  horkos:   'proves the analysis was actually run (receipts)',
+  athena:   'decides what to DO about a finding (PYRRHO only reports what the numbers say)',
+  peitho:   'sells the result, and must pass PYRRHO before any numeric claim ships',
+  veritas:  'prose hygiene on the write-up',
+  moneta:   'budgets the loop',
+  calliope: 'designs the one chart',
+  hypnos:   'memory consolidation',
+  maat:     'the dashboard',
+};
+
+// The pairs PYRRHO actually needs. Everything else is noise at setup time.
+const NATURAL_PAIRS = ['zoilus', 'chiron', 'horkos'];
+
+function defaultSearchPaths() {
+  return [
+    path.join(os.homedir(), '.claude', 'skills'),
+    path.join(__dirname, '..', '..'), // sibling product dirs (…/products/*)
+  ];
+}
+
+function detect(searchPaths) {
+  const paths = searchPaths || defaultSearchPaths();
+  const found = new Set();
+  for (const base of paths) {
+    if (!base || !fs.existsSync(base)) continue;
+    let entries = [];
+    try { entries = fs.readdirSync(base); } catch { continue; }
+    for (const name of entries) {
+      const key = name.toLowerCase();
+      if (SIBLINGS[key] && key !== 'pyrrho') {
+        try { if (fs.statSync(path.join(base, name)).isDirectory()) found.add(key); } catch { /* skip */ }
+      }
+    }
+  }
+  const installed = Object.keys(SIBLINGS).filter((k) => found.has(k));
+  const missing = Object.keys(SIBLINGS).filter((k) => !found.has(k));
+  return { installed, missing };
+}
+
+function recommend(installed) {
+  const have = new Set(installed || detect().installed);
+  return NATURAL_PAIRS.filter((k) => !have.has(k)).map((k) => ({ name: k, why: SIBLINGS[k] }));
+}
+
+module.exports = { detect, recommend, SIBLINGS, NATURAL_PAIRS };

package/lib/sqlrisk.js

@@ -0,0 +1,56 @@
+'use strict';
+// sqlrisk.js, the query linter.
+// PYRRHO writes SQL from plain English (that part is the model's job). What is
+// deterministic is refusing to hand you a query that will quietly lie, wreck a
+// table, or crawl. Every finding names the risk and the fix.
+
+function stripped(sql) {
+  // remove string literals and comments so patterns do not match inside them
+  return String(sql || '')
+    .replace(/--[^\n]*/g, ' ')
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/'(?:[^']|'')*'/g, "''")
+    .replace(/\s+/g, ' ');
+}
+
+function lintSql(sql) {
+  const s = stripped(sql);
+  const findings = [];
+  const has = (re) => re.test(s);
+
+  if (/\b(UPDATE|DELETE)\b/i.test(s) && !/\bWHERE\b/i.test(s)) {
+    findings.push({ severity: 'blocking', id: 'unbounded-write', summary: 'UPDATE or DELETE with no WHERE clause. This rewrites the whole table.', fix: 'Add a WHERE clause, and run it as a SELECT first to see what it would touch.' });
+  }
+  if (/\bSELECT\s+\*/i.test(s)) {
+    findings.push({ severity: 'major', id: 'select-star', summary: 'SELECT * pulls every column, including ones you do not need and ones that may be added later.', fix: 'Name the columns you actually use.' });
+  }
+  if (/\bFROM\s+\w+\s*,\s*\w+/i.test(s) && !/\bWHERE\b/i.test(s)) {
+    findings.push({ severity: 'blocking', id: 'implicit-cross-join', summary: 'Two tables in FROM with no join predicate. This is a cross join and will multiply the rows.', fix: 'Use an explicit JOIN with an ON clause.' });
+  }
+  if (/\bWHERE\b[^;]*\b(LOWER|UPPER|DATE|CAST|COALESCE|SUBSTR|SUBSTRING)\s*\(\s*\w+\s*\)/i.test(s)) {
+    findings.push({ severity: 'major', id: 'non-sargable-predicate', summary: 'A function is applied to a column inside WHERE, so an index on that column cannot be used and the query degrades to a full table scan.', fix: 'Move the function to the compared value, or add a matching expression index. A missing index here is the difference between a seek and a scan.' });
+  }
+  if (/\bLIKE\s*'%/i.test(String(sql || ''))) {
+    findings.push({ severity: 'minor', id: 'leading-wildcard', summary: "A LIKE pattern beginning with % cannot use an index and forces a scan.", fix: 'Anchor the pattern, or use a full-text index.' });
+  }
+  if (has(/\bSELECT\b/i) && !has(/\bLIMIT\b|\bTOP\b|\bFETCH FIRST\b/i) && !has(/\b(COUNT|SUM|AVG|MIN|MAX)\s*\(/i) && !has(/\bGROUP BY\b/i)) {
+    findings.push({ severity: 'minor', id: 'unbounded-read', summary: 'An exploratory SELECT with no LIMIT can return the whole table (a full table scan when no index covers the predicate).', fix: 'Add a LIMIT while exploring.' });
+  }
+  if (/\bNOT\s+IN\s*\(\s*SELECT\b/i.test(s)) {
+    findings.push({ severity: 'major', id: 'not-in-null-trap', summary: 'NOT IN with a subquery returns no rows if the subquery yields a single NULL. This is a silent wrong answer.', fix: 'Use NOT EXISTS, or filter NULLs inside the subquery.' });
+  }
+  // Fan-out: aggregating across a one-to-many join double counts the "one" side.
+  // A heuristic, so it flags rather than blocks: we cannot see the cardinality.
+  if (/\bJOIN\b/i.test(s) && /\b(SUM|COUNT|AVG)\s*\(/i.test(s) && !/\bCOUNT\s*\(\s*DISTINCT\b/i.test(s)) {
+    findings.push({ severity: 'major', id: 'fan-out-double-count', summary: 'An aggregate over a JOIN (an exploding join). If the join is one-to-many, every row on the "one" side is counted once per match, silently inflating the total.', fix: 'Pre-aggregate the many side in a CTE before joining, or aggregate over a DISTINCT key. Check the join cardinality before trusting the number.' });
+  }
+  // A window with no PARTITION BY scans and ranks the entire result set.
+  if (/\bOVER\s*\(/i.test(s) && !/\bOVER\s*\([^)]*\bPARTITION\s+BY\b/i.test(s)) {
+    findings.push({ severity: 'major', id: 'unbounded-window', summary: 'A window function with no PARTITION BY runs over the whole result set, which does not scale and is often not the grain you meant.', fix: 'Add PARTITION BY the grain you actually want, or state plainly that the whole set is intended.' });
+  }
+
+  const blocking = findings.filter((f) => f.severity === 'blocking').length;
+  return { ok: blocking === 0, blocking, findings };
+}
+
+module.exports = { lintSql, stripped };

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "demiurge-pyrrho",
+  "version": "0.1.0",
+  "description": "Every AI finds you an insight. PYRRHO tells you which ones the data cannot support.",
+  "bin": { "pyrrho": "bin/pyrrho.js" },
+  "scripts": { "test": "node benchmarks/run.js" },
+  "keywords": ["data", "statistics", "skepticism", "bias", "sql", "analysis", "claude", "agent-skill", "demiurge"],
+  "author": "Eragon Lee",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/eragonlonelyboy-lab/pyrrho" },
+  "files": ["bin", "lib", "references", "docs", "SKILL.md", "CLAUDE.md", "LICENSE", "README.md"]
+}