TriageCore Build Ledger

Turn Codex-generated changes into reviewable evidence: requested scope, actual diff, validation results, risk findings, and explicit human approval.

Comment

Inspiration

AI coding agents can produce working software quickly, but the evidence needed for responsible human review is usually scattered across the original request, Git diff, terminal history, test output, and reviewer notes. TriageCore Build Ledger turns that fragmented trail into a bounded approval workflow.

This Build Week extension follows a simple principle: the hackathon serves the TriageCore roadmap; TriageCore does not contort itself to serve the hackathon. The result is a durable TriageCore capability for Codex changes, local coding agents, contributor pull requests, and security-sensitive modifications.

What it does

Given a Markdown change request and a Git change, TriageCore Build Ledger:

  • parses declared file scope and required validations;
  • compares the declared scope with the actual Git diff, including staged, unstaged, and untracked files;
  • runs explicitly trusted validation commands with bounded time and output capture;
  • flags unexpected files, scope drift, failed or missing validation evidence, sensitive-file changes, binaries, and source changes without corresponding tests;
  • emits authoritative review.json, diff-summary.json, and validation-results.json evidence;
  • renders readable Markdown and a polished local HTML review report;
  • records one explicit approved, rejected, or needs_revision human decision without overwriting an existing decision; and
  • independently verifies packet integrity by recomputing canonical evidence and checking that the decision references the exact evidence hash.

The installed interface is:

tc build-review create ...
tc build-review decide ...
tc build-review verify <packet-path>

The core flow is: requested scope → actual changes → validation evidence → findings → human decision → independent verification.

How we built it

The extension is implemented in Python using the standard library, the Git CLI, argparse, canonical JSON, SHA-256 evidence binding, and standalone HTML/CSS. Two contract-first change requests define the boundary:

  • CR-BW-001 — Evidence-Bound Build Review
  • CR-BW-002 — Installable CLI and Evidence Verification

Codex accelerated the Git inspection layer, evidence schema, verifier, report renderer, tests, and documentation. Human judgment set the product boundary, trusted-command model, immutable-evidence design, decision semantics, release gate, and freeze rule.

The feature landed through public pull request #103. The initial feature commit is 50894bf; the CI compatibility hardening commit is 472222e.

Challenges we ran into

The hardest design problem was separating evidence from decisions. A reviewer needs a decision bound to exactly what they reviewed, but rewriting evidence during approval would weaken that guarantee. The solution hashes canonical authoritative evidence independently, stores the decision separately, binds the decision to that exact hash, and refuses decision overwrite.

The verifier also cannot trust derived fields inside the packet. It recomputes them, rejects malformed or duplicate-key JSON, checks required artifacts, validates the decision enum and references, and exits nonzero with a specific diagnostic for every failure.

During the public CI run, Python 3.12 exposed an install-test assumption about build isolation, while Python 3.10 exposed an intermittent UUID/credit-card-pattern false positive in the existing privacy invariant. Both were fixed with narrow regression coverage before merge.

Accomplishments that we're proud of

  • Complete vertical slice from request contract through immutable human decision and independent verification.
  • Installed tc console command with create, decide, and verify subcommands.
  • End-to-end tests invoke the installed command through subprocesses rather than importing CLI internals.
  • Intact-packet verification plus tamper, missing-artifact, malformed-JSON, altered-decision-reference, and overwrite-refusal coverage.
  • A clean self-review packet that recommends approval while keeping the human decision pending.
  • An adversarial packet that is cryptographically intact while documenting undeclared scope and missing validation, resulting in needs_revision.
  • Local release gate: 1,017 tests passed and 3 skipped.
  • Public CI passed on Python 3.10, 3.11, and 3.12 for both the PR head and merged main.
  • Fresh-environment installation from the public release tag succeeded, and the installed command verified both demo packets.

Release evidence

Install the exact submitted source with:

python -m pip install "git+https://github.com/coreytshaffer/TriageCore.git@build-week-2026-07-17"
tc build-review --help

What we learned

Governance is most useful when it is part of the development path rather than a separate compliance exercise. A small number of transparent invariants—declared scope, explicit validation, immutable evidence, exact decision binding, and independent verification—can make agent-generated changes substantially easier to review without turning the coding loop into a second bureaucracy.

We also learned to distinguish integrity from acceptability: an evidence packet can be intact while proving that a code change should not be approved.

Limitations

The SHA-256 evidence hash proves internal packet consistency; it is not a digital signature and does not prove authorship or external timestamping. Validation commands are explicit trusted local commands, not sandboxed untrusted input. The workflow is intentionally local-first and does not autonomously remediate findings or replace human approval.

What's next for TriageCore Build Ledger

Post-hackathon work can add signed attestations, CI and pull-request adapters, richer policy and coverage evidence, and external evaluator integration while preserving the same evidence-bound, local-first, human-controlled review boundary.

Built With

Share this project:

Updates