Revision-identifiable review evidence
Revision-Identifiable Review Evidence
Status: Adopted. Designed under #34, and adopted into the canonical skills' record templates under #33. It implements item 6 of the #16 maintainer decision.
This document defines how a workflow record identifies the exact artifact it covers, and how it separates facts that can be checked from claims that cannot. The record templates in the canonical skills carry this format, and Agent #2 stops when valid Agent #1 completion evidence in this format is absent. Records use the resolved object name of the integration branch tip as integration_ref, never a bare branch name. garage status (#40) reports these records for one issue or pull request. It keeps the checked and asserted elements separate, compares recorded changesets, and recomputes a committed artifact only from objects already local. It never fetches, so it does not recompute in a partial clone.
What does not change
- The issue review stays authoritative. Agent #2's implementation review on the originating issue governs whether an implementation may advance. A PR review is supplemental. See GOVERNANCE: Review requirements. A digest identifies what a review covered. It does not create review authority, and it does not replace a review.
- Garage cannot certify separate execution contexts. GitHub shows who posted a comment, not which session produced it. On #17 and #25–#27, every Agent #1 and Agent #2 record was posted by the same account. Context separation is always recorded as an assertion. Nothing in this design verifies it, and no tool built on it may claim to.
- No orchestration. The design defines values that agents record and that a verifier can recompute. It does not assign, invoke, schedule, or wait for any agent.
Artifact identity: garage-artifact-v1
What is identified
An artifact is a change: the difference between a base commit B and a result tree T.
| Input | Working-tree artifact: an uncommitted change | Committed artifact: a pushed head H |
|---|---|---|
Integration reference I |
The project's configured integration branch tip, as fetched. Builder Garage: origin/main. |
Same |
Base B |
git merge-base I HEAD |
git merge-base I H before the PR opens and while it is open. After merge, git merge-base M^1 M^2, where M is the merge commit. |
Result tree T |
The working tree, staged into a temporary index (procedure below) | H^{tree} |
An artifact's stage is either working-tree or commit. The stage is set by what the reviewer inspects, not by where the record is posted:
- Working tree. An implementation reviewed on the issue before commit, which is the default. Also a correction that Agent #2 re-reviews on the PR before Agent #1 commits it (integration-pr-review: Artifact equivalence).
- Commit. A pushed PR head, such as one reviewed in a triggered PR review. Also an implementation or correction under commit-stage review: a pushed branch head that is not yet proposed for integration, reviewed on the issue so that a reviewer outside the implementer's workspace can recompute it (application-implementation-workflow: Commit-stage review).
For a working-tree artifact, the working tree is the artifact, because it is what the reviewer inspects. The developer's real index is never read or changed.
Recorded values
| Value | Definition |
|---|---|
method |
garage-artifact-v1 |
object_format |
The repository's object format: sha1 or sha256 (git rev-parse --show-object-format) |
base |
The full object name of B |
tree |
The full object name of T |
changeset |
sha256: followed by the lowercase hex SHA-256 of the exact bytes written by git diff-tree -r -z --raw --no-abbrev --no-renames B T |
paths |
The number of paths in that output (informational) |
The changeset digest hashes Git's raw change listing. For every changed path, that listing gives the old mode, new mode, old object name, new object name, status, and path, with NUL separators. Because each object name is a content hash, the digest binds the full content of every changed file without hashing patch text.
Equivalence
A PR head H is artifact-equivalent to an approved artifact A when changeset(H) equals A.changeset. This is the mechanical form of the rule in integration-pr-review: Artifact equivalence: the head's changed files and their content match the approved artifact exactly.
- When
Bis unchanged,treeequality is a stronger check and also holds. - After a rebase onto, or a merge of, integration commits that touch none of the artifact's paths,
treeandbasechange, butchangesetstays equal. The head is still equivalent. - If the integration branch changed a path the artifact also changes,
changesetdiffers. Equivalence is not shown, and minimum trigger 1 applies. This is intended: the approved change was reviewed against different content.
Edge cases
| Case | Behavior | Shown by |
|---|---|---|
| New untracked file | Included. git add -A in the temporary index stages it. |
Synthetic test, g.txt |
| Ignored file | Excluded, exactly as a commit would exclude it | Synthetic test, h.log |
| Binary file | Identified by its object name. Patch text plays no part. | Synthetic test, b.bin |
| Rename | Listed as a delete plus an add. --no-renames turns detection off, so the result never depends on a similarity threshold. |
Synthetic test, c.txt → c2.txt |
| Deleted file | New mode 000000 and the null object name |
Synthetic test, d.txt |
| Mode-only change | Captured by the mode columns | Synthetic test, e.sh, and a negative case |
| Line endings | The identity is of normalized repository content, as Git would commit it under the repository's .gitattributes and core.autocrlf. A working-tree change from LF to CRLF in a text=auto file is not a change. |
Synthetic test, f.txt |
| Index differs from working tree | The working tree wins, and the index is ignored | Synthetic test: a.txt staged, then edited again |
| Symbolic links and submodules | Covered by Git's own modes (120000, 160000) and object names |
Follows from the raw format; not separately exercised |
| Diff configuration | Has no effect. diff-tree is a plumbing command, and its raw output does not use diff algorithm, context, prefix, color, or rename settings. |
Synthetic test, seven configuration values |
| SHA-1 or SHA-256 repository | Supported. object_format is recorded so a verifier compares like with like. |
Only sha1 exercised |
| Sparse checkout | Not supported in v1. A temporary index built from HEAD would treat files outside the sparse set as deleted. The procedure refuses with an error. |
Refusal coded; not exercised |
| Squash or rebase merge, audited after merge | There is no merge commit whose parents give B. A post-merge audit must use the base in the approving record. |
Not exercised |
Why not hash the patch
Builder Garage's first informational digest, used on #18, was sha256(git diff --binary <base>). It reproduces at the PR stage only when every machine uses the same diff configuration. It also omits untracked files.
- The #18 change hashes to
7794ea3e…by that method. Withdiff.noprefix=true, the same change hashes to14d94019…. git diff <base>omits a new untracked file, so an approved change that adds a file would not be identified at the issue stage.
garage-artifact-v1 has neither weakness.
Reference procedure
This POSIX shell procedure is the reference definition. A Garage implementation must produce identical values. It runs from inside the repository.
#!/bin/sh
# garage-artifact-v1
# artifact-v1.sh <integration-ref> working-tree artifact (stage: working-tree)
# artifact-v1.sh <integration-ref> <commit> committed artifact (stage: commit)
set -eu
ref=$1
rev=${2:-}
if [ -n "$rev" ]; then
base=$(git merge-base "$ref" "$rev")
tree=$(git rev-parse --verify "$rev^{tree}")
else
if [ "$(git config --bool core.sparseCheckout || echo false)" = true ]; then
echo "garage-artifact-v1: sparse checkouts are not supported" >&2
exit 2
fi
base=$(git merge-base "$ref" HEAD)
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
GIT_INDEX_FILE="$tmp/index" git read-tree HEAD
GIT_INDEX_FILE="$tmp/index" git add -A
tree=$(GIT_INDEX_FILE="$tmp/index" git write-tree)
fi
changeset=$(git diff-tree -r -z --raw --no-abbrev --no-renames "$base" "$tree" | shasum -a 256 | cut -d' ' -f1)
paths=$(git diff-tree -r -z --name-only --no-renames "$base" "$tree" | tr -cd '\000' | wc -c | tr -d ' ')
echo "base=$(git rev-parse "$base") tree=$tree changeset=sha256:$changeset paths=$paths"
For a post-merge audit, pass the merge commit's first parent as <integration-ref> and its second parent as <commit>.
Demonstrated results
Against the real #18 change, reconstructed in a throwaway clone:
| Stage | base |
tree |
changeset |
|---|---|---|---|
Issue stage: base b871324, approved files uncommitted |
b8713248… |
b731c035f7ac5bec41d44a95622c593fad4796d2 |
sha256:45532f9d8c5763fda80a94867d7688680d48c5406325a51b89f8468927ddead0 |
PR stage: head ae2adf6 |
b8713248… |
b731c035… |
sha256:45532f9d… (identical) |
After merge: base from the parents of merge commit 9837e3e |
b8713248… |
b731c035… |
sha256:45532f9d… (identical) |
A synthetic throwaway repository exercised every case in Edge cases that is marked as shown. The working-tree and committed values matched. The changeset survived an unrelated rebase and a merge of the integration branch. A one-byte edit, a mode-only edit, an added file, and an integration change to a path the artifact also changes were each detected.
Evidence block: garage-evidence v1
A workflow record carries one fenced YAML block. The block separates values a verifier can recompute or confirm (checkable) from claims no verifier can confirm (asserted). The surrounding Markdown comment keeps its existing marker and human-readable sections.
Where each record lives
Location and links depend on the record type, as the canonical skills place each record. The location says nothing about the artifact's stage.
record |
Posted on | responds_to |
Other required links |
|---|---|---|---|
implementation |
The governing issue | — | — |
correction |
The governing issue, after an implementation review; or the PR, after a PR review (integration-pr-review: Current-PR correction) | — | — |
review |
The governing issue | An earlier Agent #1 implementation or correction record on the governing issue |
— |
pr-review |
The PR | An earlier record on the same PR for the reviewed artifact: the Agent #1 PR state record or Agent #2 PR Review Request for a triggered review, or the Agent #1 correction record for a correction re-review |
supplements: an earlier approving review record on the governing issue. A pr-review without one is invalid, because the issue review stays authoritative. |
equivalence |
The PR | — | equivalent_to: the approving review on the governing issue, or the approving pr-review on the PR, that the pushed head is equivalent to; none when equivalence is not shown, so minimum trigger 1 applies |
Agent #1 completion record
[AGENT #1 — IMPLEMENTATION]
```yaml
garage_evidence: 1
record: implementation # implementation | correction
issue: 34
checkable:
artifact:
method: garage-artifact-v1
object_format: sha1
stage: working-tree # working-tree | commit
integration_ref: <full object name of the integration branch tip>
base: <full object name>
tree: <full object name>
changeset: sha256:<64 hex>
paths: 1
asserted:
status: ready-for-review # ready-for-review | ready-for-re-review | material-blocker
validation_run: true # the listed validation was run; its output is not reproduced here
```
<existing human-readable sections>
Agent #2 review record
[AGENT #2 — INDEPENDENT REVIEW]
```yaml
garage_evidence: 1
record: review # review | pr-review
issue: 34
responds_to: "<URL of the record reviewed; see Where each record lives>"
supplements: "<pr-review only: URL of the approving review on the governing issue>"
checkable:
artifact: # recomputed by the reviewer from the artifact it inspected
method: garage-artifact-v1
object_format: sha1
stage: working-tree # working-tree | commit, by what was inspected, not by record type
integration_ref: <full object name of the integration branch tip>
base: <full object name>
tree: <full object name>
changeset: sha256:<64 hex>
paths: 1
commit: "<present only when stage is commit: the head reviewed>"
matches_responds_to: true # this artifact equals the one in responds_to
asserted:
execution_context: separate-from-implementation
inspected: complete-artifact
answers: {acceptance_criteria_met: true, new_regression: false, works: true}
verdict: approved # approved | changes-required
```
<existing human-readable sections>
Equivalence record on a PR
The artifact-equivalence record that Agent #1 posts for each pushed head carries the same block, with record: equivalence. Its checkable.artifact is computed at stage: commit for the pushed head. equivalent_to links the approving disposition: the issue review, or a pr-review that approved a PR-side correction.
What can be checked, and what remains asserted
| Element | Classification | How a verifier treats it |
|---|---|---|
| A record exists, its location (issue or PR), its author account, and its time | Checked from GitHub | Read from the API |
Record location and order, by record type (Where each record lives): the record is where its type belongs; responds_to is earlier and in the location its type requires; a pr-review's supplements is an earlier approving review on the governing issue |
Checked from GitHub | Compare locations, timestamps, and URLs |
| Block present and well formed | Checked | Parse the YAML |
Committed artifact (stage: commit), on any record |
Checked | Recompute from the repository at commit |
Working-tree artifact (stage: working-tree), whether recorded on the issue or on the PR |
Checkable only by a holder of the working tree at the time, such as Agent #2 recomputing it during review. Later it is checked transitively: the changeset of the pushed head whose equivalence record links the approval must equal it. | Compare with the equivalence record and the head |
matches_responds_to |
Checked by comparing the two records' changesets | Compare values; do not trust the boolean |
| CI results, maintainer approving review | Checked from GitHub | Read from the API |
| Role (Agent #1 or Agent #2) | Asserted. The marker is self-declared, and the author account may be shared. | Report as asserted |
| Separate execution context | Asserted. Never certified. | Report as asserted; never as verified |
| The three answers, verdict, and depth of inspection | Asserted judgment. A verifier confirms only that they are present. | Report as recorded, not as verified |
| Validation was run | Asserted unless reproduced, for example by CI | Report as asserted |
A verifier's output must keep these two columns visible. A "valid" result means only that every checkable element checked. It never means that independence was proven.
Compatibility
- Integration PR review. Changeset equality is the equivalence evidence
integration-pr-reviewasks Agent #1 to record. A head whose changeset differs from the latest approved artifact fires minimum trigger 1. Nothing about the two minimum triggers changes. - Developer-local history (#19). A local event's "artifact identity" field holds
method,base, andchangeset. These are object names and a digest, with no file content, so the #19 privacy rules are kept. Local events stay non-authoritative. - Project configuration (#35).
integration_refcomes from the configured integration branch (extension point E1 in the #16 report). - Records written before adoption. Free-text and patch-hash records, such as those on #18, remain valid historical evidence. A verifier reports them as
legacyand does not try to recompute them.
Not decided here
- Support for sparse checkouts, and post-merge audit of squash or rebase merges without a recorded
base.
