Queue-North-Website/docs/DOC_TRUST_MAP.md

# Doc Trust Map — which document to believe

```
Status: Current
Owner: _null
Last reviewed: 2026-08-18
Governs: docs/**
Review trigger: Any doc added, deleted or moved; any change to which doc owns a subject
Fires on: added, deleted, moved
```

This describes what is **actually** in this repository, written after everything
else was settled. Where it differs from the template it came from, this one is
right about this project.

## 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. **It has already happened here.** Before 2026-08-18 this project
kept its work in `FUTURE.md`, a changelog in `HISTORY.md`, an agent log in
`DEVELOPMENT_LOG.md`, and phase checklists in `PROJECT.md`, `STRUCTURE.md` and
`README.md` — six records, beside 205 issues in a tracker that none of them
pointed at. Two of those documents still described the project as being in
"Phase 5" while the code was at `0.9.3`, and nothing anywhere said so.

| Question | Answer lives in |
| --- | --- |
| What are we building, and for whom? | `docs/planning/PROJECT_PLAN.md` |
| What standards does the code have to meet? | `docs/planning/REQUIREMENTS.md` — and they need `_null`'s approval to change |
| 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 is deployed, and what do I do when it breaks? | `docs/OPERATIONS.md` |
| What happened, and when? | `docs/history/DEVELOPMENT_LOG.md` |
| Why is it shaped like this? | `docs/history/HISTORY.md` — decisions, and what was tried and dropped |
| What were the batches, before the tracker? | `docs/history/BATCH_LEDGER.md` — archived, must not be updated |
| Did QA pass, and what does the tester think? | `docs/qa/ClaudeReport.md` |
| What did QA actually reach? | `docs/qa/ClaudeQACoverage.md` — and here, the answer is *nothing yet* |
| How is it built? | `docs/architecture/README.md` |
| How does the CRM integration work? | `docs/architecture/zoho-setup.md` |
| What should it look like? | `docs/design/OVERHAUL_PLAN.md` |
| What should it sound like? | `docs/design/REDESIGN_REVIEW.md` |
| 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/` |
| 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.

## Folder layout

| Folder | Contents |
| --- | --- |
| `docs/planning/` | `PROJECT_PLAN` — the vision. `REQUIREMENTS` — the engineering standards. Not the schedule; that is the tracker |
| `docs/qa/` | `ClaudeQAPlan` (playbook), `ClaudeQACoverage` (what each pass reached), `ClaudeReport` (the verdict) |
| `docs/architecture/` | `README` — boundaries, schema, response shapes, the script table. `GUARDS` — how to write a check. `zoho-setup` — the CRM manual |
| `docs/design/` | `OVERHAUL_PLAN` — the visual system. `REDESIGN_REVIEW` — positioning and tone |
| `docs/security/` | `SECURITY` — threat model and third parties. `SECURITY_CHECKLIST` — the pre-release list |
| `docs/history/` | `DEVELOPMENT_LOG` (dated, append-only), `HISTORY` (the narrative), `BATCH_LEDGER` (archived) |
| `docs/data/` | the branding marks privacyllc.dev renders for this project |
| `docs/` root | this map; `WORK_CYCLE`; `TOOLS`; `OPERATIONS` |

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

## What this project keeps that the template does not describe

- **`docs/planning/REQUIREMENTS.md`** — engineering standards with a change
  policy attached. It is not the plan and not the architecture; it is the set of
  rules every agent works to, and it predates the template. Kept whole.
- **`docs/design/OVERHAUL_PLAN.md`** — 25 KB, and **two documents in one file**.
  Its design brief onward is the live token and layout authority; its earlier
  migration-phase and agent-plan sections describe a rebuild that finished. Its
  own front-note says which half is which. Splitting it would have risked losing
  prose that nothing else records, so it was not split.
- **`docs/architecture/zoho-setup.md`** — written for a non-technical reader.
  Note the trap in its own header: it documents the OAuth path, and production
  runs WebToLead.
- **The agent pipeline** — Scarlett, Neo, Private Hudson, Bishop, Ripley — is in
  `README.md`, not in this tree, because it is how work is dispatched rather
  than a subject anything is authoritative about. `.learnings/` holds four
  agents' notes and is gitignored.

## What the template carries that this project deleted

Recorded so a reader can tell a deliberate absence from an oversight.

| Deleted | Why |
| --- | --- |
| `ClaudeQAPlan.md` pass I — money flowing backwards | no money moves through this site. A pass that never applies is noise |
| `SECURITY_CHECKLIST.md` — the authorisation group, and the session-token row | there is no login, no session, no role and no per-user data anywhere in the product |
| `SECURITY.md` — the *(precautionary)* bring-your-own-credential paragraph | **a precautionary rule, dropped deliberately.** It describes holding credentials on behalf of users; there are no users. `PROJECT_PLAN.md` records accounts as out of scope, which is what makes it safe to drop |

Every other *(precautionary)* marker was kept. `OPERATIONS.md` was kept in full —
this is a deployed service with a live origin, a named host and a database.

**Pass H was kept and rewritten** rather than deleted. Its authorisation half
does not apply; its *what a stranger can reach and exhaust* half is the most
exposed surface this project has.

## A fifth severity label exists, and is frozen

`P3` sits on 21 closed issues from before this repository adopted the
convention. It is **not** one of the four names the Command Center queries, so a
defect filed `P3` today would be counted by nothing.

It was kept rather than deleted because removing it would erase the severity
record on those 21 issues, and merged into `P2` would misstate them. **Nothing
new gets it.** New defects use `P0`, `P1`, `P2` or `release-blocker`.

## Source-of-truth ladder

When two sources disagree, believe them in this order:

1. **Verified code behaviour** — read the source. Note that on this project
   "run the tests" is not available: there are none
2. **The issue tracker** — for anything about state of work
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.

```
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.** 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.

**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. A header 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`.
`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.

**Fires on** is optional and only for the case where `Governs:` is much broader
than the trigger. This file is the extreme of that gap — it governs `docs/**`,
the broadest glob here, while its trigger is one of the narrowest. Omit the line
unless it is genuinely needed; absent means fire on every kind.

`scripts/verify.d/30-doc-headers` checks all of this on every `npm run verify`,
which is what stops it being a convention people remember.

## Declaring a document deliberately absent

A repository may decide it will not keep one of these documents in git. 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.
Keep illustrations fenced, and use placeholders anyway, as the form above does.

**This project exempts nothing.** It considered it: the internal history and
planning documents were gitignored with the comment *"never commit"*, and
exempting them was one of the three options on the table. Instead the Forgejo
repository was made **private** on 2026-08-18 and the documents were committed,
because a half-populated doc tree reports to privacyllc.dev as a half-adopted
project and the reason for the secrecy was the audience, not the content.

**`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.

## One asset is genuinely missing, and that is not an exemption

docs/data/img/banner.webp does not exist — named here without backticks
deliberately, because `doc-claims.sh` reads a backticked path as a claim that the
file is there, and this sentence is the opposite claim. `icon.webp` and
`logo.webp` do exist, both converted from this project's own marks in `assets/`.

No placeholder was generated, deliberately — a placeholder that looks finished
outlives the issue that would have replaced it. It is filed as a `P2` issue
instead, and the project card will render without a banner until somebody draws
one.