Proofline

01 · Production problem

Teams remember the decision but lose the evidence state that made it defensible.

Architecture decisions often cite mutable requirements, tickets and documents. When a source changes, the historical decision should not be silently rewritten, but reviewers still need to know that its current evidence requires attention.

Proofline binds decisions to immutable source versions and exact spans, then computes stale-citation and transitive-impact state deterministically. The failure class appears in production engineering; this page does not claim hosted team deployment.

02 · Architecture and trade-offs

Separate immutable history from current evidence health.

1. Explicit local ingest creates immutable source versions with hashes and stable offsets.
2. SQLite and FTS index retrieval units; citations bind source, version, offsets, lines, quote and quote hash.
3. Accepted decision status remains historical while evidence review state can become stale or review-required.
4. Portable evidence packages, review receipts and optional Ed25519 attestations verify through fail-closed local code.

CLI, local API, web UI and desktop shell share one domain model. Optional generation, embeddings and reranking sit outside the integrity-critical path. The trade-off is deliberate: one local authoritative store avoids tenant and identity complexity, but does not provide shared hosted collaboration.

Architecture · Evidence packages · Operations

03 · Benchmark or failure case

A changed requirement moves evidence to review without erasing history.

The stale-decision demo creates a disposable workspace, changes a cited requirement, reports the citation as stale, moves current review state to review-required, and verifies the exported evidence package from its root hash.

A committed synthetic 10,000-decision SQLite benchmark measured 6,731.87 ms to refresh 10,000 reviews and 1,645.54 ms to verify them on the recorded macOS/Python environment.

The exact default-branch revision 5f7715f passed public CI and CodeQL.

04 · Reproduce in under five minutes

Install the released package and run one complete stale-evidence story.

python -m pip install proofline-evidence==2.0.2
proofline demo stale-decision
proofline verify-package proofline-demo-stale-decision/evidence.zip
proofline verify-review-receipt proofline-demo-stale-decision/decision-review.json

Expected result: the cited requirement becomes stale, current review state becomes review-required, and both the evidence package and review receipt verify.

05 · What I designed and led

I designed the trust boundary, decision lifecycle and portable evidence contracts.

I own the separation between historical decision status and present review state; immutable source/citation model; cycle-safe impact traversal; package, receipt and attestation semantics; local API/UI/desktop boundaries; and release qualification.

This is evidence of personal architecture and maintenance ownership. The repository does not provide evidence that I led a customer team using Proofline in production.

06 · Limitations and missing evidence

Integrity is implemented; organizational trust is not implied.

• The current scope is one local user; hosted sync, tenant isolation, shared workspaces, OAuth and organization identity are absent.
• A valid package root proves integrity, not source truth or authenticity.
• An Ed25519 signature proves matching key control relative to a trusted public key, not legal identity, trusted time, authorization or revocation status.
• No real-team pilot or hosted-production benchmark has been run.
• Desktop artifacts are experimental and lack Apple notarization and Windows Authenticode evidence.