Repository navigation
docs(decisions): add ADRs 0079/0080 for caller-specified build source ref and verification binding - #83
Merged
Conversation
Decide that every producer profile supports an optional, tags-only `source-ref` input as the default fixed-pipeline release-retry path, with the JS/TS npm package profile as the first adopter. Partially supersedes ADR 0032's invocation-ref requirement for manual dispatch; the version-tag convention, tag-mutation prohibition, rerun semantics, and already-published failure behavior remain in force. The verification binding model is deliberately deferred to a follow-up ADR; this ADR alone changes no observable verification behavior. Related: #81 Signed-off-by: Yunseo Kim <git@yunseo.kim>
Complete the two-ADR split begun by ADR 0079: bind verifier source expectations (repository, tag ref, commit SHA) to the signed provenance fields, and redefine the certificate Source Repository Digest/Ref extensions as invocation-context evidence cryptographically bound to a signed invocation record. Partially supersedes ADR 0068 clause 4; the issuer, signer workflow, repository identity (including numeric IDs), run identity, and runner trust bindings remain in force. Omitted-`source-ref` flows remain byte-compatible with the pre-existing contract. Related: #81 Signed-off-by: Yunseo Kim <git@yunseo.kim>
Add the reverse relation edges required by ADR 0065 (ADR 0032 partially-superseded-by ADR 0079; ADR 0068 see-also ADR 0079 and partially-superseded-by ADR 0080; ADR 0026 see-also ADR 0079) and register both ADRs in the decisions and architecture README inventory and traceability tables, in English and Korean. Only frontmatter relations fields change on existing ADRs; accepted bodies are unchanged. Signed-off-by: Yunseo Kim <git@yunseo.kim>
20 of 30 tasks
yunseo-kim
added a commit
that referenced
this pull request
Aug 13, 2026
…tion binding (#84) ## Summary Specifies the accepted decisions from ADR 0079 (tags-only `source-ref` input across profiles) and ADR 0080 (B-1 source-identity binding model) in the architecture specs and bilingual READMEs. Documentation/specification only, except for one consistency-gate-driven registration: the diagnostic registry gains the spec-mandated `windlass.verify.error.source-ref-invalid` ID (registration only, no emission sites — the `mutation-queue-overflow` precedent). - What changed? - **Core profile contract**: new "Built source identity" invariant — every producer profile offers the tags-only `source-ref` input, runtime release guards evaluate the built ref, the resolved commit travels through the digest-verified handoff, and provenance records the built identity plus a signed invocation record when the two contexts differ. - **npm package profile**: ninth public input (tags-only full-ref form, fail-closed existence/resolution/version-match checks, tag-trigger conflict rejection), runtime guards and concurrency keys re-anchored on the built release tag, new pre-mutation diagnostic `windlass.verify.error.source-ref-invalid`, and dispatch-retry/single-identity fixtures. - **npm provenance and publish**: conditional `input_ref`, `invocation_ref`, and `invocation_revision` members in the closed source group (omitted-input bundles stay byte-identical), nine-input completeness mapping, signer-identity table rebound so policy binds the signed built-source fields and certificate source claims bind the signed invocation record. - **Common contracts** (`slsa-provenance-v1`, `identity-and-buildtypes`, `verification-policy-and-fixtures`): two-identity model — policy `source.digest`/`source.ref` expectations bind signed built-source fields; certificate Source Repository Digest/Ref extensions bind the signed invocation record; `source-digest-mismatch`/`source-ref-mismatch` diagnostics redefined accordingly. - **READMEs** (bilingual): optional input count 8→9, dispatch-retry capability in Features, two-identity verification model, new Strengths item, and the predecessor ecosystem's never-shipped dispatch tag identity in the alternatives comparison (slsa-github-generator#1947, osv-scanner#632, #81). - **Spec inventory** (`docs/architecture/README*.md`): ADR 0079/0080 registered in per-spec source ADR lists; repaired the identity spec row's pre-existing omission of ADR 0068. - **Diagnostic registry**: `windlass.verify.error.source-ref-invalid` registered (pre-mutation, exit 1, `mutation_possible: false`) to satisfy the spec↔registry consistency gate (`TestRegistryMatchesSpecTaxonomy`); closed-registry count updated 155→156. No emission sites — those land with the implementation. - Why is this needed? Issue #81 showed release retry was structurally impossible: the workflow builds `github.ref`, and the verification policy compared certificate source claims against the release tag — conflating the invocation context with the built source at three layers (ADR 0032 dispatch restriction, spec byte-equality, certificate binding). ADRs 0079 and 0080 resolve this; this PR makes the specs match the decisions. ## Related Issues - Related #81 (root cause addressed in specs; issue closes when the implementation lands) - Related #22 ## Change Type - [ ] Bug fix - [x] Feature (diagnostic ID registration only) - [ ] Refactor - [x] Documentation - [ ] Test/CI - [ ] Breaking change - [ ] Other: <!-- describe --> ## Changelog - Category: Added - User-facing note: Specified the optional tags-only `source-ref` input for dispatch-driven release retry, the nine-input npm profile contract, and the ADR 0080 verification binding model. Changelog update: - [x] `CHANGELOG.md` `[Unreleased]` updated - [ ] Not needed because this change is not user-facing ## Checklist ### General - [x] PR title follows [Conventional Commits](https://www.conventionalcommits.org/) format: `type(scope): Summary` - [x] This PR does not expose backend/internal implementation details in a public repo. - [x] No secrets, tokens, keys, or private endpoints are included. - [x] Changes stay within this repository's intended scope. ### CI/Workflow Changes (if applicable) No workflow or CI/CD changes in this PR. ### Protocol / Compatibility Impact - [ ] No protocol/spec impact - [x] Protocol/spec updated - [ ] Conformance tests updated - [ ] Breaking change is versioned and migration notes are included If impacted, describe compatibility impact: Additive spec change. The `source-ref` input is optional; when omitted, the signed source group is byte-identical to the current single-identity contract, so existing producers and verifiers are unaffected. The verification binding redefinition (policy binds signed built-source fields; certificate source claims bind the signed invocation record) takes effect only when `source-ref` is supplied. Code fixtures and conformance tests follow in the implementation PR. ## Testing - [x] Unit tests added/updated (closed-registry count and taxonomy gate) - [ ] Integration or conformance tests added/updated - [x] Tests pass - [x] Lint and format pass - [x] Type check passes - [x] Manual verification performed Describe test evidence: `go test ./...` passes locally (all packages, including `TestRegistryMatchesSpecTaxonomy` and `TestClosedRegistryAndContractValidation` with the new ID). Lefthook gates (prettier, markdownlint, golangci-lint, DCO) pass on every commit; `check_relations.py` passes (81 ADRs, 172 edges) since ADR relations landed in PR #83. Specification fixtures (`dispatch-retry-success`, `single-identity-default`) are named contracts for the implementation phase. ## Documentation - [x] README updated - [x] Spec/docs updated - [x] Changelog decision completed above ## Rollout / Risk - Risk level: Low - Rollback plan: Revert the merge commit; specs and READMEs return to the pre-ADR-0079/0080 wording and the registry drops the unused ID. No runtime or workflow behavior changes (the new ID has no emission sites). ## Reviewer Checklist - [x] Scope is clear and minimal - [x] Security and boundary checks passed - [x] Tests and docs are sufficient - [x] Compatibility impact is correctly handled --------- Signed-off-by: Yunseo Kim <git@yunseo.kim>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds two accepted architecture decision records that together resolve the release-retry dead end reported in #81 (a failed tag release cannot be retried with a fixed pipeline because the built source identity is bound to the invocation ref):
source-refinput as the default release-retry path (JS/TS npm profile first adopter). When supplied onworkflow_dispatch, the invocation ref may carry a fixed pipeline (e.g.main) while the built/attested content must remain the version tag. Partially supersedes ADR 0032's invocation-ref requirement only; tag immutability, version-tag matching, rerun semantics, and already-published failure behavior are preserved.source-refflows stay byte-compatible with the current contract.A third commit records the ADR 0065-required reverse relation edges (ADRs 0026/0032/0068 frontmatter only — accepted bodies untouched) and registers both ADRs in the English/Korean decisions and architecture README inventory and traceability tables.
How to test: docs gates —
pnpm exec prettier --check "docs/**/*.md",pnpm exec markdownlint-cli2 "docs/**/*.md", andpython3 .agents/skills/adr-relations-check/scripts/check_relations.py(81 ADRs, 172 edges, no problems). All pass.No observable behavior changes: ADR 0080 gates implementation, and no specification or workflow content is modified by this PR.
Related Issues
Change Type
Changelog
source-refcapability and the new binding model take effect only through later specification and implementation PRs gated by ADR 0080.Changelog update:
CHANGELOG.md[Unreleased]updatedChecklist
General
type(scope): SummaryCI/Workflow Changes (if applicable)
N/A — no workflow or CI/CD changes.
uses:references are pinned to full 40-character commit SHAs (with# vX.Y.Zcomment)step-security/harden-runneris included as the first step in every jobpermissionsare used instead of top-levelpermissionsProtocol / Compatibility Impact
If impacted, describe compatibility impact: None in this PR. ADR 0079/0080 decisions will drive specification updates (profile input contract, provenance signer-identity sections, verification policy) in follow-up PRs; ADR 0080 explicitly preserves byte compatibility for all flows where
source-refis omitted.Testing
Describe test evidence: Docs-only change.
prettier --checkandmarkdownlint-cli2clean;check_relations.pyreports 81 ADRs / 172 edges with no problems (relations symmetry and closed status grammar verified). Lefthook pre-commit (prettier, markdownlint) and commit-msg DCO checks passed on all three commits.Documentation
Rollout / Risk
Reviewer Checklist