@pietro-falco/verity 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pietro Falco
+
+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,112 @@
+# verity
+
+[![CI](https://github.com/pietro-falco/verity/actions/workflows/ci.yml/badge.svg)](https://github.com/pietro-falco/verity/actions/workflows/ci.yml)
+
+Turn your coding agent's "done" into a receipt you can check — deterministic, local, zero-dependency.
+
+Status: pre-alpha
+
+## The problem
+
+Coding agents produce plausible narratives about the work they performed.
+"Done" is a claim, not a receipt. A rules file (CLAUDE.md, Cursor rules,
+AGENTS.md) can ask an agent to be honest about what it did — it cannot
+verify that it was. verity checks the claim instead of trusting the
+narration: it moves trust from what the agent says it did to evidence a
+human (or another process) can inspect directly.
+
+## How it works (30 seconds)
+
+The agent — or you — declares a set of claims in `.verity/claims.json`.
+verity runs one deterministic check per claim against literal reality: the
+filesystem, a git repository's `HEAD` via `git show`, or a real command's
+actual exit code. You get a ✓/✗ receipt on stdout and a JSON report on disk.
+The process exits `1` if anything fails, so it gates scripts and CI as
+easily as it informs a human review.
+
+```json
+{
+  "version": "0.1",
+  "claims": [
+    { "id": "tests-pass", "type": "command", "run": "npm test", "expect": { "exitCode": 0 } }
+  ]
+}
+```
+
+```
+$ verity verify
+✓ tests-pass [command] command exits 0 — exit 0
+
+1 passed, 0 failed
+OVERALL: PASS
+```
+
+## Install / Quickstart
+
+**`npx @pietro-falco/verity verify`** — the zero-install path. Run it in any
+project with a `.verity/claims.json` manifest.
+
+**From source (for development):**
+
+```
+git clone https://github.com/pietro-falco/verity.git
+cd verity
+npm install
+npm run build
+node dist/cli.js verify
+```
+
+## Claim types
+
+| type            | asserts                                   | key fields                          |
+| ---------------- | ------------------------------------------ | ------------------------------------ |
+| `file_exists`    | a path exists (optionally non-empty)      | `path`, `nonEmpty`                  |
+| `file_matches`   | file content matches                      | `path`, `match`                     |
+| `git_committed`  | path is committed at `HEAD`               | `path`, `match` (against committed content) |
+| `command`        | a command's exit code / stdout            | `run`, `cwd`, `timeoutMs`, `expect` |
+
+`match` is `{ kind: "substring" | "regex" | "sha256", value, flags? }`. Full
+field-by-field semantics, defaults, and PASS conditions are in
+[`docs/spec.md`](docs/spec.md).
+
+## For coding agents
+
+[`SKILL.md`](SKILL.md) is a cross-agent skill any coding agent can load. The
+loop it describes: emit `.verity/claims.json` after finishing a task → run
+`verity verify` → paste the full raw receipt back to the human, unedited.
+
+## Scope and non-goals
+
+verity does not judge semantic correctness (whether the code is *good*,
+only whether the declared claim is *true*), does not sign anything in v0,
+and does not orchestrate workflows. See
+[`docs/adrs/0001-verity-architecture.md`](docs/adrs/0001-verity-architecture.md)
+for the full reasoning. Where it sits relative to adjacent controls: rules
+files request behavior; commit/CI hooks enforce process at commit time;
+supply-chain attestation (SLSA/in-toto) covers release artifacts post-build;
+verity reconciles task-level claims at review time — standalone, offline,
+in the development loop itself.
+
+## Design choices
+
+- **Zero runtime dependencies.** Node built-ins only — the whole tool is
+  auditable in minutes, with near-zero supply-chain surface.
+- **Deterministic and offline.** No network calls, no LLM in the loop. Same
+  inputs, same verdicts, every time.
+- **In-toto-inspired vocabulary.** Receipts use `subject` / `predicate` /
+  `evidence` / `verdict`, borrowed for interoperability with other
+  evidence-consuming tooling.
+
+## Verifying verity
+
+This repository verifies itself: [`.verity/claims.json`](.verity/claims.json)
+declares claims about verity's own README, license, ADR status, docs, and
+test suite. Run it with:
+
+```
+node dist/cli.js verify
+```
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

package/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: verity
+description: Use after completing a coding task, to produce a verifiable receipt of what was actually done instead of a prose claim of completion.
+---
+
+## What this does
+
+verity reconciles your claims about a task against literal reality — files
+on disk, git history, real command exit codes. The human reviewing your work
+trusts the receipt it produces, not your narration of what you did.
+
+## Workflow
+
+1. After finishing the task, write `.verity/claims.json` declaring
+   verifiable claims about what you did. One claim per meaningful assertion:
+   - Files you created or modified → `file_exists` / `file_matches`.
+   - Work you committed → `git_committed`.
+   - "Tests pass" / "build passes" → `command` claims that actually run
+     the test suite / build, not claims that assume the outcome.
+2. Run `npx @pietro-falco/verity verify` (or, in a development checkout of verity itself,
+   `node dist/cli.js verify`).
+3. Paste the full raw report output back to the human — never summarize it.
+4. If any claim FAILs, either fix the underlying work or correct the claim,
+   then rerun. If you change a claim to make it pass, disclose that you did
+   so and why — never silently edit a claim just to turn a FAIL into a PASS.
+
+## Example `.verity/claims.json`
+
+```json
+{
+  "version": "0.1",
+  "claims": [
+    {
+      "id": "readme-updated",
+      "type": "file_matches",
+      "path": "README.md",
+      "match": { "kind": "substring", "value": "## Installation" }
+    },
+    {
+      "id": "fix-committed",
+      "type": "git_committed",
+      "path": "src/parser.ts",
+      "match": { "kind": "substring", "value": "function parseHeader" }
+    },
+    {
+      "id": "tests-pass",
+      "type": "command",
+      "run": "npm test",
+      "expect": { "exitCode": 0 }
+    },
+    {
+      "id": "build-passes",
+      "type": "command",
+      "run": "npm run build",
+      "expect": { "exitCode": 0 }
+    }
+  ]
+}
+```
+
+## Rules
+
+- Claims must be falsifiable and specific — "it works" is not a claim;
+  "`npm test` exits 0" is.
+- Prefer `git_committed` over `file_exists` / `file_matches` when the task
+  said the work should be committed — a file existing in the working tree
+  is not the same claim as a file being committed.
+- Keep `command` claims fast and side-effect-free; they run for real, every
+  verification.
+- Add `.verity/reports/` to your project's `.gitignore` — receipts are
+  generated artifacts, not source.

package/dist/checks.d.ts

@@ -0,0 +1,6 @@
+import type { CheckContext, Claim, ClaimResult, CommandClaim, FileExistsClaim, FileMatchesClaim, GitCommittedClaim } from "./types.ts";
+export declare function checkFileExists(claim: FileExistsClaim, ctx: CheckContext): ClaimResult;
+export declare function checkFileMatches(claim: FileMatchesClaim, ctx: CheckContext): ClaimResult;
+export declare function checkGitCommitted(claim: GitCommittedClaim, ctx: CheckContext): ClaimResult;
+export declare function checkCommand(claim: CommandClaim, ctx: CheckContext): ClaimResult;
+export declare function runClaim(claim: Claim, ctx: CheckContext): ClaimResult;

package/dist/checks.js

@@ -0,0 +1,226 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+function matchBuffer(buf, match) {
+    if (match.kind === "sha256") {
+        const digest = createHash("sha256").update(buf).digest("hex");
+        const pass = digest.toLowerCase() === match.value.toLowerCase();
+        return {
+            pass,
+            evidence: pass
+                ? `sha256 digest ${digest} matches expected`
+                : `sha256 digest ${digest} != expected ${match.value.toLowerCase()}`,
+        };
+    }
+    const text = buf.toString("utf8");
+    if (match.kind === "substring") {
+        const pass = text.includes(match.value);
+        return {
+            pass,
+            evidence: pass
+                ? `substring ${JSON.stringify(match.value)} found`
+                : `substring ${JSON.stringify(match.value)} not found (${buf.length} bytes read)`,
+        };
+    }
+    // regex
+    const re = new RegExp(match.value, match.flags);
+    const pass = re.test(text);
+    return {
+        pass,
+        evidence: pass
+            ? `regex /${match.value}/${match.flags ?? ""} matched`
+            : `regex /${match.value}/${match.flags ?? ""} did not match (${buf.length} bytes read)`,
+    };
+}
+function describeMatch(match) {
+    if (match.kind === "sha256")
+        return `sha256 digest equals ${match.value.toLowerCase()}`;
+    if (match.kind === "substring")
+        return `content contains substring ${JSON.stringify(match.value)}`;
+    return `content matches regex /${match.value}/${match.flags ?? ""}`;
+}
+export function checkFileExists(claim, ctx) {
+    const abs = resolve(ctx.cwd, claim.path);
+    const predicate = claim.nonEmpty ? "file exists and is non-empty" : "file exists";
+    let stat;
+    try {
+        stat = statSync(abs);
+    }
+    catch {
+        return {
+            id: claim.id,
+            type: claim.type,
+            subject: claim.path,
+            predicate,
+            verdict: "FAIL",
+            evidence: `does not exist at ${abs}`,
+        };
+    }
+    if (claim.nonEmpty && stat.size === 0) {
+        return {
+            id: claim.id,
+            type: claim.type,
+            subject: claim.path,
+            predicate,
+            verdict: "FAIL",
+            evidence: "exists, 0 bytes (nonEmpty required)",
+        };
+    }
+    return {
+        id: claim.id,
+        type: claim.type,
+        subject: claim.path,
+        predicate,
+        verdict: "PASS",
+        evidence: `exists, ${stat.size} bytes`,
+    };
+}
+export function checkFileMatches(claim, ctx) {
+    const abs = resolve(ctx.cwd, claim.path);
+    const predicate = describeMatch(claim.match);
+    let buf;
+    try {
+        buf = readFileSync(abs);
+    }
+    catch (err) {
+        return {
+            id: claim.id,
+            type: claim.type,
+            subject: claim.path,
+            predicate,
+            verdict: "FAIL",
+            evidence: `file not found at ${abs}: ${err.message}`,
+        };
+    }
+    const outcome = matchBuffer(buf, claim.match);
+    return {
+        id: claim.id,
+        type: claim.type,
+        subject: claim.path,
+        predicate,
+        verdict: outcome.pass ? "PASS" : "FAIL",
+        evidence: outcome.evidence,
+    };
+}
+export function checkGitCommitted(claim, ctx) {
+    const predicate = claim.match
+        ? `path is committed at HEAD and ${describeMatch(claim.match)}`
+        : "path is committed at HEAD";
+    if (!ctx.repoRoot) {
+        return {
+            id: claim.id,
+            type: claim.type,
+            subject: claim.path,
+            predicate,
+            verdict: "FAIL",
+            evidence: "not inside a git repository",
+        };
+    }
+    // git show HEAD:<path> requires posix separators regardless of platform.
+    const repoRelativePath = relative(ctx.repoRoot, resolve(ctx.cwd, claim.path)).split(sep).join("/");
+    const result = spawnSync("git", ["show", `HEAD:${repoRelativePath}`], {
+        cwd: ctx.repoRoot,
+    });
+    if (result.error) {
+        return {
+            id: claim.id,
+            type: claim.type,
+            subject: claim.path,
+            predicate,
+            verdict: "FAIL",
+            evidence: `failed to run git: ${result.error.message}`,
+        };
+    }
+    if (result.status !== 0) {
+        const stderr = (result.stderr ?? Buffer.alloc(0)).toString("utf8").trim();
+        return {
+            id: claim.id,
+            type: claim.type,
+            subject: claim.path,
+            predicate,
+            verdict: "FAIL",
+            evidence: `git show HEAD:${repoRelativePath} exit ${result.status}${stderr ? `; stderr: ${stderr}` : ""}`,
+        };
+    }
+    if (!claim.match) {
+        return {
+            id: claim.id,
+            type: claim.type,
+            subject: claim.path,
+            predicate,
+            verdict: "PASS",
+            evidence: `git show HEAD:${repoRelativePath} exit 0`,
+        };
+    }
+    const outcome = matchBuffer(result.stdout ?? Buffer.alloc(0), claim.match);
+    return {
+        id: claim.id,
+        type: claim.type,
+        subject: claim.path,
+        predicate,
+        verdict: outcome.pass ? "PASS" : "FAIL",
+        evidence: `git show HEAD:${repoRelativePath} exit 0; ${outcome.evidence}`,
+    };
+}
+const DEFAULT_COMMAND_TIMEOUT_MS = 60_000;
+export function checkCommand(claim, ctx) {
+    const expectedExitCode = claim.expect.exitCode ?? 0;
+    const timeoutMs = claim.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+    const cwd = claim.cwd ? resolve(ctx.cwd, claim.cwd) : ctx.cwd;
+    const predicate = `command exits ${expectedExitCode}${claim.expect.stdout ? ` and stdout ${describeMatch(claim.expect.stdout)}` : ""}`;
+    const result = spawnSync(claim.run, {
+        shell: true,
+        cwd,
+        timeout: timeoutMs,
+    });
+    if (result.error && result.error.code !== "ETIMEDOUT") {
+        return {
+            id: claim.id,
+            type: claim.type,
+            subject: claim.run,
+            predicate,
+            verdict: "FAIL",
+            evidence: `command failed to spawn: ${result.error.message}`,
+        };
+    }
+    if (result.signal || result.error?.code === "ETIMEDOUT") {
+        return {
+            id: claim.id,
+            type: claim.type,
+            subject: claim.run,
+            predicate,
+            verdict: "FAIL",
+            evidence: `command timed out after ${timeoutMs}ms (killed with ${result.signal ?? "SIGTERM"})`,
+        };
+    }
+    const actualExitCode = result.status ?? -1;
+    const exitPass = actualExitCode === expectedExitCode;
+    const stdoutOutcome = claim.expect.stdout
+        ? matchBuffer(result.stdout ?? Buffer.alloc(0), claim.expect.stdout)
+        : null;
+    const pass = exitPass && (stdoutOutcome === null || stdoutOutcome.pass);
+    const parts = [exitPass ? `exit ${actualExitCode}` : `exit ${actualExitCode} (expected ${expectedExitCode})`];
+    if (stdoutOutcome)
+        parts.push(`stdout: ${stdoutOutcome.evidence}`);
+    return {
+        id: claim.id,
+        type: claim.type,
+        subject: claim.run,
+        predicate,
+        verdict: pass ? "PASS" : "FAIL",
+        evidence: parts.join("; "),
+    };
+}
+export function runClaim(claim, ctx) {
+    switch (claim.type) {
+        case "file_exists":
+            return checkFileExists(claim, ctx);
+        case "file_matches":
+            return checkFileMatches(claim, ctx);
+        case "git_committed":
+            return checkGitCommitted(claim, ctx);
+        case "command":
+            return checkCommand(claim, ctx);
+    }
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { formatHuman, toReceiptJson, writeReceipt } from "./report.js";
+import { VerityUsageError } from "./types.js";
+import { DEFAULT_MANIFEST_PATH, getToolVersion, verify } from "./verify.js";
+const USAGE = `verity — deterministic claim verifier
+
+Usage:
+  verity verify [manifestPath] [--json]
+  verity --version | -v
+  verity --help | -h
+
+Arguments:
+  manifestPath   Path to claims manifest (default: ${DEFAULT_MANIFEST_PATH})
+
+Options:
+  --json         Print the full JSON report to stdout instead of the human summary`;
+function runVerifyCommand(args) {
+    let manifestPath = DEFAULT_MANIFEST_PATH;
+    let json = false;
+    for (const arg of args) {
+        if (arg === "--json") {
+            json = true;
+        }
+        else if (arg.startsWith("-")) {
+            process.stderr.write(`unknown option: ${arg}\n`);
+            return 2;
+        }
+        else {
+            manifestPath = arg;
+        }
+    }
+    let outcome;
+    try {
+        outcome = verify(manifestPath);
+    }
+    catch (err) {
+        if (err instanceof VerityUsageError) {
+            process.stderr.write(`${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+    writeReceipt(outcome.report, process.cwd());
+    process.stdout.write(`${json ? toReceiptJson(outcome.report) : formatHuman(outcome.report)}\n`);
+    return outcome.exitCode;
+}
+export function main(argv) {
+    const [cmd, ...rest] = argv;
+    if (cmd === "--version" || cmd === "-v") {
+        process.stdout.write(`${getToolVersion()}\n`);
+        return 0;
+    }
+    if (cmd === "--help" || cmd === "-h") {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    if (cmd === undefined) {
+        process.stderr.write(`${USAGE}\n`);
+        return 2;
+    }
+    if (cmd === "verify") {
+        return runVerifyCommand(rest);
+    }
+    process.stderr.write(`unknown command: ${cmd}\n${USAGE}\n`);
+    return 2;
+}
+process.exitCode = main(process.argv.slice(2));

package/dist/report.d.ts

@@ -0,0 +1,4 @@
+import type { VerifyReport } from "./types.ts";
+export declare function formatHuman(report: VerifyReport): string;
+export declare function toReceiptJson(report: VerifyReport): string;
+export declare function writeReceipt(report: VerifyReport, cwd: string): string;

package/dist/report.js

@@ -0,0 +1,26 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+export function formatHuman(report) {
+    const lines = report.results.map((r) => {
+        const mark = r.verdict === "PASS" ? "✓" : "✗";
+        return `${mark} ${r.id} [${r.type}] ${r.predicate} — ${r.evidence}`;
+    });
+    const passed = report.results.filter((r) => r.verdict === "PASS").length;
+    const failed = report.results.length - passed;
+    const overall = failed === 0 ? "PASS" : "FAIL";
+    lines.push("");
+    lines.push(`${passed} passed, ${failed} failed`);
+    lines.push(`OVERALL: ${overall}`);
+    return lines.join("\n");
+}
+export function toReceiptJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function writeReceipt(report, cwd) {
+    const dir = resolve(cwd, ".verity", "reports");
+    mkdirSync(dir, { recursive: true });
+    const filename = `${report.timestamp.replace(/:/g, "-")}.json`;
+    const path = join(dir, filename);
+    writeFileSync(path, toReceiptJson(report));
+    return path;
+}

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+export type MatchKind = "substring" | "regex" | "sha256";
+export interface MatchSpec {
+    kind: MatchKind;
+    value: string;
+    flags?: string;
+}
+interface ClaimBase {
+    id: string;
+    description?: string;
+}
+export interface FileExistsClaim extends ClaimBase {
+    type: "file_exists";
+    path: string;
+    nonEmpty?: boolean;
+}
+export interface FileMatchesClaim extends ClaimBase {
+    type: "file_matches";
+    path: string;
+    match: MatchSpec;
+}
+export interface GitCommittedClaim extends ClaimBase {
+    type: "git_committed";
+    path: string;
+    match?: MatchSpec;
+}
+export interface CommandExpect {
+    exitCode?: number;
+    stdout?: MatchSpec;
+}
+export interface CommandClaim extends ClaimBase {
+    type: "command";
+    run: string;
+    cwd?: string;
+    timeoutMs?: number;
+    expect: CommandExpect;
+}
+export type Claim = FileExistsClaim | FileMatchesClaim | GitCommittedClaim | CommandClaim;
+export interface Manifest {
+    version: string;
+    claims: Claim[];
+}
+export type Verdict = "PASS" | "FAIL";
+export interface ClaimResult {
+    id: string;
+    type: Claim["type"];
+    subject: string;
+    predicate: string;
+    verdict: Verdict;
+    evidence: string;
+}
+export interface VerifyReport {
+    version: string;
+    timestamp: string;
+    gitHeadSha: string | null;
+    results: ClaimResult[];
+}
+export interface CheckContext {
+    /** Directory that file_exists / file_matches paths and command cwd are resolved against. */
+    cwd: string;
+    /** Git repo root used for git_committed checks; null when not inside a git repo. */
+    repoRoot: string | null;
+}
+export declare class VerityUsageError extends Error {
+}
+export {};

package/dist/types.js

@@ -0,0 +1,2 @@
+export class VerityUsageError extends Error {
+}

package/dist/verify.d.ts

@@ -0,0 +1,12 @@
+import type { Manifest, VerifyReport } from "./types.ts";
+export declare const DEFAULT_MANIFEST_PATH = ".verity/claims.json";
+export declare function parseManifest(raw: unknown): Manifest;
+export declare function loadManifest(manifestPath: string): Manifest;
+export declare function getRepoRoot(cwd: string): string | null;
+export declare function getGitHeadSha(cwd: string): string | null;
+export declare function getToolVersion(): string;
+export interface VerifyOutcome {
+    report: VerifyReport;
+    exitCode: 0 | 1;
+}
+export declare function verify(manifestPath: string, cwd?: string): VerifyOutcome;

package/dist/verify.js

@@ -0,0 +1,169 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runClaim } from "./checks.js";
+import { VerityUsageError } from "./types.js";
+export const DEFAULT_MANIFEST_PATH = ".verity/claims.json";
+const CLAIM_TYPES = new Set(["file_exists", "file_matches", "git_committed", "command"]);
+const MATCH_KINDS = new Set(["substring", "regex", "sha256"]);
+function assertString(value, field) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new VerityUsageError(`expected non-empty string for "${field}", got ${JSON.stringify(value)}`);
+    }
+}
+function validateMatchSpec(value, field) {
+    if (typeof value !== "object" || value === null) {
+        throw new VerityUsageError(`expected match object for "${field}"`);
+    }
+    const match = value;
+    if (!MATCH_KINDS.has(match.kind)) {
+        throw new VerityUsageError(`unknown match kind "${String(match.kind)}" in "${field}"`);
+    }
+    assertString(match.value, `${field}.value`);
+    if (match.flags !== undefined && typeof match.flags !== "string") {
+        throw new VerityUsageError(`expected string for "${field}.flags"`);
+    }
+    return { kind: match.kind, value: match.value, flags: match.flags };
+}
+function validateClaim(raw, index) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new VerityUsageError(`claim[${index}] is not an object`);
+    }
+    const claim = raw;
+    assertString(claim.id, `claim[${index}].id`);
+    if (!CLAIM_TYPES.has(claim.type)) {
+        throw new VerityUsageError(`claim "${claim.id}" has unknown claim type "${String(claim.type)}"`);
+    }
+    const description = claim.description !== undefined ? String(claim.description) : undefined;
+    switch (claim.type) {
+        case "file_exists": {
+            assertString(claim.path, `claim "${claim.id}".path`);
+            if (claim.nonEmpty !== undefined && typeof claim.nonEmpty !== "boolean") {
+                throw new VerityUsageError(`claim "${claim.id}".nonEmpty must be boolean`);
+            }
+            return {
+                id: claim.id,
+                type: "file_exists",
+                description,
+                path: claim.path,
+                nonEmpty: claim.nonEmpty,
+            };
+        }
+        case "file_matches": {
+            assertString(claim.path, `claim "${claim.id}".path`);
+            const match = validateMatchSpec(claim.match, `claim "${claim.id}".match`);
+            return { id: claim.id, type: "file_matches", description, path: claim.path, match };
+        }
+        case "git_committed": {
+            assertString(claim.path, `claim "${claim.id}".path`);
+            const match = claim.match !== undefined ? validateMatchSpec(claim.match, `claim "${claim.id}".match`) : undefined;
+            return { id: claim.id, type: "git_committed", description, path: claim.path, match };
+        }
+        case "command": {
+            assertString(claim.run, `claim "${claim.id}".run`);
+            if (claim.cwd !== undefined)
+                assertString(claim.cwd, `claim "${claim.id}".cwd`);
+            if (claim.timeoutMs !== undefined && typeof claim.timeoutMs !== "number") {
+                throw new VerityUsageError(`claim "${claim.id}".timeoutMs must be a number`);
+            }
+            if (typeof claim.expect !== "object" || claim.expect === null) {
+                throw new VerityUsageError(`claim "${claim.id}".expect is required`);
+            }
+            const expectRaw = claim.expect;
+            if (expectRaw.exitCode !== undefined && typeof expectRaw.exitCode !== "number") {
+                throw new VerityUsageError(`claim "${claim.id}".expect.exitCode must be a number`);
+            }
+            const stdout = expectRaw.stdout !== undefined ? validateMatchSpec(expectRaw.stdout, `claim "${claim.id}".expect.stdout`) : undefined;
+            return {
+                id: claim.id,
+                type: "command",
+                description,
+                run: claim.run,
+                cwd: claim.cwd,
+                timeoutMs: claim.timeoutMs,
+                expect: { exitCode: expectRaw.exitCode, stdout },
+            };
+        }
+        default:
+            throw new VerityUsageError(`claim "${claim.id}" has unknown claim type "${String(claim.type)}"`);
+    }
+}
+export function parseManifest(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new VerityUsageError("manifest root must be an object");
+    }
+    const data = raw;
+    assertString(data.version, "version");
+    if (!Array.isArray(data.claims)) {
+        throw new VerityUsageError('manifest "claims" must be an array');
+    }
+    const seenIds = new Set();
+    const claims = data.claims.map((c, i) => {
+        const claim = validateClaim(c, i);
+        if (seenIds.has(claim.id)) {
+            throw new VerityUsageError(`duplicate claim id "${claim.id}"`);
+        }
+        seenIds.add(claim.id);
+        return claim;
+    });
+    return { version: data.version, claims };
+}
+export function loadManifest(manifestPath) {
+    let text;
+    try {
+        text = readFileSync(manifestPath, "utf8");
+    }
+    catch (err) {
+        throw new VerityUsageError(`manifest not found at ${manifestPath}: ${err.message}`);
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (err) {
+        throw new VerityUsageError(`invalid JSON in manifest ${manifestPath}: ${err.message}`);
+    }
+    return parseManifest(json);
+}
+export function getRepoRoot(cwd) {
+    const result = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" });
+    if (result.status !== 0)
+        return null;
+    return result.stdout.trim();
+}
+export function getGitHeadSha(cwd) {
+    const result = spawnSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8" });
+    if (result.status !== 0)
+        return null;
+    return result.stdout.trim();
+}
+export function getToolVersion() {
+    const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return pkg.version;
+}
+/**
+ * The base directory that relative claim paths (and default command cwd) resolve against:
+ * the directory containing the manifest, or its parent when the manifest lives under a
+ * ".verity" directory (so the base is the repo root, not the ".verity" dir itself).
+ */
+function resolveBaseDir(absManifestPath) {
+    const manifestDir = dirname(absManifestPath);
+    return basename(manifestDir) === ".verity" ? dirname(manifestDir) : manifestDir;
+}
+export function verify(manifestPath, cwd = process.cwd()) {
+    const absManifestPath = resolve(cwd, manifestPath);
+    const manifest = loadManifest(absManifestPath);
+    const base = resolveBaseDir(absManifestPath);
+    const repoRoot = getRepoRoot(base);
+    const results = manifest.claims.map((claim) => runClaim(claim, { cwd: base, repoRoot }));
+    const report = {
+        version: getToolVersion(),
+        timestamp: new Date().toISOString(),
+        gitHeadSha: getGitHeadSha(base),
+        results,
+    };
+    const exitCode = results.every((r) => r.verdict === "PASS") ? 0 : 1;
+    return { report, exitCode };
+}

package/docs/spec.md

@@ -0,0 +1,149 @@
+# Claims manifest format (v0.1)
+
+This document specifies the `.verity/claims.json` format and the deterministic
+verification behavior of `verity verify`. The format version below (`"0.1"`)
+is independent from the package version.
+
+## Purpose
+
+A claims manifest declares specific, checkable assertions about a piece of
+work — files that should exist, content that should be present, work that
+should be committed, commands that should succeed. `verity verify` checks
+each claim against literal reality and reports a PASS/FAIL verdict per claim.
+
+## File location and base directory
+
+By convention the manifest lives at `.verity/claims.json`, but any path may
+be passed to `verity verify [manifestPath]`.
+
+All relative claim paths (and the default `cwd` for `command` claims) resolve
+against a **base directory**, computed from the manifest's own location: the
+directory containing the manifest file, or — if that directory is named
+`.verity` — its **parent** directory instead, so a manifest at
+`.verity/claims.json` resolves paths against the repo root, not against the
+`.verity/` directory itself. The process's current working directory is
+never used for path resolution, only the manifest's location.
+
+## Manifest shape
+
+```json
+{
+  "version": "0.1",
+  "claims": [
+    { "id": "string, unique within the manifest", "type": "...", "description": "optional" }
+  ]
+}
+```
+
+`claims` is an array of claim objects; each `id` must be unique in the manifest.
+
+## Claim types
+
+### `file_exists`
+
+Asserts a path exists, resolved against the base directory.
+
+- `path` (string, required)
+- `nonEmpty` (boolean, optional, default `false`) — also requires size > 0.
+
+PASS when the path exists (and, if `nonEmpty`, has size > 0). FAIL otherwise.
+
+### `file_matches`
+
+Asserts a file's content matches a `match` spec, resolved against the base.
+
+- `path` (string, required)
+- `match` (MatchSpec, required)
+
+PASS when the file exists and its content satisfies `match`. FAIL if missing
+or non-matching.
+
+### `git_committed`
+
+Asserts a path is committed at `HEAD`, verified via `git show HEAD:<path>`
+against the git repository containing the base directory — never the
+working tree.
+
+- `path` (string, required)
+- `match` (MatchSpec, optional) — matched against the **committed** content
+  from `git show`, not the working-tree file.
+
+PASS when `git show HEAD:<path>` exits 0 (and, if `match` is present, the
+committed content satisfies it). FAIL if there is no enclosing repository,
+the path is not committed at `HEAD`, or the match fails.
+
+### `command`
+
+Runs a shell command and asserts its outcome.
+
+- `run` (string, required) — executed via the platform shell.
+- `cwd` (string, optional) — defaults to the base directory; resolved
+  against the base directory when given.
+- `timeoutMs` (number, optional, default `60000`).
+- `expect.exitCode` (number, optional, default `0`).
+- `expect.stdout` (MatchSpec, optional).
+
+PASS when the command exits within the timeout with the expected exit code
+and (if given) `stdout` satisfies `expect.stdout`. FAIL on a non-matching
+exit code, non-matching stdout, or a timeout (process is killed, claim FAILs).
+
+## The match object (`MatchSpec`)
+
+```json
+{ "kind": "substring" | "regex" | "sha256", "value": "string", "flags": "optional string" }
+```
+
+- `substring` — PASS if `value` is found anywhere in the content.
+- `regex` — PASS if `new RegExp(value, flags)` matches. `flags` are standard
+  JavaScript regex flags (e.g. `"m"`, `"i"`).
+- `sha256` — PASS if the SHA-256 digest of the content, as lowercase hex,
+  equals `value` compared case-insensitively.
+
+## Exit codes
+
+- `0` — manifest loaded and every claim PASSed.
+- `1` — manifest loaded and at least one claim FAILed.
+- `2` — usage error: manifest not found, invalid JSON, a schema violation,
+  or an unknown claim type.
+
+## The receipt
+
+Every `verity verify` run writes a JSON receipt to
+`.verity/reports/<ISO-timestamp>.json` (under the process's current working
+directory), regardless of `--json`. `--json` also prints the same JSON to
+stdout instead of the human-readable summary.
+
+```json
+{
+  "version": "package version of the verity binary that produced the report",
+  "timestamp": "ISO 8601 timestamp",
+  "gitHeadSha": "string | null (best-effort, null if not inside a git repo)",
+  "results": [
+    {
+      "id": "string",
+      "type": "file_exists | file_matches | git_committed | command",
+      "subject": "the path or command the claim is about",
+      "predicate": "human-readable description of what was checked",
+      "verdict": "PASS | FAIL",
+      "evidence": "human-readable evidence for the verdict"
+    }
+  ]
+}
+```
+
+The `subject` / `predicate` / `evidence` / `verdict` vocabulary is borrowed
+from in-toto attestation terminology for interoperability — a naming
+convention, not a claim of in-toto compliance.
+
+## Versioning
+
+Format version `0.1` and its `0.x` successors are additive: new optional
+fields and new claim types may be added without a major bump. An unknown
+claim type is a usage error (exit code `2`), not a silently skipped claim.
+
+## Determinism guarantees
+
+Verification is local and offline: no network calls, no LLM involvement.
+Given the same manifest and the same filesystem/git/command state, `verity
+verify` produces the same verdicts every time. `command` claims are exactly
+as deterministic as the command being run.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@pietro-falco/verity",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Turn your coding agent's 'done' into a receipt you can check — deterministic, local, zero-dependency.",
+  "bin": {
+    "verity": "dist/cli.js"
+  },
+  "main": "dist/verify.js",
+  "types": "dist/verify.d.ts",
+  "files": ["dist", "SKILL.md", "docs/spec.md"],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test",
+    "prepare": "tsc"
+  },
+  "keywords": [
+    "ai-agents",
+    "coding-agents",
+    "verification",
+    "guardrails",
+    "claude-code",
+    "evidence",
+    "receipt",
+    "cli",
+    "deterministic"
+  ],
+  "author": "Pietro Falco <pietrofalco.dev@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pietro-falco/verity.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pietro-falco/verity/issues"
+  },
+  "homepage": "https://github.com/pietro-falco/verity#readme",
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "@types/node": "^26.1.0"
+  }
+}