Orchestrata Ultimate › Plans › briefs › 2026-10-13-adr-0101-precommit-stage-walls-ledger
Brief: ADR-0101 rule 2 — the real pre-commit hook records its stage walls to an append-only ledger
Source: plans/briefs/2026-10-13-adr-0101-precommit-stage-walls-ledger.md at 8a2cb42ad · last changed 2026-10-13 · first committed 2026-10-13 · 38 lines.
Prose pending.
Plan text
Brief: ADR-0101 rule 2 — the real pre-commit hook records its stage walls to an append-only ledger
Date: 2026-10-13 · DESIGN_WAIVER: ADR-0101 (Accepted 2026-10-13 21:05: scripts/hooks/pre-commit records one line per commit with the wall of each stage and the per-file reviewer walls inside review-staged; placement is decided on ten measured commits; the hook's exit code and verdict are unchanged) · Executor: Kimi in worktree /home/mohamed/workspace/orchestrata-ultimate-worktrees/adr-0101-hook-ledger on branch feat/adr-0101-precommit-walls-ledger off origin/master 9447d4fcc · Design settled below; if a fork appears, STOP and report.
GOAL: every git commit appends one JSON line to reports/precommit-walls.ndjson with the wall of the secrets check, the ruff stage and gate.py review-staged, and the wall of each reviewer per staged file inside review-staged, whether the commit passes or fails; nothing else about the hook changes.
VERIFIED (coordinator, origin/master 9447d4fcc):
scripts/hooks/pre-commitis the hookgit commitruns (ADR-0101 Context): stages are a secrets check,ruff --fixon staged files, and"$PY" scripts/gate.py review-staged(L85) whose exit is 0 pass / 1 fail / 2 invalid, with the block messages at L87-95.scripts/hooks/commit-msgis RUL-007 and is not touched.scripts/gate.py review-stagedrunsgates/commit_review.py, which runsscripts/code-review.pyandscripts/test-review.pyper staged file under a 600 s timeout each and derives the verdict insrc/orchestrata_ultimate/prolog/commit_review.pl.- Append-only ndjson files already exist under
reports/(container-cpu.ndjson,test-durations.ndjson,test-phase-durations.ndjson);.gitattributeshas nomerge=unionentry today (codetools uses one for its iteration log; the same attribute applies here). - Measured today on one builder commit: the full hook took 1 m 28 s with a cold mypy cache (MCP gateway hand-back, item 12); no per-stage numbers exist anywhere, which is the gap ADR-0101 rule 2 closes.
FILES (repo-relative): Modify:
- scripts/hooks/pre-commit — wrap each stage with a monotonic start/end; at the end (on every exit path, via
trap … EXIT) append one line toreports/precommit-walls.ndjson:{"ts": <iso8601>, "sha": "<HEAD or 'initial'>", "branch": "<name>", "staged_files": N, "secrets_s": x, "ruff_s": x, "review_staged_s": x, "reviews": [{"file": "...", "reviewer": "code-review|test-review", "wall_s": x, "rc": n}], "rc": <hook exit>}. Exit code and all messages unchanged. The ledger line is written even when a stage fails or the hook is interrupted (thenrcis the signal's code and later fields are null). - scripts/gate.py and gates/commit_review.py —
review-stagedemits the per-file reviewer walls on a side channel the hook can read (a JSON file whose path the hook passes inPRECOMMIT_WALLS_FILE), without changing stdout, the report files or the Prolog verdict inputs. If the env var is absent, behaviour is byte-identical to today. - .gitattributes —
reports/precommit-walls.ndjson merge=union. - reports/precommit-walls.ndjson — created empty-plus-first-line by the slice's own commit (the hook writes the first real line while committing this change; that line is committed with it). Create:
- tests/scripts/test_precommit_walls_ledger.py — a real scratch git repository under
/var/tmp/ct-0101/<name>with this repository'sscripts/hooks/pre-commitinstalled as its hook and a staged Python file: one commit appends one well-formed line with every key above andreview_staged_s >= sum(wall_s of reviews); a commit that the secrets check refuses still appends a line withrc1 andruff_snull; two lines after two commits; the line never contains a token or key (grep the ledger forsk-,ghp_,GATEWAYreturns nothing). - tests/scripts/test_review_staged_walls_side_channel.py —
review-stagedwithPRECOMMIT_WALLS_FILEset writes the per-file reviewer walls there; without it, no file and identical stdout. Read-only: docs/adr/0101-*.md, scripts/hooks/commit-msg, src/orchestrata_ultimate/prolog/commit_review.pl, tests/gates/ (for the existing review-staged tests).
CONSTRAINTS:
- Read Python through the AST toolkit; shell scripts and markdown with any tool.
direnv exec /home/mohamed/workspace/orchestrata-ultimate-worktrees/adr-0101-hook-ledger uv run …for everything; tests observed:timeout 300 direnv exec <worktree> uv run python -m pytest <modules> -p orchestrata_ultimate.core.threading.pytest_live_observer -q --basetemp=/var/tmp/ct-0101/v(mkdir -p first). No mocks, no monkeypatch, no skips, no xdist. Never re-run an unchanged red.- The scratch repositories are your own; never install or modify the hook of any real checkout on this host.
- Real pre-commit on commit, no
--no-verify; commits by Mohamed, stage by name, no attribution lines; never commitplans/ast-*.json,docs/CODEBASE_MAP*.md,.claude/. - None of ADR-0100's rules execute: no hook is removed, no ship-script gate, no slice-review script.
DONE WHEN:
- Both new tests and the existing review-staged tests are green, observed.
- Your own commit of this slice appended a line to
reports/precommit-walls.ndjsonthrough the real hook; quote it (with any path shortened) in the hand-back. shellcheck scripts/hooks/pre-commitclean if shellcheck is installed (say so if not); ruff and mypy clean on the Python you changed;git status --shortempty.
VERIFY: the pytest summary line; the ledger line; git log --oneline -1.
Report back with those observed outputs and anything that stopped you.