Evidence & audit

The evidence lives in your repo, not on our servers, not in a vendor dashboard. It travels with the code, versioned by git, and outlives any vendor. This page is the map.

Where every record lives

Record	Path	Contents
Scan verdicts	`.linebreak/audit/security.json` `.linebreak/audit/code.json`	The verdict plus the raw scanner output that produced it (osv-scanner, npm audit, the AI code review): every conclusion is traceable to its original evidence, not just asserted.
Overrides	appended to the audit artifact	One exact finding or criterion, the reason, and a named human approver. Never a blanket waiver.
Approved spec	`.linebreak/spec/manifest.yml` `.linebreak/spec/stories/<id>.yml`	One file per story: metadata plus every acceptance criterion, with approval attribution (who, when, what role).
Manual sign-offs	`.linebreak/spec/signoffs/<criterion>-<uuid>.yml`	Attributed human sign-off for a manual criterion, with a note of what was verified.

The spec bundle validates itself: a stray or renamed file in stories/ fails the load: a writer only ever emits <id>.yml, so a mismatch means the bundle was tampered with.

Two more records, outside the repo

The required check on every PR: GitHub’s own history of the gate passing (or a human overriding) on every merge. An independent second ledger.
The PR summary comment: one comment per PR, updated in place, stating what the gate found.

How a CTO exports the evidence

linebreak-gate report                 # human-readable summary of everything recorded
linebreak-gate report --format json   # machine-readable, for the audit package
git log -- .linebreak/                # the chronological ledger: who, what, when

The git history of .linebreak/ is the audit trail: every approval, override, and threshold change is a commit with an author and a date. Nothing can be rewritten without it showing. Relaxing the gate is itself a PR: who loosened fail_on, and when, is part of the story.

How an auditor verifies signatures, offline

On the Pro plan, every approval carries an Ed25519 signature envelope over the canonical content hash. The verifying public key is committed in .linebreak/gate.yml. That means the auditor:

needs no LineBreak account and no access to LineBreak servers,
verifies entirely offline, on a bare clone,
does not have to trust the team’s word, or ours. The math either verifies or it doesn’t.

If a signature does not verify, the gate itself fails closed: tampered evidence cannot “pass quietly.” Key rotation is supported: each key carries a kid, so approvals signed before and after a rotation both verify.

Signature states, reported honestly

State	Meaning
`unsigned`	Free tier: the approval is on the record in git, but carries no signature. Reported as exactly that, never implied assurance.
`signed-unverified`	A signature is present but no verifying key is configured. The hash comparison still detects tampering.
`valid`	The signature verifies against a configured key.
`invalid`	The bundle was edited after approval. Reported loudly; the gate rejects it at merge.

The one-line summary: the evidence lives in your repo, exports with one command, and your auditor verifies it without trusting you, or us.