141 lines
7.1 KiB
Markdown
141 lines
7.1 KiB
Markdown
# 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
|
|
```
|
|
|
|
> 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 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? | `docs/architecture/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? | `docs/architecture/githooks/` |
|
|
| 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 |
|
|
|
|
`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:
|
|
|
|
```
|
|
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>
|
|
```
|
|
|
|
**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. `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.
|
|
|
|
## 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.
|