repo-proof-index 0.1.1

Reviewer-ready index CLI for proof packets, receipts, and JSON contracts

repo-proof-index

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.

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, and where the evidence lives.

Install

python -m pip install repo-proof-index

For local development:

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

Usage

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.

What it indexes

Known shapes:

• proof-surface interop packets with proof_surface_version and packet_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

Output fields

Field	Meaning
kind	Best-effort contract type.
surface	Product, language, witness implementation, root, or contract name.
status	Status, maturity, verdict, or fallback status.
evidence	Short evidence summary from verification, claims, notes, or backend counts.
path	Source JSON path in JSON mode.

Release summary mode

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.

total: 3
kinds: backend-capability=1, product-use-case=1, witness-receipt=1
statuses: MATCH=1, backend-matrix=1, release-candidate=1
evidence_gaps: 0
action_items:
- none

Example table output

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

Example JSON output

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

What it does not do

• 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 decide whether a claim is true.
• It does not replace tests, audits, or release review.

Release-readiness use

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.

Proof-surface interop packet

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

Research harness

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.

Authorship

Created and maintained by Zain Dana Harper. Claude Code contributed to the initial implementation.