D27 · apps/docs is the source of truth, written before tests and code

Accepted · 2026-10-06 · zuki · Supersedes D23, except that product and process docs stay in Drive · Partly supersedes D1 (when the register moves) and D25 (how docs files enter the repository) · Partly superseded by D28 (the agent fork, and when the register moves)

Decision: apps/docs is built alongside v2, not after cutover, and it is the source of truth for what v2 does. Each feature is written in this order: its rules in apps/docs, then the tests that prove them, then the code. apps/docs holds two kinds of pages. Written pages give each rule an ID (such as R-BC-03), a status, an example, the error key it raises (D10), the roles it applies to and its source. Generated pages (tables, functions, enums, error keys, permissions) are produced from the database and never edited by hand. Every pgTAP and Playwright test starts its description with the ID of the rule it proves, and pnpm docs:rules fails CI when a built rule has no test or a test cites a rule that doesn't exist.

A new role, the Docs Engineer, writes the rules and never writes tests, code or decisions. The Backend and Frontend Engineers write the tests first, then the code, and change only a rule's status. A rule that turns out wrong goes back to the Docs Engineer, or to this register as a change request; it is never changed quietly to fit the code. Writing docs, tests and code is delegated to agents and reviewed by zuki before it merges. Operating stays with zuki: anything run against staging or production, and every promotion on the automation ladder. M0's TL, BE and FE steps stay runbook steps that zuki runs (D25).

There is no paid GitHub plan until cutover, so D26 stands and only zuki can write to the repository. Agents push to a private fork under zuki's personal account, where CI runs; zuki opens each pull request from the fork into the repository, where CI runs again without secrets, and merges it (TL-M0-25 in [Runbook] v2 timeline). The Docs Engineer starts in M0: DOC pack A moves V13's rules into apps/docs before BE pack B, so the first pgTAP tests cite rule IDs. This register moves into apps/docs at the M0 exit check and keeps its numbers. Product and process docs that team leads comment on stay in Drive.

Why: Docs written after cutover would describe the code instead of steering it. The rules live in Postgres and pgTAP tests them directly, so a written rule can be proved the same day. Keeping a rule's author apart from its implementer keeps the docs a check on the code, and the CI check keeps them true. The fork gives agents CI without access to the repository or its secrets, at no cost.

Consequences: [Spec] and [Ref] docs move into apps/docs as their domain comes up, and each is archived with a pointer. The order of authority places the written pages with the specs and the generated pages with the references. The timeline gains TL-M0-25 (agent fork), TL-M0-26 (rule format and check), DOC pack A and TL-M0-27 (the register's move); every module from M1 on starts with a DOC pack, and BE pack E adds the generated pages. Moving to GitHub Team after cutover would bring agents from the fork into the repository, with rulesets and environment secrets.