Docs

Ledger

One page for every item of work, and one row per item. Built, fixed, open, on the roadmap, waiting on a person, or held on purpose. Each row says who can act on it and what it gives the user or the platform, and carries a block you can copy straight into a new coding session.

Where to find it

  • Local tab: /ledger.html, a subtab of Launch plan
  • API: GET /api/ledger
  • Authored rows: docs/ledger.d/<program>.md, one file per program
  • Folded page: docs/LEDGER.md, written by npm run sync-ledger
  • The rules: docs/ledger.d/README.md

Why one page

Most projects end up tracking work in several places at once: a roadmap, a feature board, a remediation tracker, a couple of files called what-is-left, and whatever page the last session wrote. Each is right about something the others are stale on, and the count each one carries makes the other four look wrong. The failure is not carelessness. Several lists cannot be kept in step by hand.

The ledger is the one page that answers what is left. Nothing else has to be read to get a complete answer, and a row that is not in it is work nobody can see.

Six kinds, and who acts on each

  • Open: an agent can build it today.
  • Operator: it needs a person, a console, a credential, a purchase, or a decision no agent may take.
  • Gated: held on purpose, and the row names what would un-gate it.
  • Roadmap: an unchecked box in the roadmap, read live.
  • Fixed: closed, with what closed it and what it gave the user.
  • Built: a shipped feature, read live from the feature index.

An item keeps its id for life. The kind is what changes: open becomes fixed when the pull request merges, operator becomes open the moment the credential lands. A row is never deleted to close it, so the page still answers what happened to that a month later.

What it does for you

Hands a row to a session as instructions, not as a titleEvery open, operator and gated row carries a block written for someone who has read your operating manual and nothing else: the goal in one sentence, the files or commands that prove the current state, what done looks like as something checkable, and the gates the change has to clear. Copy it into a fresh session and the session starts without re-deriving what the last one knew.
Makes every item say what it is worthA row carries a value: what it gives the user, or what it gives the platform. A row that cannot say either does not belong in the ledger, which is a cheap filter that a status-only tracker never applies. It is also what lets two unrelated items be ranked against each other.
Cannot drift from the roadmap or the feature indexThose two sections are read from their own files on every load rather than transcribed. The roadmap stays the system of record for roadmap boxes and the feature index for shipped features, so neither count can go stale by being copied. The ledger only owns the rows that had no registry at all, which is where the gaps in a multi-list setup turn out to be.
Refuses the two mistakes that hide an itemA duplicate id and an unknown kind both drop a row off the page in silence. Both are hard errors: the fold refuses, and the API answers 500 naming the id and the two files. A ledger that quietly loses rows is worse than no ledger.

How a row is added, changed and closed

Authored rows live as fragments, one file per program, holding one or more items. One file per program so a program's rows read together, and one file per program rather than one shared table so two pull requests open at once never touch the same file.

  • Edit or add a fragment in docs/ledger.d/<program>.md
  • Run npm run sync-ledger and commit the regenerated docs/LEDGER.md with it
  • Do both in the same commit as the work they describe

The tab reads the fragments on every request rather than the folded page, so an edit shows in the app immediately. The folded page is what a fresh session and a pull request diff read, which is why the fold still runs.

Read more

Last updated