ProofGate

Evidence before assertion. ProofGate is a zero-dependency Node.js CLI for AI product teams and operations-heavy businesses that need to keep sourced facts, reported claims, inferences, and unsupported assertions separate.

It audits a JSON manifest against local evidence, records SHA-256 provenance, produces Markdown and JSON reports, and fails CI when required support is missing or contradicted.

| Status | Meaning | | --- | --- | | confirmed | Every source exists and every explicit text check passes | | claimed | A source reports it, or a file is attached without machine checks | | inferred | Checked sources support an interpretation but do not state it directly | | unverified | Evidence is absent, over the size limit, missing required text, or contains forbidden text |

ProofGate never silently upgrades an attached document into proof.

The problem it solves

AI-generated reports, diligence packages, release notes, and portfolio case studies often flatten “someone said this” into “this is true.” ProofGate adds a small, inspectable gate between source material and a publishable claim.

Good fits include:

• release and deployment assertions;
• AI-generated research reports;
• diligence and compliance workpapers;
• portfolio case studies;
• asset and inventory records.

Five-minute demo

git clone https://github.com/christopherlhammer11-ai/proofgate.git
cd proofgate
npm ci
npm run check
npm run demo

Or install the CLI from npm:

npm install --global @craigai/proofgate
proofgate --help

The primary demo succeeds and writes reports to examples/output/demo:

PASS Acme Intake 1.4.0 demo
1 confirmed | 1 claimed | 0 inferred | 0 unverified
Reports: .../examples/output/demo

Case study: catching a readiness overclaim

The sanitized AI vendor readiness manifest checks three assertions against a test record and an approval record. Tests passed, so ProofGate confirms the test result and preserves a readiness interpretation as inferred. The approval record says deployment is pending and not approved, so the production claim fails.

node src/cli.js audit examples/case-study/manifest.json \
  --out examples/output/case-study \
  --allow-unverified

FAIL Sanitized AI vendor readiness review
1 confirmed | 0 claimed | 1 inferred | 1 unverified

See the committed case-study report for the full evidence trail. Remove --allow-unverified to use the same manifest as a CI gate; it exits with code 2.

Manifest format

{
  "$schema": "./proofgate.schema.json",
  "schemaVersion": 1,
  "project": "Acme Intake 1.4.0",
  "claims": [
    {
      "id": "production-approved",
      "statement": "The release is approved for production.",
      "mode": "verify",
      "evidence": [
        {
          "path": "evidence/approval-record.txt",
          "requireAll": ["production deployment is approved", "approval ID"],
          "forbidAny": ["not approved", "pending review"],
          "note": "Require affirmative approval and reject explicit blockers."
        }
      ]
    }
  ]
}

Evidence paths are resolved relative to the manifest and may not escape that directory, including through symlinks. Checks are case-insensitive literal matches:

• requireAll: every term must occur;
• requireAny: at least one term must occur;
• forbidAny: none of the terms may occur;
• the three checks may be combined.

Blank terms are invalid. The included proofgate.schema.json provides editor validation, while runtime validation enforces the same fields, types, modes, and schema version.

Modes express what passing evidence can establish:

| Mode | Passing result | Use it when | | --- | --- | --- | | verify | confirmed | Checked text directly supports the statement | | attribution | claimed | A source reports something not independently verified | | inference | inferred | A conclusion is reasoned from checked sources |

An inference with only an unchecked attachment remains claimed.

CLI

proofgate audit <manifest.json> [--out <directory>] [--max-bytes <number>] [--allow-unverified]

Options:

• --out: report directory; defaults to proofgate-output;
• --max-bytes: positive per-file limit; defaults to 10 MiB;
• --allow-unverified: write the report without returning a failing gate code.

Exit codes:

• 0: gate passed, or --allow-unverified was supplied;
• 1: invalid input or runtime error;
• 2: one or more claims are unverified.

Safety design

• Unknown manifest fields, empty check strings, and unsupported schema versions are rejected.
• Lexical traversal, absolute evidence paths, and symlinks outside the manifest directory are rejected.
• Evidence is streamed for hashing and text matching rather than buffered whole.
• A default 10 MiB per-file ceiling limits accidental or adversarial work.
• Manifest-controlled Markdown is escaped before reports are rendered.
• Reports retain the manifest filename and hash without exposing its absolute local path.

See SECURITY.md for the trust model and reporting process.

Design boundaries

ProofGate verifies file presence, hashes, and literal text checks. It does not authenticate a source, understand semantic entailment, establish legal truth, prove current real-world state, or measure system performance. forbidAny can catch explicit contradictions but is not a substitute for human review.

This is pre-1.0 portfolio software. Version 0.2 is tested and CI-backed, but it has not been independently security-audited or validated through third-party production use.

Never place secrets or sensitive source files in a public repository. Review generated reports before publishing them.

Development

npm ci
npm run check
npm run test:coverage

The test suite uses Node's built-in runner and temporary fixtures. CI exercises supported Node.js versions 20, 22, and 24. The project has no runtime or development dependencies.

The public npm package is @craigai/proofgate.

Roadmap

• pluggable PDF and CSV extractors;
• signed report attestations;
• GitHub Check annotations;
• independent security review and real-user validation.

See CHANGELOG.md for version history.

License

MIT