Ledger_c

README

ledger

Decisions that can't silently rot. Bind a design decision to the exact code it governs; ledger keeps the link anchored as the code moves, and fails CI when the code changes without the decision being revisited.

New here? Read GETTING_STARTED.md — plain-language explanation, first decision in five minutes, and setup for Obsidian, VS Code, and CI.

Install

go install github.com/Din-es/Ledger_c/cmd/ledger@latest

Or grab a prebuilt binary for Windows, macOS or Linux from Releases. Then, in any repo:

ledger init

Why

Docs drift because nothing forces them to keep up. ledger turns a decision into a checked invariant: the link records live in the repo (.ledger/*.json), travel with every clone, and a CI gate breaks the build when governed code changes but its rationale doesn't.

Commands

ledger init
ledger bind <file>:<start>-<end> --note <id> [--title "..."] [--add] [--note-file <path>]
ledger resolve <id> [--json]
ledger why <file>[:<line>] [--json]
ledger list [--json]
ledger verify [--since <base>] [--strict]

• init — scaffold .ledger/, docs/decisions/, and a CI workflow.
• bind — capture a decision's code span at the current commit (commit SHA + content fingerprint + surrounding context). Re-binding an id re-anchors it, which is how you clear a drift; --add appends another anchor so one decision can govern several places.
• resolve — find where that span lives now. Reports fresh (tracked), drifted (relocated by similarity, content changed), or broken (the code is gone).
• verify — CI gate. Plain form fails on broken (--strict also fails on drifted). --since <base> fails when a decision's code changed between <base> and HEAD but its note/record was not touched in the same range.
• list — resolve every decision at once. --json is the IPC surface the editor integrations consume.
• why — the reverse of bind: which decisions govern this line?

Demo

./demo.sh

Builds a throwaway repo and walks the whole lifecycle: bind, refactor, rename, a PR blocked for not revisiting the rationale, the same PR passing once it does, why from the code side, and the decision breaking when its code is deleted.

How anchoring works

An anchor is {commit, range, fingerprint, before/after context, body}. Resolution replays git diff <boundCommit>..<target>: hunks above the span shift its line numbers; if the span itself was touched, a windowed fuzzy relocate (LCS line similarity) finds its new home and scores confidence. When the file itself is gone, git's rename detection follows it to its new path. The bias is to break loudly rather than relocate silently.

Editor surfaces

• obsidian-plugin/ — authoring side. A ```ledger codeblock renders the live code a decision governs, plus a staleness sidebar. See its README.
• vscode-extension/ — reading side. Gutter dot, CodeLens and hover on governed spans, and a "why does this code exist?" command. Build with npm install && npx tsc -p ./, then load the folder as an unpacked extension (F5 in VS Code, or symlink into ~/.vscode/extensions).

Testing

go test ./...

Tests build real temp git repos and exercise shift, drift, deletion, rename, and the CI gate.

License

MIT — see LICENSE.

Dependencies. The engine has none: go.mod requires nothing beyond the standard library. The Obsidian plugin and VS Code extension use TypeScript, esbuild and type packages at build time only (all MIT or Apache-2.0); neither shipped bundle vendors third-party code — they require only child_process, path, and their host's own API.

git. ledger runs git as a separate process. Invoking a program is not linking to it, so git's GPL-2.0 does not reach this codebase — the same basis on which any tool that shells out to git stays permissively licensed. Nothing from git is copied, bundled, or redistributed here.

Status

v1.0.0. Anchor engine (shift, fuzzy relocate, rename-follow), CI gate, multi-anchor decisions, JSON IPC, Obsidian plugin, and VS Code extension — all working and verified in their real hosts.

Possible next: an in-process go-git engine instead of shelling out, and binding by symbol name rather than line range.