# Research Integrity Gate

> Diagnose and repair a failing ScientistOS integrity gate, provenance chain, or replay verification. Use when `science integrity`, `verify-store` or `verify-replay` fails, when the Claude Code Stop hook or the git pre-commit hook blocks on a broken research graph, before handing research to anyone, and before treating a result as final. Triggers include "integrity check failed", "the hook is blocking me", "blocking finding", "graph digest", "provenance chain broken", "claim has no lineage", "evidence not verified", "verify the replay package", "is this research ready to share". It only ever repairs graphs; never use it to weaken or bypass a check. Not for general CI, lint or test failures.

- Skill: `ahmad-jaradat-space/research-integrity-gate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ahmad-jaradat-space/research-integrity-gate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ahmad-jaradat-space/research-integrity-gate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: Ahmad-Jaradat-Space (https://skillmd.com/u/ahmad-jaradat-space)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ahmad-jaradat-space/research-integrity-gate

---


# 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.

```bash
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.py` on `Stop`, 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 by
  `sh 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

```bash
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

1. `science integrity` passes.
2. `science verify-store` passes.
3. Every load-bearing result has a replay package that `verify-replay` accepts.
4. Counter-evidence is still in the graph and reflected in claim qualifiers.
5. 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.