@relaxedg/proof-gate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Greg Bond
+
+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,174 @@
+# proof-gate
+
+A tiny CLI and GitHub Action that makes `done` require class-aware, inspectable evidence.
+
+Most workflows use one word for several different claims:
+
+- code changed
+- checks passed
+- a PR merged
+- a deploy marker moved
+- a live system behaved correctly
+- a team correctly decided not to ship
+
+`proof-gate` forces the claim to name its proof class and then runs the matching verifier. It does not pretend that a pointer is truth. Every pass prints an honesty depth:
+
+```text
+existence < shape < inspected < reran
+```
+
+## Install
+
+```bash
+npx @relaxedg/proof-gate@latest --help
+```
+
+For a local checkout:
+
+```bash
+npm install
+npm run build
+npm test
+npm run check
+```
+
+## Quick demo
+
+```bash
+npx @relaxedg/proof-gate@latest check examples/toy-service/tasks
+```
+
+Example output:
+
+```text
+PASS LOCAL-1 [local/existence]: file exists: ../evidence/unit-test.txt
+PASS PR-1 [ci/shape]: GitHub CI/PR URL shape accepted: https://github.com/gregbond/proof-gate/actions/runs/123456789
+PASS MERGED-1 [ci/shape]: GitHub CI/PR URL shape accepted: https://github.com/gregbond/proof-gate/commit/abcdef1
+PASS DEPLOY-1 [deploy/inspected]: release marker sha matches abc123
+PASS RUNTIME-1 [runtime/inspected]: runtime receipt status 200
+PASS NO-GO-1 [no-go/inspected]: no-go evidence file inspected: ../evidence/no-go.md
+```
+
+And the two lies this exists to reject:
+
+```text
+FAIL LIE-1: status=done requires a proof_state from local_only, pr_open, merged, deployed, runtime_proven, closed_no_go; got missing
+FAIL LIE-2: proof_state=runtime_proven cannot be justified by class=local; expected one of runtime, db, visual
+```
+
+## Proof classes
+
+Opinionated defaults:
+
+- `local`: local files or commands
+- `ci`: CI, PR, check, or commit evidence
+- `deploy`: release marker inspection, usually a SHA comparison
+- `runtime`: live healthcheck rerun or saved runtime receipt inspection
+- `db`: query rerun or DB receipt inspection
+- `visual`: screenshot/image inspection
+- `no-go`: proof that the correct outcome was not to ship
+
+`closed_no_go` is first-class. A stopped lane can be the correct result when the proof says stop.
+
+## Task contract
+
+```yaml
+id: RUNTIME-1
+status: done
+proof_state: runtime_proven
+proof:
+  class: runtime
+  evidence:
+    - type: receipt
+      value: ../evidence/runtime-receipt.json
+      expected_status: 200
+```
+
+`status: done` requires a non-`none` `proof_state`, a coherent `proof.class`, and at least one evidence pointer that the class verifier can inspect or rerun.
+
+## PR body check
+
+Put a fenced `Proof:` block in the PR body:
+
+````markdown
+Proof:
+```yaml
+id: PR-42
+status: done
+proof_state: deployed
+expected_sha: abc123
+proof:
+  class: deploy
+  evidence:
+    - type: release_json
+      value: examples/toy-service/release.json
+      expected_sha: abc123
+```
+````
+
+Then run:
+
+```bash
+proof-gate check-pr pr-body.md
+```
+
+## GitHub Action
+
+```yaml
+name: proof-gate
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+jobs:
+  proof-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: gregbond/proof-gate@v0.1
+        with:
+          mode: pr
+```
+
+For a task directory:
+
+```yaml
+- uses: actions/checkout@v4
+- uses: gregbond/proof-gate@v0.1
+  with:
+    mode: check
+    path: examples/toy-service/tasks
+```
+
+## What v0.1 can and cannot prove
+
+`proof-gate` does not magically prove every external truth. It makes proof claims inspectable, class-aware, and verifier-backed with explicit honesty depth.
+
+Current verifier depths:
+
+| Class | v0.1 behavior | Typical depth |
+| --- | --- | --- |
+| local | file exists, or command exits 0 with `--allow-exec` | existence or reran |
+| ci | GitHub PR, commit, check, or Actions run URL shape | shape |
+| deploy | reads release marker and compares SHA | inspected |
+| runtime | reads saved receipt, or performs GET with `--network` | inspected or reran |
+| db | reads count receipt, or runs command/query with `--allow-exec` | inspected or reran |
+| visual | verifies screenshot magic bytes | inspected |
+| no-go | requires reason plus non-empty file or URL | inspected or shape |
+
+The class to verifier seam is the product. Richer adapters should raise claims from `existence` or `shape` to `inspected` or `reran`.
+
+## Contributing
+
+v0.1 is intentionally small. The most useful contributions are new verifiers that raise honesty depth from `existence` or `shape` to `inspected` or `reran`, especially for real CI, deploy, runtime, DB, and issue-tracker workflows.
+
+If you try `proof-gate` and it does not fit where your team declares "done," please open an issue with:
+
+- where the done signal lives
+- what evidence already exists
+- what proof class you expected
+- what verifier would make the claim inspectable or rerunnable
+
+## Essay
+
+Read the launch essay: [Done Means Proven](docs/done-means-proven.md).

package/action.yml

@@ -0,0 +1,56 @@
+name: proof-gate
+description: Make done require class-aware, inspectable evidence.
+inputs:
+  mode:
+    description: Run mode, either pr or check.
+    required: false
+    default: pr
+  path:
+    description: File or directory for mode=check.
+    required: false
+    default: .
+  pr-body-file:
+    description: Optional PR body file for mode=pr. Defaults to the GitHub event pull request body.
+    required: false
+    default: ""
+  version:
+    description: npm version to install.
+    required: false
+    default: latest
+  network:
+    description: Allow network-backed runtime verifiers.
+    required: false
+    default: "false"
+  allow-exec:
+    description: Allow command/query verifiers.
+    required: false
+    default: "false"
+runs:
+  using: composite
+  steps:
+    - name: Install proof-gate
+      shell: bash
+      run: npm install -g "proof-gate@${{ inputs.version }}"
+    - name: Run proof-gate
+      shell: bash
+      env:
+        INPUT_MODE: ${{ inputs.mode }}
+        INPUT_PATH: ${{ inputs.path }}
+        INPUT_PR_BODY_FILE: ${{ inputs.pr-body-file }}
+        INPUT_NETWORK: ${{ inputs.network }}
+        INPUT_ALLOW_EXEC: ${{ inputs.allow-exec }}
+      run: |
+        set -euo pipefail
+        args=()
+        if [ "${INPUT_NETWORK}" = "true" ]; then args+=(--network); fi
+        if [ "${INPUT_ALLOW_EXEC}" = "true" ]; then args+=(--allow-exec); fi
+        if [ "${INPUT_MODE}" = "check" ]; then
+          proof-gate check "${INPUT_PATH}" "${args[@]}"
+          exit $?
+        fi
+        body_file="${INPUT_PR_BODY_FILE}"
+        if [ -z "${body_file}" ]; then
+          body_file="${RUNNER_TEMP}/proof-gate-pr-body.md"
+          node -e "const fs=require('fs'); const event=JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH,'utf8')); fs.writeFileSync(process.argv[1], event.pull_request?.body || '')" "${body_file}"
+        fi
+        proof-gate check-pr "${body_file}" "${args[@]}"

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { discoverProofFiles, parsePrBodyFile, readProofFile } from "./parse.js";
+import { checkProofBlock } from "./verify.js";
+function usage() {
+    return `proof-gate
+
+Usage:
+  proof-gate check <file-or-directory> [--network] [--allow-exec]
+  proof-gate check-pr <pr-body-file> [--network] [--allow-exec]
+
+Examples:
+  proof-gate check examples/toy-service/tasks
+  proof-gate check-pr examples/toy-service/pr-body.md
+`;
+}
+function parseFlags(args) {
+    const positional = [];
+    const options = { network: false, allowExec: false };
+    for (const arg of args) {
+        if (arg === "--network")
+            options.network = true;
+        else if (arg === "--allow-exec")
+            options.allowExec = true;
+        else
+            positional.push(arg);
+    }
+    return { positional, options };
+}
+async function runCheck(target, options) {
+    const files = discoverProofFiles(target);
+    let failed = 0;
+    for (const file of files) {
+        const block = readProofFile(file);
+        const result = await checkProofBlock(block, { filePath: file, ...options });
+        if (result.ok) {
+            console.log(`PASS ${result.id} [${result.className}/${result.depth}]: ${result.message}`);
+        }
+        else {
+            failed += 1;
+            console.error(`FAIL ${result.id}: ${result.message}`);
+        }
+    }
+    return failed === 0 ? 0 : 1;
+}
+async function runCheckPr(file, options) {
+    const block = parsePrBodyFile(file);
+    const result = await checkProofBlock(block, { filePath: path.resolve(file), ...options });
+    if (result.ok) {
+        console.log(`PASS ${result.id} [${result.className}/${result.depth}]: ${result.message}`);
+        return 0;
+    }
+    console.error(`FAIL ${result.id}: ${result.message}`);
+    return 1;
+}
+export async function main(argv = process.argv.slice(2)) {
+    const command = argv[0];
+    const { positional, options } = parseFlags(argv.slice(1));
+    try {
+        if (!command || command === "--help" || command === "-h") {
+            console.log(usage());
+            return 0;
+        }
+        if (command === "check") {
+            if (!positional[0])
+                throw new Error("check requires a file or directory");
+            return await runCheck(positional[0], options);
+        }
+        if (command === "check-pr") {
+            if (!positional[0])
+                throw new Error("check-pr requires a PR body file");
+            return await runCheckPr(positional[0], options);
+        }
+        console.error(usage());
+        return 2;
+    }
+    catch (error) {
+        console.error(`proof-gate: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}
+main().then((code) => {
+    process.exitCode = code;
+});

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+export declare const PROOF_CLASSES: readonly ["local", "ci", "deploy", "runtime", "db", "visual", "no-go"];
+export declare const PROOF_STATES: readonly ["none", "local_only", "pr_open", "merged", "deployed", "runtime_proven", "closed_no_go"];
+export declare const HONESTY_DEPTHS: readonly ["existence", "shape", "inspected", "reran"];
+export type ProofClass = (typeof PROOF_CLASSES)[number];
+export type ProofState = (typeof PROOF_STATES)[number];
+export type HonestyDepth = (typeof HONESTY_DEPTHS)[number];
+export declare function normalizeProofState(value: unknown): ProofState | undefined;
+export declare function normalizeProofClass(value: unknown): ProofClass | undefined;
+export declare function expectedClassesForState(state: ProofState): ProofClass[];
+export declare function depthRank(depth: HonestyDepth): number;
+export declare function maxDepth(depths: HonestyDepth[]): HonestyDepth;

package/dist/config.js

@@ -0,0 +1,42 @@
+export const PROOF_CLASSES = ["local", "ci", "deploy", "runtime", "db", "visual", "no-go"];
+export const PROOF_STATES = [
+    "none",
+    "local_only",
+    "pr_open",
+    "merged",
+    "deployed",
+    "runtime_proven",
+    "closed_no_go",
+];
+export const HONESTY_DEPTHS = ["existence", "shape", "inspected", "reran"];
+const STATE_TO_CLASSES = {
+    local_only: ["local"],
+    pr_open: ["local", "ci"],
+    merged: ["ci"],
+    deployed: ["deploy"],
+    runtime_proven: ["runtime", "db", "visual"],
+    closed_no_go: ["no-go"],
+};
+export function normalizeProofState(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.trim().toLowerCase().replaceAll("-", "_");
+    return PROOF_STATES.includes(normalized) ? normalized : undefined;
+}
+export function normalizeProofClass(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.trim().toLowerCase().replaceAll("_", "-");
+    return PROOF_CLASSES.includes(normalized) ? normalized : undefined;
+}
+export function expectedClassesForState(state) {
+    if (state === "none")
+        return [];
+    return STATE_TO_CLASSES[state];
+}
+export function depthRank(depth) {
+    return HONESTY_DEPTHS.indexOf(depth);
+}
+export function maxDepth(depths) {
+    return depths.reduce((best, next) => (depthRank(next) > depthRank(best) ? next : best), "existence");
+}

package/dist/parse.d.ts

@@ -0,0 +1,5 @@
+import type { ProofBlock } from "./types.js";
+export declare function loadStructuredText(raw: string, source: string): ProofBlock;
+export declare function readProofFile(filePath: string): ProofBlock;
+export declare function discoverProofFiles(target: string): string[];
+export declare function parsePrBodyFile(filePath: string): ProofBlock;

package/dist/parse.js

@@ -0,0 +1,35 @@
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+const PROOF_EXTENSIONS = new Set([".json", ".yaml", ".yml"]);
+export function loadStructuredText(raw, source) {
+    const ext = path.extname(source).toLowerCase();
+    const parsed = ext === ".json" ? JSON.parse(raw) : yaml.load(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`${source} did not parse to an object`);
+    }
+    return parsed;
+}
+export function readProofFile(filePath) {
+    return loadStructuredText(fs.readFileSync(filePath, "utf8"), filePath);
+}
+export function discoverProofFiles(target) {
+    const stat = fs.statSync(target);
+    if (stat.isFile())
+        return [target];
+    if (!stat.isDirectory())
+        throw new Error(`${target} is neither a file nor a directory`);
+    return fs
+        .readdirSync(target)
+        .filter((entry) => PROOF_EXTENSIONS.has(path.extname(entry).toLowerCase()))
+        .map((entry) => path.join(target, entry))
+        .sort();
+}
+export function parsePrBodyFile(filePath) {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const match = raw.match(/Proof:\s*\n```(?:yaml|yml|json)?\s*\n([\s\S]*?)\n```/i);
+    if (!match) {
+        throw new Error(`${filePath} does not contain a fenced Proof: block`);
+    }
+    return loadStructuredText(match[1] ?? "", filePath.endsWith(".json") ? filePath : `${filePath}.yaml`);
+}

package/dist/types.d.ts

@@ -0,0 +1,59 @@
+import type { HonestyDepth, ProofClass, ProofState } from "./config.js";
+export interface EvidencePointer {
+    type?: string;
+    value?: string;
+    path?: string;
+    url?: string;
+    command?: string;
+    query?: string;
+    expected_sha?: string;
+    expected_status?: number;
+    expected_count?: number;
+}
+export interface ProofDetails {
+    class?: string;
+    reason?: string;
+    evidence?: EvidencePointer[] | EvidencePointer;
+}
+export interface ProofBlock {
+    id?: string;
+    status?: string;
+    proof_state?: string;
+    expected_sha?: string;
+    expected_status?: number;
+    expected_count?: number;
+    reason?: string;
+    proof?: ProofDetails;
+}
+export interface CheckContext {
+    filePath?: string;
+    baseDir: string;
+    network: boolean;
+    allowExec: boolean;
+}
+export interface VerifierPass {
+    ok: true;
+    className: ProofClass;
+    depth: HonestyDepth;
+    message: string;
+}
+export interface VerifierFail {
+    ok: false;
+    className?: ProofClass;
+    message: string;
+}
+export type VerifierResult = VerifierPass | VerifierFail;
+export interface ProofCheckPass {
+    ok: true;
+    id: string;
+    proofState: ProofState;
+    className: ProofClass;
+    depth: HonestyDepth;
+    message: string;
+}
+export interface ProofCheckFail {
+    ok: false;
+    id: string;
+    message: string;
+}
+export type ProofCheckResult = ProofCheckPass | ProofCheckFail;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/verify.d.ts

@@ -0,0 +1,6 @@
+import type { ProofBlock, ProofCheckResult } from "./types.js";
+export declare function checkProofBlock(block: ProofBlock, options?: {
+    filePath?: string;
+    network?: boolean;
+    allowExec?: boolean;
+}): Promise<ProofCheckResult>;

package/dist/verify.js

@@ -0,0 +1,213 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { expectedClassesForState, maxDepth, normalizeProofClass, normalizeProofState } from "./config.js";
+function idFor(block) {
+    return block.id?.trim() || "unknown";
+}
+function evidenceList(block) {
+    const evidence = block.proof?.evidence;
+    if (!evidence)
+        return [];
+    return Array.isArray(evidence) ? evidence : [evidence];
+}
+function evidenceValue(evidence) {
+    return evidence.value || evidence.path || evidence.url || evidence.command || evidence.query || "";
+}
+function resolveEvidencePath(raw, baseDir) {
+    return path.isAbsolute(raw) ? raw : path.resolve(baseDir, raw);
+}
+function pass(className, depth, message) {
+    return { ok: true, className, depth, message };
+}
+function fail(className, message) {
+    return { ok: false, className, message };
+}
+function readJsonFile(filePath) {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+function firstObject(value) {
+    if (value && typeof value === "object" && !Array.isArray(value))
+        return value;
+    return undefined;
+}
+function numeric(value) {
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value)))
+        return Number(value);
+    return undefined;
+}
+function verifyLocal(evidence, block, baseDir, allowExec) {
+    const value = evidenceValue(evidence);
+    if (!value)
+        return fail("local", "local evidence needs a file path or command");
+    if (evidence.type === "command" || evidence.command) {
+        if (!allowExec)
+            return fail("local", "local command evidence requires --allow-exec");
+        execSync(value, { stdio: "pipe", cwd: baseDir });
+        return pass("local", "reran", `command exited 0: ${value}`);
+    }
+    const filePath = resolveEvidencePath(value, baseDir);
+    if (!fs.existsSync(filePath))
+        return fail("local", `file does not exist: ${value}`);
+    return pass("local", "existence", `file exists: ${value}`);
+}
+function verifyCi(evidence) {
+    const value = evidenceValue(evidence);
+    if (!/^https:\/\/github\.com\/[^/]+\/[^/]+\/(actions\/runs\/\d+|pull\/\d+|commit\/[0-9a-f]{7,40}|checks)/i.test(value)) {
+        return fail("ci", "ci evidence must look like a GitHub PR, commit, check, or Actions run URL");
+    }
+    return pass("ci", "shape", `GitHub CI/PR URL shape accepted: ${value}`);
+}
+function verifyDeploy(evidence, block, baseDir) {
+    const value = evidenceValue(evidence);
+    if (!value)
+        return fail("deploy", "deploy evidence needs a release.json path");
+    const expectedSha = evidence.expected_sha || block.expected_sha;
+    if (!expectedSha)
+        return fail("deploy", "deploy evidence needs expected_sha");
+    const filePath = resolveEvidencePath(value, baseDir);
+    if (!fs.existsSync(filePath))
+        return fail("deploy", `release marker does not exist: ${value}`);
+    const marker = firstObject(readJsonFile(filePath));
+    const actualSha = String(marker?.sha || marker?.commit || marker?.release_sha || "");
+    if (!actualSha)
+        return fail("deploy", `release marker has no sha-like field: ${value}`);
+    if (actualSha !== expectedSha)
+        return fail("deploy", `release marker sha mismatch: expected ${expectedSha}, got ${actualSha}`);
+    return pass("deploy", "inspected", `release marker sha matches ${expectedSha}`);
+}
+async function verifyRuntime(evidence, block, baseDir, network) {
+    const value = evidenceValue(evidence);
+    if (!value)
+        return fail("runtime", "runtime evidence needs a URL or receipt file");
+    const expectedStatus = evidence.expected_status || block.expected_status || 200;
+    if (/^https?:\/\//i.test(value)) {
+        if (!network)
+            return fail("runtime", "runtime URL evidence requires --network or a saved receipt");
+        const response = await fetch(value);
+        if (response.status !== expectedStatus)
+            return fail("runtime", `runtime GET expected ${expectedStatus}, got ${response.status}`);
+        return pass("runtime", "reran", `GET ${value} returned ${response.status}`);
+    }
+    const filePath = resolveEvidencePath(value, baseDir);
+    if (!fs.existsSync(filePath))
+        return fail("runtime", `runtime receipt does not exist: ${value}`);
+    const receipt = firstObject(readJsonFile(filePath));
+    const status = numeric(receipt?.status_code ?? receipt?.status ?? receipt?.http_status);
+    if (status === undefined)
+        return fail("runtime", `runtime receipt has no status field: ${value}`);
+    if (status !== expectedStatus)
+        return fail("runtime", `runtime receipt expected ${expectedStatus}, got ${status}`);
+    return pass("runtime", "inspected", `runtime receipt status ${status}`);
+}
+function verifyDb(evidence, block, baseDir, allowExec) {
+    const value = evidenceValue(evidence);
+    if (!value)
+        return fail("db", "db evidence needs a receipt file or command");
+    if (evidence.type === "command" || evidence.command || evidence.query) {
+        if (!allowExec)
+            return fail("db", "db command/query evidence requires --allow-exec");
+        execSync(value, { stdio: "pipe", cwd: baseDir });
+        return pass("db", "reran", "db command/query exited 0");
+    }
+    const filePath = resolveEvidencePath(value, baseDir);
+    if (!fs.existsSync(filePath))
+        return fail("db", `db receipt does not exist: ${value}`);
+    const receipt = firstObject(readJsonFile(filePath));
+    const actualCount = numeric(receipt?.count ?? receipt?.row_count ?? receipt?.rows);
+    const expectedCount = evidence.expected_count ?? block.expected_count;
+    if (expectedCount !== undefined && actualCount !== expectedCount) {
+        return fail("db", `db receipt expected count ${expectedCount}, got ${actualCount ?? "missing"}`);
+    }
+    return pass("db", "inspected", expectedCount === undefined ? "db receipt inspected" : `db count ${actualCount}`);
+}
+function verifyVisual(evidence, block, baseDir) {
+    const value = evidenceValue(evidence);
+    if (!value)
+        return fail("visual", "visual evidence needs a screenshot path");
+    const filePath = resolveEvidencePath(value, baseDir);
+    if (!fs.existsSync(filePath))
+        return fail("visual", `screenshot does not exist: ${value}`);
+    const bytes = fs.readFileSync(filePath);
+    const isPng = bytes.length >= 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47;
+    const isJpeg = bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff;
+    const isGif = bytes.length >= 6 && bytes.subarray(0, 3).toString("ascii") === "GIF";
+    if (!isPng && !isJpeg && !isGif)
+        return fail("visual", `screenshot is not PNG/JPEG/GIF by magic bytes: ${value}`);
+    return pass("visual", "inspected", `image magic bytes verified: ${value}`);
+}
+function verifyNoGo(evidence, block, baseDir) {
+    const reason = block.reason || block.proof?.reason;
+    if (!reason?.trim())
+        return fail("no-go", "closed_no_go requires a reason");
+    const value = evidenceValue(evidence);
+    if (!value)
+        return fail("no-go", "no-go evidence needs a pointer");
+    if (/^https?:\/\//i.test(value))
+        return pass("no-go", "shape", `no-go URL shape accepted: ${value}`);
+    const filePath = resolveEvidencePath(value, baseDir);
+    if (!fs.existsSync(filePath))
+        return fail("no-go", `no-go evidence file does not exist: ${value}`);
+    if (fs.statSync(filePath).size === 0)
+        return fail("no-go", `no-go evidence file is empty: ${value}`);
+    return pass("no-go", "inspected", `no-go evidence file inspected: ${value}`);
+}
+async function verifyEvidence(className, evidence, block, baseDir, network, allowExec) {
+    switch (className) {
+        case "local":
+            return verifyLocal(evidence, block, baseDir, allowExec);
+        case "ci":
+            return verifyCi(evidence);
+        case "deploy":
+            return verifyDeploy(evidence, block, baseDir);
+        case "runtime":
+            return verifyRuntime(evidence, block, baseDir, network);
+        case "db":
+            return verifyDb(evidence, block, baseDir, allowExec);
+        case "visual":
+            return verifyVisual(evidence, block, baseDir);
+        case "no-go":
+            return verifyNoGo(evidence, block, baseDir);
+    }
+}
+export async function checkProofBlock(block, options = {}) {
+    const id = idFor(block);
+    const status = block.status?.trim().toLowerCase();
+    const rawState = block.proof_state;
+    const proofState = normalizeProofState(rawState);
+    if (status === "done" && !proofState) {
+        return { ok: false, id, message: `status=done requires a proof_state from local_only, pr_open, merged, deployed, runtime_proven, closed_no_go; got ${rawState ? String(rawState) : "missing"}` };
+    }
+    if (status === "done" && proofState === "none") {
+        return { ok: false, id, message: "status=done requires proof_state to be non-none" };
+    }
+    if (!proofState || proofState === "none") {
+        return { ok: false, id, message: "proof_state is required" };
+    }
+    const className = normalizeProofClass(block.proof?.class);
+    if (!className)
+        return { ok: false, id, message: `proof.class is required and must be one of: local, ci, deploy, runtime, db, visual, no-go` };
+    const expected = expectedClassesForState(proofState);
+    if (!expected.includes(className)) {
+        return { ok: false, id, message: `proof_state=${proofState} cannot be justified by class=${className}; expected one of ${expected.join(", ")}` };
+    }
+    if (proofState === "closed_no_go" && !(block.reason || block.proof?.reason)?.trim()) {
+        return { ok: false, id, message: "proof_state=closed_no_go requires a reason" };
+    }
+    const evidence = evidenceList(block);
+    if (evidence.length === 0)
+        return { ok: false, id, message: "proof.evidence requires at least one pointer" };
+    const baseDir = options.filePath ? path.dirname(options.filePath) : process.cwd();
+    const results = [];
+    for (const pointer of evidence) {
+        results.push(await verifyEvidence(className, pointer, block, baseDir, Boolean(options.network), Boolean(options.allowExec)));
+    }
+    const failed = results.find((result) => !result.ok);
+    if (failed && !failed.ok)
+        return { ok: false, id, message: failed.message };
+    const passes = results.filter((result) => result.ok);
+    const depth = maxDepth(passes.map((result) => result.depth));
+    return { ok: true, id, proofState, className, depth, message: passes.map((result) => result.message).join("; ") };
+}

package/docs/done-means-proven.md

@@ -0,0 +1,103 @@
+# Done Means Proven
+
+Software teams have overloaded one word until it stopped meaning anything.
+
+Done can mean a patch exists. It can mean tests passed. It can mean a PR merged. It can mean the deploy job ran. It can mean the live system behaved correctly. In agent-heavy workflows, the collapse gets worse because agents are very good at producing confident summaries from partial evidence.
+
+The failure is not only capability. It is epistemology.
+
+If another actor cannot independently inspect or rerun the evidence, the claim is not runtime truth. It is narrative truth. Narrative truth can be useful for routing, but it should not close work.
+
+## The missing vocabulary
+
+A done claim should name what kind of proof backs it:
+
+- `local`: the local worktree or developer runtime proved it
+- `ci`: automated checks proved the branch or PR path
+- `deploy`: the deploy marker or release path moved to the expected version
+- `runtime`: the running system was exercised
+- `db`: authoritative stored state was inspected
+- `visual`: a rendered screen or screenshot proved the visual claim
+- `no-go`: the correct outcome was to stop, roll back, or decide not to ship
+
+The last class matters. Most definition-of-done systems have no vocabulary for a correct no. They reward motion and leave stopped work looking incomplete. But sometimes the highest-quality outcome is proving that a lane should not ship.
+
+## The rule
+
+`done` requires a proof state, a proof class, and evidence that can be inspected or rerun.
+
+Not merely a sentence. Not merely a link. Not merely a JSON file that an agent could have fabricated.
+
+The evidence has to match the claim. A local file can justify `local_only`. It cannot justify `runtime_proven`. A release marker can justify `deployed`. It cannot prove the live API behavior unless the runtime was exercised too.
+
+This is the invariant behind `proof-gate`:
+
+```text
+status=done requires proof_state != none
+proof_state=runtime_proven requires class in runtime, db, visual
+class chooses the verifier
+verifier prints honesty depth
+```
+
+The depth label is the honesty contract:
+
+```text
+existence < shape < inspected < reran
+```
+
+A gate that only checks for a pointer should say it checked existence. A gate that curls a healthcheck should say it reran runtime evidence. The difference is the whole point.
+
+## What a gate can and cannot do
+
+A small CI gate cannot prove every truth about production. It can make false confidence harder.
+
+`proof-gate` v0.1 does not claim omniscience. It makes proof claims inspectable, class-aware, and verifier-backed with explicit honesty depth. Some verifiers are intentionally shallow in v0.1. CI URLs are shape-checked. Local files are existence-checked. Deploy markers, runtime receipts, DB receipts, and visual screenshots are inspected. Runtime URLs and command/query checks can be rerun when explicitly allowed.
+
+That scope is not a caveat buried at the bottom. It is the architecture. The class to verifier mapping is first-class so deeper adapters can replace shallow checks without changing the contract.
+
+## The output should tell the truth
+
+A legitimate deploy proof should look like this:
+
+```text
+PASS DEPLOY-1 [deploy/inspected]: release marker sha matches abc123
+```
+
+A legitimate runtime receipt should look like this:
+
+```text
+PASS RUNTIME-1 [runtime/inspected]: runtime receipt status 200
+```
+
+And a local file pretending to be runtime proof should fail before any verifier runs:
+
+```text
+FAIL LIE-2: proof_state=runtime_proven cannot be justified by class=local; expected one of runtime, db, visual
+```
+
+That is the difference between pointer discipline and proof discipline.
+
+## Why this matters more with agents
+
+Humans also blur proof states, but agents amplify the problem. They can summarize a desired outcome in polished language, cite files that exist, and move work across tools faster than teams can verify the underlying claim.
+
+The answer is not to distrust agents. The answer is to give them contracts that make truth inspectable.
+
+A good agent should be able to say:
+
+```text
+local-only: tests pass here
+PR-open: reviewable branch exists
+merged: main contains the change
+deployed: release marker matches the SHA
+runtime-proven: live behavior was exercised
+closed-no-go: evidence says stop
+```
+
+Those are different claims. They deserve different proof.
+
+## The launch target
+
+Attention is not adoption. Stars, comments, and traffic are useful, but they are not runtime proof.
+
+The real launch proof for this project is one repo I do not control committing a `proof-gate.yml` workflow or equivalent CI integration. That is the moment the idea leaves narrative truth and becomes runtime truth.

package/examples/toy-service/evidence/db-receipt.json

@@ -0,0 +1,4 @@
+{
+  "count": 3,
+  "query": "select count(*) from toy_events"
+}

package/examples/toy-service/evidence/no-go.md

@@ -0,0 +1 @@
+The proposed change was intentionally stopped because the deploy proof did not match the requested SHA.

package/examples/toy-service/evidence/runtime-receipt.json

@@ -0,0 +1,5 @@
+{
+  "status": 200,
+  "body": "ok",
+  "checked_at": "2026-07-07T00:00:00Z"
+}

package/examples/toy-service/evidence/screenshot.gif

@@ -0,0 +1 @@
+GIF89a toy visual proof

package/examples/toy-service/evidence/unit-test.txt

@@ -0,0 +1 @@
+unit tests passed in the toy service

package/examples/toy-service/lies/bare-done.yml

@@ -0,0 +1,7 @@
+id: LIE-1
+status: done
+proof:
+  class: local
+  evidence:
+    - type: file
+      value: ../evidence/unit-test.txt

package/examples/toy-service/lies/runtime-proven-local.yml

@@ -0,0 +1,8 @@
+id: LIE-2
+status: done
+proof_state: runtime_proven
+proof:
+  class: local
+  evidence:
+    - type: file
+      value: ../evidence/unit-test.txt

package/examples/toy-service/pr-body.md

@@ -0,0 +1,17 @@
+# Example PR
+
+This PR updates the toy service.
+
+Proof:
+```yaml
+id: PR-BODY-1
+status: done
+proof_state: deployed
+expected_sha: abc123
+proof:
+  class: deploy
+  evidence:
+    - type: release_json
+      value: release.json
+      expected_sha: abc123
+```

package/examples/toy-service/release.json

@@ -0,0 +1,4 @@
+{
+  "sha": "abc123",
+  "service": "toy-service"
+}

package/examples/toy-service/tasks/001-local.yml

@@ -0,0 +1,8 @@
+id: LOCAL-1
+status: done
+proof_state: local_only
+proof:
+  class: local
+  evidence:
+    - type: file
+      value: ../evidence/unit-test.txt

package/examples/toy-service/tasks/002-pr-open.yml

@@ -0,0 +1,8 @@
+id: PR-1
+status: done
+proof_state: pr_open
+proof:
+  class: ci
+  evidence:
+    - type: url
+      value: https://github.com/gregbond/proof-gate/actions/runs/123456789

package/examples/toy-service/tasks/003-merged.yml

@@ -0,0 +1,8 @@
+id: MERGED-1
+status: done
+proof_state: merged
+proof:
+  class: ci
+  evidence:
+    - type: url
+      value: https://github.com/gregbond/proof-gate/commit/abcdef1

package/examples/toy-service/tasks/004-deployed.yml

@@ -0,0 +1,10 @@
+id: DEPLOY-1
+status: done
+proof_state: deployed
+expected_sha: abc123
+proof:
+  class: deploy
+  evidence:
+    - type: release_json
+      value: ../release.json
+      expected_sha: abc123

package/examples/toy-service/tasks/005-runtime-proven.yml

@@ -0,0 +1,9 @@
+id: RUNTIME-1
+status: done
+proof_state: runtime_proven
+proof:
+  class: runtime
+  evidence:
+    - type: receipt
+      value: ../evidence/runtime-receipt.json
+      expected_status: 200

package/examples/toy-service/tasks/006-closed-no-go.yml

@@ -0,0 +1,9 @@
+id: NO-GO-1
+status: done
+proof_state: closed_no_go
+reason: The correct decision was not to ship this change.
+proof:
+  class: no-go
+  evidence:
+    - type: file
+      value: ../evidence/no-go.md

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@relaxedg/proof-gate",
+  "version": "0.1.0",
+  "description": "A tiny CI gate that makes done require class-aware, inspectable evidence.",
+  "type": "module",
+  "bin": {
+    "proof-gate": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "action.yml",
+    "docs",
+    "examples"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "check": "node dist/cli.js check examples/toy-service/tasks && node dist/cli.js check-pr examples/toy-service/pr-body.md",
+    "prepublishOnly": "npm run build && npm test && npm run check"
+  },
+  "keywords": [
+    "agentops",
+    "ci",
+    "github-actions",
+    "proof",
+    "runtime-truth",
+    "ai-agents"
+  ],
+  "author": "Greg Bond",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gregbond/proof-gate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gregbond/proof-gate/issues"
+  },
+  "homepage": "https://github.com/gregbond/proof-gate#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}