git:20261024.7a46275 to git:20261026.5892847

3 added, 0 removed. Audit A to A.

# HypGraph

> The evidence layer for AI research agents: a research record that can't flatter itself. Typed nodes (question, hypothesis, experiment, run, result, claim, source, review, decision) and typed links in one append-only, SHA-256 hash-chained SQLite file. Standing (review, risk, independent support, evidence strength) is derived on every read and never asserted. Claims are checked on write. Slogan: "Don't believe the hype. Test the hyp."

Use HypGraph whenever you investigate a question with evidence and need to say what is established. Rules the record enforces:

- Every number in a claim must be bound to a result field (`measurements`), the scope, or a declared constant.

- "never / always / eliminates / 100%" need a count with k = 0 or k = n, a 95% bound under 5% (0 of 50 → could still be 5.8%), and n stated in the claim. Check with `hypgraph bound K N --exposure X` or the MCP tool `bound`.

- "beats / outperforms" need both sides measured; "significantly" needs a test (the record tests two bound counts itself); "causes" needs an experiment that intervened. Numbers computed from bound counts pass; invented ones are refused.

- Before handing over a write-up, run `hypgraph check summary.md` (MCP `check_report`): it flags numbers no result contains, claims called settled that the record has as unchecked/contested/withdrawn, unknown codes, and never/no effect/significantly with nothing cited. Refusals are logged per author (`hypgraph refusals`, MCP `refusal_log`).

- Every refusal ends in a code like [ABSOLUTE_UNDERPOWERED] and gives the honest sentence. Withdrawing or contesting a node reports its blast radius: what now rests on something that fell.

- `kind: exclusion` needs a search shown to recover a planted answer (`power: demonstrated`); otherwise use `inconclusive`.

- `tests` links need `data.expected`, written before running. `supports` / `challenges` need a `why`.

- Only named reviewers set standing, never on their own work. Revising a node makes its reviews stale.

- Report standing as the record states it. When a write is refused, fix what the message says.

Connect: `pip install "hypgraph[mcp]"` then `claude mcp add hypgraph -- hypgraph --db study.hypgraph --as <you> mcp`. Skill: `pip install hypgraph && hypgraph skill --install`. CLI: `hypgraph --json <command>`.

## Docs

- [Agent skill](https://hypgraph.com/SKILL.md): the method, refusals and their fixes (Agent Skills format)

- [For agents](https://hypgraph.com/agents.md): MCP setup, tools, reading standing

- [Record format](https://hypgraph.com/spec/): nodes, edges, events, hash chain, bundles, derivation rules

- [The arithmetic of never](https://hypgraph.com/never/): what 0 of n really supports, and what it costs at scale

- [Schema](https://hypgraph.com/schema/hypgraph-1.json): node types, fields, relations, verdicts as JSON

## Examples

- [Broad Street, 1854](https://hypgraph.com/data/broad-street.bundle.json): a complete verifiable bundle (teaching reconstruction of Snow's cholera investigation)

## Optional

- [For engineers](https://hypgraph.com/engineers/): policy and roles, tool wrappers, recorded runs, eval reports, spend, HTTP API, bundles in CI

- [Source](https://github.com/voodoomods/hypgraph): Apache-2.0

+ ## Profiles and workflows (hypgraph >= 0.5)

+ An investigation may pin a profile: scientific@2, software@2, trading@2, knowledge@2, optimization@2 (the @1 profiles are frozen as they were). A profile carries its discipline's workflow: stages with gates the record checks. The stage is derived, never set: `stage(question)` names the stage the question is in and every gate MET / NOT MET with what would meet it; write the next gate in order (a hypothesis with predictions; an experiment with data.expected BEFORE any run; the diff or instance as an artifact with its kind, and the run that `uses` it; a position decision with size, stop, review_date, paper, or kind=no_position). A corrected file, a newer commit, a changed instance or a withdrawn source makes earlier evidence STALE; a check on stale evidence doesn't count. An honest "it can't be answered" is a claim kind=inconclusive derived from what the search did find; checked, it settles the question. HTTP: /api/graph/stages, /api/graph/profiles. Method per workflow: https://github.com/voodoomods/hypgraph/tree/main/docs/workflows