Ahmad-Jaradat-Space The integrity gate
Say in one short line that you are using the research-integrity-gate skill before you act, so
the user can see which discipline you are working under.
Three deterministic checks stand between the graph and a shareable conclusion. They exit
non-zero on failure and are wired into a Stop hook, so a session cannot quietly end on a
broken graph.
science integrity # audits claims, evidence, figures, run manifests
science verify-store # verifies the hash-chained event log
science verify-replay <package.zip>
Two gates run the same check:
.claude/hooks/research_integrity.pyonStop, so a Claude Code session cannot end on a broken graph. If it blocks, its stderr contains the findings table..git/hooks/pre-commit, so no client can commit on a broken graph. Installed bysh scripts/install-git-hooks.sh.
Both check every *.db in the project and skip *.corpus.db. The research_integrity and
research_verify_store MCP tools run the same audits and return structured findings.
The one rule
Repair the graph, never the check. Do not edit src/scientistos/modules/integrity.py,
loosen a threshold, delete the failing node, or disable the hook to get a green result. The
gate exists precisely because an agent under pressure to finish will otherwise argue its way
past its own evidence. If you genuinely believe a check is wrong, say so and stop, and let
the user decide.
Findings and their real repairs
Severities are blocking and warning. Only blocking findings fail the command.
| Category | Finding | Correct repair |
|---|---|---|
provenance |
event chain invalid | The append-only log was tampered with or truncated. Do not paper over it. Report it, and recover from an export-graph snapshot if one exists. |
claim |
E1+ claim has no evidence or result lineage | Attach the real evidence, or demote the claim to E0. |
evidence |
missing evidence node | The claim references an id that is not in the graph. Re-record the evidence properly. |
evidence |
evidence is not fully verified | One of existence, locator, entailment, scope_match is false. Go read the passage and set the flags honestly, or demote the claim. Do not flip flags to clear the gate. |
retraction |
supporting source is retracted | Remove that support and reassess the claim. A retracted source cannot hold up a claim. |
result |
missing result | Same as missing evidence. Record the result or demote. |
uncertainty |
E3+ result has no uncertainty | Add the real uncertainty record (interval, standard error, bootstrap). If you cannot quantify it, the claim is not E3. |
figure |
figure spec issue | Fix the figure spec so it is traceable to the data behind it. |
reproducibility |
run manifest missing code/environment digest | The run was not captured reproducibly. Re-run it through the sandbox so digests are recorded. |
execution |
non-zero exit code (warning) | A recorded run failed. Do not build claims on it. |
counter_evidence |
opposing evidence with no qualifier (warning) | Add an explicit qualifiers entry naming the scope limit. Worth fixing even though it does not block. |
Diagnosing
science integrity # the findings table plus the graph digest
science impact <node_id> # what else breaks if you change this node
science dump # full node payloads as JSON
Use impact before you change or demote anything. A claim rarely stands alone, and demoting
one often means qualifying the figures and conclusions built on top of it.
The graph digest
integrity and status both print a graph digest. It changes whenever the graph changes.
Quote it when you report a result, so the state you audited is identifiable later.
Before handing off
science integritypasses.science verify-storepasses.- Every load-bearing result has a replay package that
verify-replayaccepts. - Counter-evidence is still in the graph and reflected in claim qualifiers.
- The claim levels in the writeup match the claim levels in the graph.
Internal checks passing is engineering readiness, not an empirical result. science engineering-status --strict and science victory-status --strict keep those separate on
purpose. Passing tests never turns an external victory cell green, and neither does a clean
integrity run.