Project-Template/docs/DOC_TRUST_MAP.md

# Doc Trust Map — which document to believe

```
Status: Current
Owner: <who maintains this>
Last reviewed: <YYYY-MM-DD>
Governs: docs/**
Review trigger: Any doc added, deleted or moved; any change to which doc owns a subject
Fires on: added, deleted, moved
```

> Write this file **last**, once the rest exists, and describe what is actually
> here rather than what a template said should be. Its whole value is being
> accurate about the others.

## Work items are not in this tree

The sequence of work, the open defects, and the things blocking a release all
live in this repository's **issue tracker**, not in `docs/`. Milestones are
batches; issues are deliverables; severity labels are `P0`, `P1`, `P2` and
`release-blocker`.

This section exists to stop the next contributor starting a fresh markdown
to-do list. A list of things to do in two places is two records that will
disagree, and nothing will say which one is right.

| Question | Answer lives in |
| --- | --- |
| What are we building, and for whom? | `docs/planning/PROJECT_PLAN.md` |
| What is the sequence of work? | milestones in the tracker |
| What is left in this batch? | open issues under that milestone |
| What is broken right now? | issues labelled `P0` / `P1` / `P2` |
| What makes a release wrong? | issues labelled `release-blocker` |
| What is the next action? | the `nextAction` field on the project at privacyllc.dev — the newest entry in `docs/history/DEVELOPMENT_LOG.md` says what it was *then* |
| What is blocking us? | the tracker, for the work; the blockers table at privacyllc.dev, for the stakeholder-facing version |
| What do I do when a piece of work is finished? | `docs/WORK_CYCLE.md` |
| What watches this in production, and what do I do when it breaks? | `docs/OPERATIONS.md` |
| What happened, and when? | `docs/history/DEVELOPMENT_LOG.md` |
| Did QA pass, and what does the tester think? | `docs/qa/ClaudeReport.md` |
| What did QA actually reach? | `docs/qa/ClaudeQACoverage.md` |
| How is it built? | `docs/architecture/` |
| How do I release, back up, or check this? | `scripts/` |
| Which script do I run, and can it stop me? | `docs/TOOLS.md` — the signpost; `docs/architecture/README.md` has the table |
| What runs before a commit? | `.githooks/` |
| What stops an agent reporting work it did not verify? | `docs/architecture/scripts/verify-before-done.sh`, and `docs/TOOLS.md` for why it is a second layer rather than the layer |
| How do I write a check that will actually catch something? | `docs/architecture/GUARDS.md` |

**Next action and blockers are recorded at the end of every piece of work, not
when somebody asks.** `docs/WORK_CYCLE.md` holds that procedure and the reason
each step is in it — including which of these channels updates itself and which
two only ever change because a person changed them.

## Folder layout

| Folder | Contents |
| --- | --- |
| `docs/planning/` | `PROJECT_PLAN` — the vision. Not the schedule; that is the tracker. |
| `docs/qa/` | `ClaudeQAPlan` (playbook), `ClaudeQACoverage` (what each pass reached), `ClaudeReport` (the verdict) |
| `docs/architecture/` | How it is built: module boundaries, data shapes, reference manuals |
| `docs/design/` | What it should feel like: product decisions, UI plans, copy |
| `docs/security/` | `SECURITY` — threat model, secret handling, what is out of scope |
| `docs/history/` | `DEVELOPMENT_LOG` (dated, append-only), `HISTORY` (the narrative), `BATCH_LEDGER` (archived, superseded by the tracker) |
| `docs/data/` | the three branding marks privacyllc.dev renders for this project |
| `docs/` root | this map; `WORK_CYCLE` — what to do when a piece of work is finished; `TOOLS` — where the scripts are and which can stop you; `OPERATIONS` — what watches production, *(only for a deployed service)* |

`README.md` stays at the repository root; it is the landing page and moving it
breaks that. Everything else lives under `docs/`.

## Source-of-truth ladder

When two sources disagree, believe them in this order:

1. **Verified code behaviour** — read the source, run the tests
2. **The issue tracker** — for anything about state of work: what is open, what
   closed, when, and by which commit
3. **Specialist docs** — authoritative for their own subject only
4. **History and logs** — a record of *then*, not a description of *now*

A document that describes work as done is describing what was true when it was
written. The tracker is describing now.

## The status header

Every document in this tree opens with one, immediately after its H1 — and so
do the documents at the repository root, which `scripts/doc-triggers.py` reads
alongside this tree. The root is read one level deep only, so a vendored copy
of this template cannot enrol its documents as governing the project holding
it.


```
Status: Current | Draft | Superseded | Archived
Owner: <who maintains this>
Last reviewed: <YYYY-MM-DD>
Governs: <paths or subject this document is authoritative for>
Review trigger: <the change that should send someone back to this file>
Fires on: <optional — added, deleted, moved, changed>
```

**Exactly those four status words.** They are not a suggestion: a checker reads
them, and a document whose status falls outside the list is reported as having
an unknown one rather than being quietly accepted. It is also what separates a
document from a *template for* one: `project-readme-template.md` carries
`Status: <Current | Draft | Superseded | Archived>` and a `Governs:` describing
the README of whichever project copies it, so `doc-triggers.py` does not treat it
as governing anything here — and says so when it would otherwise have fired,
rather than dropping it quietly. `Historical` is the word this
convention used to have and deliberately dropped — `Archived` covers it, and a
vocabulary a script enforces beats one described in prose, which drifts the
moment somebody writes something adjacent to it. `Draft` earns its place by
naming a real state the old list had no word for: a document being written,
which is neither current nor superseded.

**Review trigger** is the line that matters. "Last reviewed" ages on its own and
a reader cannot tell a current document from an abandoned one by looking at it;
a trigger names the event that should bring somebody back, which is what stops a
document becoming confidently wrong. It is also checked: the header is read from
the first sixteen lines of the file, and one carrying `Status` without
`Review trigger` is reported as incomplete — that combination looks finished and
is not.

**Governs** is a comma-separated list, and an entry may explain itself after the
glob with a spaced dash — `docs/data/** — the assets privacyllc.dev renders for
this project`. `scripts/doc-triggers.py` cuts the entry there and reads the globs
from the left of it. **Use that form and no other.** A gloss in parentheses, or
after a colon, is not recognised: the whole entry becomes the glob, matches
nothing, and the document is silently never fired — not reported as skipped
either, because it still looks like a path. Three documents here sat in exactly
that state from the first commit, `docs/data/img/README.md` among them, so
editing the branding assets never once prompted the document that specifies their
names and sizes. A trailing `/` on a glob means the directory and everything in
it, which is how this file's `.githooks/` entry reaches a project's installed
hooks.

**Fires on** is optional, and only for the case where `Governs:` is much broader
than the trigger. `Governs:` says *where* a document is authoritative; the
trigger says *which kinds of change* to that place should bring somebody back,
and `scripts/doc-triggers.py` can only read the first. This file is the extreme
of the gap: it governs `docs/**`, the broadest glob here, while its trigger is
one of the narrowest — *any doc added, deleted or moved*. Without the
declaration it fires on every edit to every document forever, and is right to by
the only rule the tool has. A prompt that always fires is one people stop
reading, and it takes the true positives with it.

The words are `added`, `deleted`, `moved` and `changed`, comma-separated. **Omit
the line unless it is genuinely needed** — absent means fire on every kind, which
is what almost every document wants. It is deliberately declared rather than
inferred from the trigger prose: the obvious heuristic — existence verbs and no
change verb — was tried against the documents here and misread this one, whose
trigger ends "any change to which doc owns a subject". That clause is about which
document owns a subject, not about a file being edited, and nothing mechanical
separates it from a trigger that does mean modification. A wrong guess is silent
in the expensive direction, so an unreadable or missing declaration fires on
everything and only a deliberate line ever quietens a document.

## Two markers: does this apply, and who earned it

This tree is copied into every project, and some of what it carries will not
apply to all of them. A static site has no refunds; a library has no uptime.
Rather than shipping several templates, entries that are not universal say so
inline, with **two markers on different axes**:

| Marker | Answers | Example |
| --- | --- | --- |
| *(only where money moves)*, *(only for a deployed service)* | does this project have to do this at all? | a payments QA pass; the operations runbook |
| *(precautionary)* | was this rule earned here, or borrowed from outside? | rate limits; secrets in a shipped bundle |

**They are independent, and conflating them loses the distinction.** A rule can
be universally applicable and precautionary — rate limiting applies to
everything here and has never yet bitten us. Another can be narrowly conditional
and thoroughly proven elsewhere — money flowing backwards applies only to
projects that take money, and is the single most common defect in the audits it
came from. One word cannot say both, and the reader needs both: applicability
tells them whether to keep the rule, provenance tells them whether to argue with
it.

**If it does not apply, delete it.** That is `docs/qa/ClaudeQAPlan.md`'s rule
about passes — *a pass that never applies is noise; a pass that is always
skipped is a lie* — and it holds for a checklist row and for a whole document
just as well. A project that is not a deployed service deletes `OPERATIONS.md`
rather than carrying its headings unanswered forever, because an empty runbook
reads as one nobody wrote rather than one that never applied.

Deleting is safe here precisely because this file is the trust map: what a
project keeps is what a project meant to keep.

## Declaring a document deliberately absent

A repository may decide it will not keep one of these documents in git — QA and
security notes held outside the repository on purpose, say. Say so **here**, one
line per path, anywhere in this file:

```
Exempt: <the path> — <why, in a few words>
```

**Write the real path only when you mean it.** Outside a fenced block, an
`Exempt:` line naming a real document is not an example — it is a declaration,
and the checker will report that document as deliberately absent in every
repository that copied the file. Keep illustrations fenced, and use placeholders
anyway, as the form above does.

Fenced blocks are skipped, but only since 2026-08-12. Before that the parser
read every line, which meant that documenting this feature *used* it: the
example a writer naturally reaches for is a real required path, because an
illustration with a fake one teaches nothing. A draft of this very section
carried `Exempt: docs/security/SECURITY.md` inside a fence and would have marked
that document deliberately absent everywhere it was copied. It is recorded here
rather than quietly fixed because the shape recurs — a parser that cannot tell a
description of a thing from the thing itself.

The declaration lives in this file because the decision does. Holding the list
somewhere else would be two records of one fact, and the other one would never
hear that this repository changed its mind.

**`docs/data/` and `docs/data/img/` cannot be exempted.** A declaration naming
either is refused rather than honoured, because the Command Center renders what
is in them — an exemption would produce a project card with no icon and nothing
explaining why, which is the failure the check exists to catch.