Index proof packets, receipts, and contracts into reviewer summaries.

python -m pip install -e ".[test]"

Repo Proof Index scans proof artifacts and returns the compact view a maintainer needs before release review: kind, surface, status, evidence summary, and source path. It indexes evidence; it does not decide whether the evidence is enough.

The animated explainer walks through the four bundled proof artifacts indexed into one table, the difference between a declared and a verified status, the summary's action items, packet validation, and the strict JSON reader's rejections. Every value on it is output from this repository. Its source is docs/explainer/index.html.

Install it, run it once, then use the main feature. Each command below is real, and so is its output.

1. Install. Install from PyPI and clone for the examples. Python 3.10 or newer.

   $ python -m pip install repo-proof-index
   $ git clone https://github.com/HarperZ9/repo-proof-index && cd repo-proof-index
   

2. First run: index one record. Read one proof record and report its kind and verification state.

   $ repo-proof-index examples/contracts/sample-witness-receipt.json --json
   "kind": "witness-receipt"
   "status": "MATCH"
   "producer_status": "MATCH"
   "verification_state": "not_assessed"
   

3. Summarize a folder. Count records by verification state.

   $ repo-proof-index examples/contracts/*.json --summary
   total: 4
   kinds: backend-capability=1, product-use-case=1, proof-surface-packet=1, witness-receipt=1
   statuses: MATCH=1, backend-matrix=1, needs-polish=1, release-candidate=1
   verification_states: not_assessed=3, not_verified=1
   evidence_gaps: 0
   action_items:
   - proof-surface-public-release-demo: resolve needs-polish
   

4. A malformed record is rejected. A file with a duplicate key is refused.

   $ repo-proof-index dup.json
   error: duplicate JSON key: status
   

As a repo gains receipts and proof packets, reviewers need a fast way to find what each artifact claims and where the evidence lives. This tool makes that proof layer navigable.

python -m pip install -e ".[test]"
repo-proof-index examples/contracts/*.json --summary
python -m pytest

• Index the bundled example contracts.
• Run repo-proof-index --root . in a repo with proof artifacts.
• Use --validate on a proof-surface packet.

Python package and CLI with tolerant JSON parsing and proof-surface integration. It produces review indexes and summaries, not compliance findings.

Reviewer-ready index over proof packets and receipts -- indexes the evidence; does not decide if it is enough.

repo-proof-index turns scattered proof artifacts into a reviewer-readable index. Feed it JSON proof contracts, proof-surface packets, witness receipts, and backend descriptors; it returns the compact view a maintainer needs before a release-readiness or diligence handoff.

The parser is intentionally schema-tolerant. Unknown contract shapes still get best-effort identifiers, status, surface, evidence, and source path fields. The JSON reader is strict before that shape-tolerant layer runs: duplicate keys, non-finite values such as NaN, Infinity, and overflowing floats, files over 1,048,576 bytes, and JSON nesting deeper than 200 levels are rejected for both indexing and proof-surface validation.

Use it when a repo or workspace has proof artifacts but no quick way to see what they claim, what surface they describe, what status they report, whether Repo Proof Index verified that status, and where the evidence lives.

python -m pip install repo-proof-index

For local development:

python -m pip install -e ".[test]"
python -m pytest

See USAGE.md for a full usage guide with worked examples and expected output. A quick tour follows.

Index explicit JSON files:

repo-proof-index contracts/*.json
repo-proof-index contracts/*.json --json
repo-proof-index contracts/*.json --summary
repo-proof-index contracts/*.json --summary --json
repo-proof-index --validate examples/contracts/proof-surface-packet.json
repo-proof-index --validate examples/contracts/proof-surface-packet.json --json

Index the common workspace location:

repo-proof-index --root .

Use a custom contracts directory:

repo-proof-index --contracts-dir project-docs/contracts

Run the bundled quick demo:

repo-proof-index examples/contracts/*.json

Malformed input example:

repo-proof-index examples/malformed/not-object.json

Expected behavior: the command prints an error: line and exits with status 1 instead of producing a proof row.

Known shapes:

• proof-surface interop packets with proof_surface_version and packet_id
• proof-surface research-claim packets with version: research-claim-proof-packet/v0
• ORCA organ exchange artifacts from orca.module.organ_exchange.bundle
• proof-surface organ receipt bundles with organ_bundle_version and bundle_id
• product use-case manifests with manifest_id and product
• backend capability descriptors with descriptor_id and backends
• witness receipts with receipt_id and verdict
• generic JSON contracts with common fields such as id, report_id, manifest_id, descriptor_id, status, maturity, verdict, claims, verification, and notes

Default discovery path when explicit files are omitted:

project-docs/roadmaps/contracts/*.json

Repo Proof Index never executes packet-supplied verifier commands and never treats a claimed command, source hash, or passing check as semantic proof. The status field stays backward-compatible and producer-reported. The verification_state field records the indexer's own role.

For proof-surface v0.1 packets and research-claim packets, verification_state is not_verified: the indexer can validate shape, read reported verdicts, and summarize pointers, but it has not re-run Crucible, opened referenced evidence, or decided claim truth. A packet that says ready, MATCH, pass, or verified while remaining not_verified is placed on the summary action list as a producer-declared green row that needs an external verifier. A regression would be a self-declared ready/MATCH packet disappearing from action_items without an independently recorded verification state.

Use --summary when a reviewer needs the portfolio-level signal instead of row-by-row detail. The summary reports total artifacts, kind counts, status counts, evidence-gap count, and the first actionable rows that need stronger proof.

Running it over the bundled example contracts:

repo-proof-index examples/contracts/*.json --summary

total: 4
kinds: backend-capability=1, product-use-case=1, proof-surface-packet=1, witness-receipt=1
statuses: MATCH=1, backend-matrix=1, needs-polish=1, release-candidate=1
verification_states: not_assessed=3, not_verified=1
evidence_gaps: 0
action_items:
- proof-surface-public-release-demo: resolve needs-polish (examples/contracts/proof-surface-packet.json)

kind                   | surface                | status             | evidence
---------------------- | ---------------------- | ------------------ | ------------------------------------------------------------------------
product-use-case       | sample-tool            | release-candidate  | pass: example tests passed
witness-receipt        | sample-witness         | MATCH              | sample receipt available
backend-capability     | rust                   | backend-matrix     | pass=1, planned=1

[
  {
    "contract": "product-usecase-build-ui",
    "kind": "product-use-case",
    "surface": "build-ui",
    "status": "private-gated",
    "evidence": "pass: 17 tests passed",
    "path": "contracts/build-ui.json",
    "producer_status": "private-gated",
    "verification_state": "not_assessed"
  }
]

• It does not validate a JSON Schema.
• It does not certify that evidence is sufficient.
• It does not read private payloads referenced by a contract.
• It does not execute packet-supplied verifier commands.
• It does not decide whether a claim is true.
• It does not replace tests, audits, or release review.

repo-proof-index is the evidence assembly point in a proof-surface pipeline:

contracts and receipts -> proof index -> report -> reviewer handoff

Its job is to make proof artifacts visible enough for a maintainer, reviewer, client, or employer to see what exists and what still needs a stronger gate.

The schemas/proof-surface-packet.schema.json file defines a small shared packet for release-readiness evidence. It is intentionally neutral: independent tools can publish claims, checks, and action items without asking any one tool to become the authority.

surface claim -> evidence pointer -> check result -> action item

repo-proof-index recognizes these packets as proof-surface-packet rows, sets verification_state to not_verified, and summarizes their claim, check, and action counts. See examples/contracts/proof-surface-packet.json and docs/PROOF-SURFACE-INTEROP.md. The current version and known producer/consumer registry lives at docs/PROOF-SURFACE-REGISTRY.json.

Validate packet shape locally:

repo-proof-index --validate examples/contracts/proof-surface-packet.json

The validator is intentionally strict for the v0.1 contract: unexpected root, claim, or check fields are reported as errors instead of silently drifting the interop shape.

Export the portable contract bundle:

python scripts/export_proof_surface_contract.py --out dist/proof-surface-contract-v0.1

The draft research harness scores proof-surface cases across schema validity, evidence coverage, actionability, non-authority language, and witness/provenance presence.

python scripts/score_proof_surface_research.py

See docs/PROOF-SURFACE-RESEARCH-HARNESS-v0.1.md. Case contribution guidance lives at docs/PROOF-SURFACE-CASE-CONTRIBUTING.md.

Zain Dana Harper -- small tools with explicit edges. Portfolio · HarperZ9 _{Built with Claude Code; reviewed, tested, and owned by me.}

Keep the public README, package metadata, and examples aligned with current behavior. Before opening a PR or pushing a release, run the local package verification path.

python -m pip install -e ".[test]"
python -m pytest

Built by Zain Dana Harper in Seattle: evidence-first tools that leave a re-checkable artifact behind. The full workbench is at Project Telos.