truthboard

README

Truthboard

Your repo already knows the status. Stop typing it twice.

Truthboard is a git-native tracker with one rule: status is derived from repo reality, never typed by hand. Humans and AI agents write down intent once — a small markdown spec — and the board, drift report, and stakeholder digest are computed from branches, merges, and commit trailers. On repos with no specs it runs as a pure read-only auditor, and either way it can check your existing tracker's claims against what the repo proves.

What it looks like

Every status on this board was computed, not typed. Apple Pay support is in progress because a branch carrying its id has commits; One-page checkout flow is done because its work landed on main — the card's evidence line says so. Cards carry the story's intent: priority, points, bug/task type badges, epic and sprint tags, and the owner's avatar. The filter row totals points per epic, and the sprint panel is pure arithmetic plus a date window: s12 · 1/3 done · 5/10 pts · 2026-07-14 → 2026-07-25 · active, 8d left — nothing there can be edited, because none of it is an opinion.

A story opens into its intent — goal and Given/When/Then acceptance, where checking a box records human sign-off, deliberately separate from delivery — followed by the derived truth panel: the status, the commit that landed it, and every signal that links work to this spec. The promise is editable; the proof is not.

Install

Grab a binary from Releases and put it on your PATH, or build from source:

go install github.com/emmanuel-D/truthboard/cmd/truthboard@latest

Single static binary; the only runtime dependency is git. Optional: gh/glab for tracker claims, npm for package scripts.

Stay current with truthboard update (--check to only look): it verifies the download against the release checksums and swaps the binary atomically. Detached boards keep running the old binary until you truthboard stop && truthboard ui --detach — the board's footer shows which version is serving it.

Quick start in an existing project

cd your-project
truthboard init --agents --hooks   # specs + MCP + AGENTS.md + trailer nudge
truthboard ui --detach             # the board, running in the background

That's the whole setup. Write your first story (truthboard spec new or the board's + New story), work on a branch containing its id, and the card moves itself. In npm projects, init also wires npm run board, board:status, board:stop, and board:audit.

Spec mode — the tracker

truthboard init                             # opt in: creates .truthboard/specs/
truthboard spec new "Add email verification" --owner emmanuel
truthboard brief tb-4f2a                    # context packet for an AI agent (or a human)
truthboard next                             # highest-priority planned story, as a brief —
                                            # "start the next story" is one deterministic call
truthboard audit                            # spec board + drift + digest, all derived
truthboard link tb-4f2a "hotfix/*"          # fix a linking miss — fixes the input, never the status

A spec is one markdown file (YAML frontmatter + Goal/Acceptance body), versioned with your code. Backlog structure is intent too: epic groups stories, priority orders them, and sprint (e.g. --sprint s12) puts a story in an iteration — the audit, reports, and board then show a per-sprint rollup (done/total and what's still open, each story's status derived as always). There is no sprint status to set and no sprint clock: a sprint finishes when its stories land. Linking signals, strongest first: a Spec: tb-4f2a commit trailer, the id in a branch name, the spec's branch glob. Derived statuses: planned → in-progress → in-review → done (plus stalled), and a done spec loudly becomes regressed when its landed work is reverted or CI goes red on the landing commit — without CI data the tool says nothing rather than guessing. There is no command to set a status — that's the product.

MCP — agents as first-class citizens

truthboard mcp serves the spec layer over the Model Context Protocol (stdio), so Claude Code and other agents stop shelling out:

claude mcp add truthboard -- truthboard mcp

Tools: list_specs, get_brief (the context packet to start work), next_spec (the highest-priority planned story — an idle agent needs no human to pick), create_spec, get_board. Deliberately absent: any tool that sets a status — an agent's work shows up on the board the same way a human's does, through commits with the spec trailer.

Web board — for the people who used to ask "what's the status?"

truthboard ui              # opens http://127.0.0.1:1337, auto-refreshing
truthboard ui --forge      # include tracker claims (slower refresh)
truthboard ui --detach     # keep it running in the background
truthboard ui --fetch 60s  # poll origin so the board tracks the remote
truthboard status          # is a board running for this repo?
truthboard stop            # stop the detached board

Detached boards are per-repo: state lives inside .git/ (never committed), no system services, no root.

In npm projects, truthboard init also wires these as package scripts — npm run board, board:status, board:stop, board:audit — via npm pkg set, never touching your existing scripts.

A live page rendering the spec board, branches, drift, and digest — and where POs create and refine stories: click a card to edit its title, goal, acceptance, epic, and priority. The promise is editable; the proof is not: intent edits write the markdown spec files (a plain git diff, with an uncommitted-changes nudge on the page), while statuses stay computed with no route by which anything could set one. Single embedded HTML file via go:embed — still one binary.

Multi-machine: a board that tracks the remote

The board derives everything from the local clone, so by default it is only as fresh as your last git fetch. When the machine showing the board is not the machine doing the work — a PO's laptop, a shared box — add --fetch:

truthboard ui --detach --fetch 60s

Remote-tracking refs refresh unconditionally, so branch statuses, drift, and the digest track the remote with no local git use. Spec files are intent and live in the working tree, so the checkout is fast-forwarded only when it is clean and on the integration branch — uncommitted work is never touched, and the page says loudly when refs are fresh but story files are not (or when fetching fails).

To give the whole team one URL, bind beyond loopback:

truthboard ui --detach --fetch 60s --host 0.0.0.0 --no-open

There is no auth story yet, so a board served beyond loopback is strictly read-only: it shows the truth; intent editing stays a same-machine (clone) privilege. truthboard status reports the fetch interval and shared host.

Audit mode — works on any repo, no specs needed

truthboard audit ~/dev/some-repo  # board + drift + digest from git alone
truthboard audit --format md      # markdown (for a weekly drift issue)
truthboard audit --format json    # machine-readable (for CI/automation)

What it reports:

• Derived board — every non-integration branch classified as in-review, in-progress, stalled, or done (merge detected by ancestry or patch-equivalence, so squash/rebase merges are caught).
• Drift — stale promises (work that stopped without landing), shadow work (commits that bypassed any branch/MR flow), zombie branches (landed but never deleted), and a misconfigured remote default branch if it spots one.
• Claims vs proof — when the repo is on GitHub and gh is available, the tracker's claims are checked against the repo: assigned tickets with no matching activity, tickets whose fix already landed but are still open, branches with no ticket and no PR, PRs closed without merging. Unassigned open issues are backlog, not claims — they are never flagged.
• Digest — what actually landed recently, readable by a non-developer.

Git evidence always outranks tracker claims: enrichment can upgrade a branch to in-review, but nothing a tracker says can un-merge a merged branch.

GitHub Action

Maintain a recurring drift-report issue, updated in place on a schedule:

name: Truthboard
on:
  schedule:
    - cron: '0 8 * * 1'
  workflow_dispatch:
permissions:
  contents: read
  issues: write
  pull-requests: read
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # full history — the audit reads branch/merge topology
      - uses: emmanuel-D/truthboard@main

Inputs: stale-days (default 7), digest-days (default 14), issue-title (default "Truthboard drift report"), github-token (defaults to the workflow token). The action never blocks, labels, or closes anything.

Build

go build ./cmd/truthboard
go test ./...

Single static binary, no runtime dependencies beyond git itself.

License

MIT — see LICENSE.

Status

0.1.0-dev — the CONCEPT-V1.md spec-driven tracker built on the CONCEPT-V2.md audit engine. The inference logic was validated at 100% done-vs-not-done accuracy against GitHub PR state on real repos before being ported to Go (CONCEPT-V1 §11). The roadmap lives in .truthboard/specs/ — run truthboard audit on this repo to see it.