v1.1.0 · experimental pre-alpha · local-first

Engineering decision memory

Know what justified a decision. Know when it changes.

Proofline shows what evidence justified an engineering decision and warns you when that evidence changes. It keeps the exact source lines with the decision, then makes the review need visible.

Run the demo Inspect the source

Credential-free product story

$ proofline demo stale-decision

Runs locally with an ephemeral database and no model provider.

Animated Proofline demo showing an ADR citation becoming stale — One ADR · one changed requirement · one review signal

Exact evidenceImmutable source identity, version, offsets, lines, and quote hash
Actionable reviewA precise stale citation instead of a generic document-changed alert
Offline proofReadable HTML plus a package verified without database or network access

The product story

An ADR should remember its reason—not only its answer.

Proofline follows one narrow vertical slice from approved requirement to reviewable decision. Every derived claim keeps a resolvable source identity and exact source span.

01 · REQUIREMENTApprove the sourcerequirement.md:42-48 rules out a network dependency and defines crash recovery.
02 · ADRMake the decisionADR-007 chooses SQLite and cites that immutable requirement version.
03 · CHANGERevise the requirementA new immutable source version changes the exact approved evidence.
04 · REVIEWSurface the consequenceProofline fails visibly and routes the decision back to a human reviewer.

Review signalDecision requires review

requirement.md:42-48 changed after this decision was approved.

Run it yourself

From clean checkout to offline verification.

The demo is deterministic in behavior, isolated from your Proofline state, and explicit about every artifact it writes.

TerminalLocal demo

git clone https://github.com/thangldw/proofline.git
cd proofline
make setup
.venv/bin/proofline demo stale-decision
.venv/bin/proofline verify-package proofline-demo-stale-decision/evidence.zip

evidence.zip

Normative Decision Evidence Package, self-contained and verifiable offline.

report.html

A readable decision, exact citation, source hashes, and verification guidance.

decision-health.json

A content-free receipt linking the stale finding to both versions and package root.

Real demo evidence

Inspect the result, not only the architecture.

These images come from one credential-free local run. The terminal output and generated report share the same run-specific package root.

Terminal output showing a changed citation, review signal, and valid offline package — **Terminal outcome**The decision needs review and the exported package verifies successfully.

Generated offline decision report showing the accepted ADR and changed evidence — **Generated report.html**A reviewer can inspect the decision, change signal, rationale, and provenance without raw JSON.

IDs and hashes differ on each run. The stable behavior is the explicit review finding plus an independently verifiable evidence package.

Why Proofline

Use the right tool for the part that must remain verifiable.

Proofline is narrower than a knowledge base. It complements existing documentation when a decision must retain its original evidence and reveal when that evidence stops matching.

ADR-onlyRecords the choice

Proofline also preserves the exact source version and lines that justified the ADR, then flags it when those lines change.

Wiki or NotionSupports flexible team docs

Proofline adds immutable, independently verifiable evidence for approved decisions instead of relying only on mutable pages and links.

Generic RAGFinds likely context

Proofline uses deterministic source identities and exact spans for claims that must remain auditable after retrieval.

Human-readable evidence

Verification should not require reading raw JSON.

Every exported package can include a self-contained HTML projection. It is escaped, CSP-restricted, private by default, and works without remote fonts or assets.

Decision Evidence Package · offline report

ADR-007 · Keep the durable queue in SQLite

Use SQLite for the desktop application's durable local queue.

accepted

Evidence changedrequirement.md:42-48 changed after this decision was approved.

Package root: 16ec914f…eacd61
Source version: immutable · SHA-256 verified
Exact citation: lines 42-48 · offsets preserved

ReadableDecision first, proof underneath.

A reviewer sees the conclusion, rationale, status, exact quote, and hashes in one offline document.

Safe projectionHTML is not the normative package.

The companion JSON or ZIP remains the object verified by the reference verifier.

One command--html-report report.html

Generate it alongside an evidence package without a model or external service.

Open Decision Evidence Package

A format others can implement and test.

DEP v1 publishes its structure and compatibility rules instead of treating Proofline as the only possible verifier.

ContractJSON Schema

Draft 2020-12, closed objects, explicit required fields.

Inspect schema → ConformanceTest vectors

Valid package plus tamper mutations and stable error codes.

Run vectors → CompatibilityVersioning policy

Immutable majors and no silent package rewriting.

Read policy →

proofline verify-package evidence.zipRecomputes source, chunk, citation, transformation, artifact, review, and root hashes offline.

Read-only CI

Stop stale decisions before they disappear into history.

The CI command validates stored provenance and current citations without ingesting, migrating, repairing, or updating review state.

CIDecision health gate

PROOFLINE_HOME=/path/to/state \
  proofline check-decisions

# machine-readable
proofline check-decisions --format json

Exit 0Every approved exact citation resolves in the current source.
Exit 1At least one decision needs review.
Fail closedMissing versions, absent evidence, corrupt spans, or unavailable database.
SQLite mode=roNo state directory creation, database mutation, or hidden repair.

Reproducible receipt

Measure the package path, publish the limits.

The committed synthetic benchmark records environment, fixture, iteration count, ingest/build/verify latency, package size, and peak Python memory.

Ingest52.29 ms

Package build8.02 ms

Median verify0.35 ms

ZIP size3,737 B

Peak memory~2.0 MB

Synthetic credential-free fixture on macOS ARM64 / CPython 3.14.6. Migration time excluded. This is regression evidence—not a production capacity claim.

Honest boundary

Integrity is implemented. Production trust is not.

Proofline is not production-ready yet. It is an experimental pre-alpha for one local user with recoverable test data. The demo proves a product interaction, not broader readiness.

AuthenticityNo signature trust model

Integrity does not establish who created a package or whether a source was trustworthy.

OperationsNo production qualification

Representative scale, security review, support, and disaster operations remain open.

DistributionNo signed native installers

Windows qualification, notarization, updater rollback, and signed native installers remain open.

CollaborationOne local user

No hosted sync, shared workspaces, RBAC, or permission-aware connector matrix.

MIT licensed · local-first · inspectable

Give an ADR the evidence it deserves.

Run the demo Read the format