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.

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 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. 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), 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)

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.

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.