> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tiny-brain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The tracking model

> Markdown is the source of truth; everything else is projection

tiny-brain's tracking has one rule at its core: **the plan markdown is
canonical, and everything derived from it is projection.** Nothing about
your work lives only in a database — it's all in your repo, in git.

## Three layers

<Steps>
  <Step title="Plan markdown (committed, canonical)">
    PRDs, features, and fixes live under `docs/` (and fix documents under
    `.tiny-brain/fixes/`) as reviewable markdown. Task descriptions,
    statuses, and commit SHAs are recorded here. Each item carries a stable
    UUID in its frontmatter — that UUID, not the wording, is the task's real
    identity.
  </Step>

  <Step title="Repo context (committed, generated)">
    `.tiny-brain/` holds what tiny-brain has learned and configured for the
    repo: `analysis.json` (detected stack, package manager, scripts, test
    patterns), `config.json` (preferences — enabled gates, directories,
    default persona), and technology context under `tech/`. Committed so the
    whole team — and every agent session — works from the same picture.
  </Step>

  <Step title="Per-clone state (not committed, rebuildable)">
    On current tiny-brain versions, live progress projections, review
    records, and session telemetry sit under `.git/tiny-brain/` in each
    clone — deliberately outside the committed tree, because they're derived
    from commit history: a fresh clone reconstructs them with
    `tiny-brain progress rebuild` instead of merging them. Repos initialised
    on earlier versions may still carry committed projections
    (`.tiny-brain/progress/`, `.tiny-brain/reviews/`) alongside; teams
    choose whether to keep tracking those in git.
  </Step>
</Steps>

## Why commits are the joins

A tracked commit's headers (`PRD:` / `Feature:` / `Task:`, or `Fix:`) are
resolved to task UUIDs by the commit-msg hook at commit time. That makes the
git history the join table between plans and code: any clone, dashboard, or
future tool can re-derive who did what for which task from history alone.
It's also why the headers are enforced rather than suggested — an
unattributed commit is a hole in the record.

## Hooks own the state

The tracking layers are written by hooks and agents, not by hand.
Hand-editing a projection creates a state that history doesn't support, and
the next hook run will disagree with it. If tracking looks wrong, the fix is
the hook (or a re-sync from the markdown) — not the JSON.

What *is* yours to edit is the canonical layer: the plan markdown. Update a
task's status there and re-sync (`tiny-brain task sync <file>`), and the
projections follow.