diff --git a/docs/concepts.md b/docs/concepts.md index 1cac6c0..1a3ebfd 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -3,9 +3,13 @@ ## Ship Receipts A **Ship Receipt** is a small, verifiable record of shipped work: artifact + verify hooks + provenance. -Public integration today: +Public integration example today: - https://github.com/Spitfire-Cowboy/ship-receipts +Proof of Ship does not require `ship-receipts` specifically. Any upstream tool +that emits the public proof-envelope contract can submit for independent +verification. + ## Diminishing Returns (DR) A lightweight “stop/ship” signal for multi-agent or long conversations. diff --git a/docs/specs/proofofship-roadmap-v1.md b/docs/specs/proofofship-roadmap-v1.md index dd96ff9..d45935d 100644 --- a/docs/specs/proofofship-roadmap-v1.md +++ b/docs/specs/proofofship-roadmap-v1.md @@ -7,7 +7,7 @@ This roadmap defines the phased build plan for proofofship as a global verificat - **ship-receipts** (~/Projects/ship-receipts): Local receipt generator. Creates verifiable records of shipped work per-repo. Does not compute reputation. - **proofofship** (~/Projects/proofofship): Global verification and reputation registry. Aggregates receipts from any conformant source, verifies independently, and publishes public trust surfaces. -Ship-receipts is the first integration. Not the only one. +Ship-receipts is the first documented integration example. Not the only one. ## Phase 0: Spec + Foundation (Current) - Define architecture: registry-first model @@ -30,7 +30,8 @@ Ship-receipts is the first integration. Not the only one. - Implement receipt query endpoint (GET /api/v1/receipts/:id) - Implement account endpoint and public-repo linking endpoints -**Exit criteria:** Can submit a receipt from ship-receipts, verify it, and retrieve it via API. +**Exit criteria:** Can submit a receipt from at least one conformant producer, +verify it, and retrieve it via API. ## Phase 2: Reputation Engine - Implement reputation score computation @@ -77,21 +78,34 @@ Ship-receipts is the first integration. Not the only one. - Pull/crawler-based ingestion - Federation with other verification systems -## ship-receipts Integration Requirements +## Example producer integration requirements -For ship-receipts to integrate with proofofship: +For any upstream producer to integrate with proofofship: -1. **Schema conformance:** ship-receipts must emit receipts matching the proofofship ingestion schema (schema_version, source_type, actor, artifact, evidence, submitted_at) -2. **Push mechanism:** ship-receipts adds a `proofofship push` command or post-commit hook that submits receipts to POST /api/v1/receipts -3. **Authentication:** ship-receipts stores a GitHub OAuth token for the actor (or prompts for auth on first push) -4. **No hard coupling:** ship-receipts continues to work standalone. Proofofship push is opt-in. -5. **Evidence payload:** ship-receipts populates the evidence field with session-specific data (session_id, diminishing_returns_signal, files_changed, tests_passed, etc.). Proofofship treats this as opaque but stores it. +1. **Schema conformance:** the producer must emit receipts matching the + proofofship ingestion schema (schema_version, source_type, actor, artifact, + evidence, submitted_at) +2. **Push mechanism:** the producer may add a `proofofship push` command, + webhook, or other submission path to `POST /api/v1/receipts` +3. **Authentication:** the producer must have a way to associate the submission + with the actor's authenticated session or equivalent identity proof +4. **No hard coupling:** the producer continues to work standalone. Submission + to proofofship remains optional. +5. **Evidence payload:** the producer may include session-specific evidence + fields. Proofofship treats this payload as opaque input for verification and + audit, not as self-authenticating truth. + +For the current `ship-receipts` integration specifically: + +- it is one producer that can satisfy the contract above +- it remains a local evidence tool, not the global verifier +- it is not a privileged upstream requirement for the Proof of Ship protocol ## Key Milestones | Milestone | Description | Phase | |-----------|-------------|-------| -| First verified receipt | End-to-end: ship-receipts -> proofofship -> verified | Phase 1 | +| First verified receipt | End-to-end: conformant producer -> proofofship -> verified | Phase 1 | | First reputation score | Score computed from verified receipts | Phase 2 | | First public profile | /u/ live and readable | Phase 3 | | Semantic search live | "Find work like X" queries work | Phase 4 | diff --git a/docs/specs/proofofship-verifier-architecture-v1.md b/docs/specs/proofofship-verifier-architecture-v1.md index d19e925..f496049 100644 --- a/docs/specs/proofofship-verifier-architecture-v1.md +++ b/docs/specs/proofofship-verifier-architecture-v1.md @@ -200,3 +200,7 @@ The scorer answers: “How much does that confidence contribute right now?” Proof of Ship always re-verifies from scratch against public evidence. That firewall is the core trust property of the system. + +More generally: the verifier depends on the public envelope and evidence +contract, not on one privileged producer. `ship-receipts` is an example +upstream source, not a mandatory one. diff --git a/docs/web/site/index.html b/docs/web/site/index.html index 19c98f8..7aa1f48 100644 --- a/docs/web/site/index.html +++ b/docs/web/site/index.html @@ -232,17 +232,17 @@

GitHub auth + linked repos

Two tools, one trust boundary

-

ship-receipts records evidence. Proof of Ship re-verifies everything.

-

The local tool and the global verifier are intentionally separate. ship-receipts owns repo-local evidence capture. Proof of Ship owns independent verification and the public trust surface.

+

Local evidence tools record proof. Proof of Ship re-verifies everything.

+

The local tool and the global verifier are intentionally separate. `ship-receipts` is the first documented evidence producer, but any conformant upstream tool may submit the same proof-envelope contract. Proof of Ship owns independent verification and the public trust surface.

-

ship-receipts

+

Example local producer

  • • local evidence recorder
  • • single-repo scope
  • • generates proof envelopes
    • -
  • • owns repo-local evidence capture
    • +
  • • ship-receipts is the first documented example
  • • does not verify or score globally