Repository navigation
Conversation
Every evidence record now carries two new fields at write time:
prev_hash - sha256 of the most recent record in the same
.ai-engineering/evidence/ directory (or 64 zeros for
an empty chain)
hash - sha256 of the canonicalised record (sort keys, compact
separators), with 'time' and 'hash' fields excluded so
wall-clock jitter cannot fork the chain and the field
that carries the digest cannot hash itself
Why this matters
The chain head is a single 64-hex commitment to the entire audit
history of a repo. Any past edit that does not also re-write all
downstream records breaks at the prev_hash link. The chain is
reproducible: starting from an empty directory and feeding the same
inputs produces the same head. It costs ~1ms per verify on a modern
machine, uses only stdlib (hashlib + json), and survives forward
schema drift because every audit tool recomputes from the file each
time.
This is the substrate that turns an evidence directory into an
immutable, externally-verifiable log. Once it lands, every other
repo in the org (repotruth, mcp-regression-lab, terminal221b, the
org website) can check the chain without trusting harness to have
done it right.
Files
- harness/chain.py (new, 56 lines): evidence_hash() and
prev_evidence_hash(). Total contract — never raises; missing
directory / unparseable records / non-JSON-native values all
fall through to defined values.
- harness/verify.py:cmd_verify — sets ev['prev_hash'] and
ev['hash'] immediately before write_evidence. Six lines.
- harness/runner.py:_verify_run — same wiring for the parallel
runner path used by 'harness serve'.
- tests/test_chain.py (new, 14 tests): shape, determinism,
time-exclusion, prev_hash resolution, parseable-record selection,
end-to-end chain advancement, and the two adversarial cases
(silent historical edit and middle insertion).
Tests
uv run pytest -q tests/test_chain.py -> 14 passed
uv run pytest -q (full suite) -> 103 passed
uv run ruff check harness/ tests/... -> clean
uv run mypy harness/ -> no issues
Out of scope
- Adversarial chain validation tool (repotruth audit-evidence,
Phase 4).
- Embedding the chain head into a public feed (Phase 5/Quattro-Commas.github.io).
- Reporting the chain head on the harness dashboard.
BoozeLee
added a commit
to Quattro-Commas/Quattro-Commas.github.io
that referenced
this pull request
Oct 11, 2026
Pulls a real Groq review against this org (Oct 11) and keeps only the moves that survive constraint checking (no new silo, no GPG, no S3). Names one shippable move per repo (harness: hash chain — already landed as Quattro-Commas/harness#12), one cross-cutting compound (every repo becomes a viewer of the chain), and one impossible-without-breaking- public-surface (a federation repo).
This branch has not been deployed
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.
What this PR adds
A deterministic SHA-256 chain over the evidence directory. Two new fields land on every
evidence/<task>.jsonat write time:{ "task": "…", "goal": "…", "verdict": "PASS", "results": [ … ], "prev_hash": "abc… (sha256 of the most recent prior record, or 64 zeros)", "hash": "def… (sha256 of the canonicalised record, excluding time+hash)" }The chain is reproducible, append-only in spirit, and stands up to silent edits: any past edit that does not also re-write all downstream records breaks at the next
prev_hashlink.Why it crosses the bar
This is the substrate that turns evidence into an externally-verifiable, tamper-evident log without introducing any new dependency (only stdlib's
hashlibandjson) and without changing any external schema. Once it lands:repotruthcan audit evidence integrity by recomputing the chain.mcp-regression-labcan replay only records whose chain is intact.terminal221bcan sign approvals asapproval_for: evidence_hash.Quattro-Commas.github.iocan render the chain head as a public heartbeat.Today every other audit tool in the org has to trust harness's evidence directory. After this lands they re-derive the chain themselves.
Files
harness/chain.py(new)evidence_hash(ev) -> str(SHA-256, stdlib only) andprev_evidence_hash(root) -> str(most-recent record bytime, falling back to mtime, then 64-zero sentinel). Total contract — never raises.harness/verify.pycmd_verifywritesprev_hash/hashimmediately beforewrite_evidence.harness/runner.py_verify_runfor parity withharness serve.tests/test_chain.py(new)Tests
Behaviour change
evidence/*.jsonfiles gain two top-level fields (prev_hash,hash). Existing readers ignore unknown keys — no schema bump. The hash itself is stable across runs of the same evidence: same canonical form, same SHA-256.Out of scope (later phases)
repotruth audit-evidence <file>to validate a single record's chain membership.reproblock (independent dimension of reproducibility).Acceptance
A reviewer can run:
…and verify that
hash == sha256(canonical(record without time|hash))for every file, and thatprev_hashof record N equalshashof the most recent record at the time N was written. The hash chain itself is inspectable fromgitalone; no external tooling is required.