SummaryThe Deploy Is a Claim; the Endpoint Is Its Evidence
docs/decisions/D0002-attempt-provenance-required.md already mandates that every attempt capture provenance (agent, model, tool, git HEAD, timestamp) at registration. That closes the loop for attempts, but a deployed build — the thing a visitor or reviewer actually hits — makes no equivalent claim about itself. Without it, "what's live matches what was reviewed" is asserted, not verifiable.
This constraint proposes a small, standard surface: a build-provenance endpoint (e.g. /api/provenance or /.well-known/provenance) that every klappy.dev deploy serves, returning at minimum:
commit— the git SHA the build was produced frombuilt_by— identity (human or agent) that triggered the buildbuilt_at— build timestampattestation— how the claim is backed (CI run URL, signed manifest, or equivalent verifiable pointer)
This is the definition-of-done evidence requirement (canon/constraints/definition-of-done.md) applied to the deploy itself, not just the PR that produced it: a claim ("this build is X") paired with evidence a reader can fetch and check, not a description to be trusted.
Operating Constraints (proposed)
- MUST expose a stable, documented path returning
commit,built_by,built_at, andattestationfor the currently live build - MUST source these fields from the build/deploy pipeline itself, not from hand-edited config — the endpoint's value is that it can't drift from what actually shipped
- MUST NOT block or replace D0002's attempt-level provenance; this is a distinct, later checkpoint (attempt → merge → build → live), not a substitute
- SHOULD degrade the same way D0002 does: if a field is unknown, say so explicitly rather than omitting it silently
Ratified Answers (captain, 2026-07-19)
- Route/shape: per-service; extending an existing
/health-style endpoint is acceptable — the fields are the contract, not the path. (ARS does exactly this per its reliability inventory S4.) - Attestation: a CI run URL is the floor; a signed manifest is the stronger rung services may graduate to. Unknown fields degrade explicitly per the operating constraints.
- Scope: portfolio-wide (this ruling) — the
governsline above now binds every deployed service in the portfolio, each implementing locally.
Relationship
- Extends
klappy://docs/decisions/D0002-attempt-provenance-requiredfrom attempt-time provenance to deploy-time provenance — same evidence discipline, later checkpoint in the same pipeline. - Is a specific application of
klappy://canon/constraints/definition-of-done— the deploy is a claim, the endpoint is the evidence that lets a reader check it instead of trusting the pipeline's say-so.