173 lines
9.0 KiB
Markdown
173 lines
9.0 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 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? | `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; `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:
|
|
|
|
```
|
|
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.
|
|
|
|
## 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.
|