Skip to content

Document Governance

Status: Current — this file is the rule, rewritten 2026-08-27. Owner: delan

Rewritten: 2026-08-27

Purpose

This project has one recurring failure: a document is written, labelled official, and then reality moves without it. Nobody deletes it, so it keeps answering questions wrongly. Over five months that produced four competing backlogs, two forked GDDs, and two architecture documents specifying different databases.

This file exists to prevent that, not to describe an ideal.

The one rule

A document is either live or archived. There is no third state.

There is no "old but still official," no "superseded but kept in place," no "mostly right." The moment a document stops being true, it moves to _archive/ in the same commit that makes it untrue.

The second rule: every live document declares its status

Currency is not the same as kind. A document can be perfectly current as a proposal and still be a lie if it is filed as documentation. The August 2026 audit found several — the GPT-5.4 card pack described 100 cards of which eleven of twelve spot-checked did not exist, and PackageModel.md said "no code committed" while three builders and a controller shipped.

So every live document carries a status block directly under its H1:

> **Status:** Current — verified YYYY-MM-DD.
> **Owner:** name

Permitted statuses:

Status Means
Current Describes what exists. Verified on the stated date.
Partially implemented Part is built, part is intent. The block must say which.
Proposed — not implemented Nobody has built this. Lives under docs/proposals/.
Art direction Briefs look and feel; specifies no code, so implementation status does not apply.
Partially stale Known out of date, not yet re-verified. Says what was checked and when.

A status claim needs evidence — a file path, a class name, a count. "Verified" with nothing behind it is how this set rotted the first time.

docs/proposals/ is not a third currency state. Its documents are live and maintained; they simply describe intent rather than fact, and the directory makes that unmissable. When a proposal ships, it moves out and its status becomes Current. When it is abandoned, it moves to _archive/.

Source hierarchy

When two live documents disagree, resolve in this order. Each layer owns a different kind of truth and should not answer for another.

Layer Owns Location
1. Story canon Lore, factions, Alden, voice, names story/bible/
2. Rules canon What the player does; terminology; mechanics docs/official/
3. Implementation truth How it is actually built and deployed docs/tech/
4. Card design (intent) The designed card pack — proposed, not built docs/proposals/card-pack-gpt54/

If a rules document and the implementation disagree, that is a bug report, not a hierarchy question — one of them is wrong and someone has to decide which.

Anything in _archive/ ranks below all of these and is never a tiebreaker.

Story is governed separately, and better

story/ has its own working agreement (story/claude.md) with a canon tree, a permanently read-only archive, and a dated decision log (story/bible/canon-decisions.md) recording what was decided, why, and what was rejected.

Do not duplicate story content into docs/. Link to the bible. The July 2026 House renames — Syntacta → the Axiom, Annalis → the Censors, Aethari → the Syndicate — were ratified in canon-decisions.md on 2026-07-03 and are canon regardless of what any other document, asset filename, or code identifier still says.

What belongs in docs/official/

Only documents that answer a recurring cross-discipline question about the rules of the game, and that someone will maintain.

The live set is deliberately small. Every entry is verified Current or Partially implemented as of 2026-08-27; see each document's status block:

What does not belong here

  • Plans and status snapshots. They are true on the day they are written and misleading a month later. If you need one, date it in the filename and put it in docs/evaluations/.
  • A second backlog. todo-inventory.md or nothing. Four backlogs meant no answer.
  • Story or lore. That is story/bible/.
  • Kickoff, audit, or brief documents. These are session artefacts. Archive on completion.
  • Anything with an owner of "nobody."

Maintenance obligations

  1. Publishing is a live-set decision. mkdocs.yml publishes docs/ to a public site. A document added to the live set gets added to the nav in the same commit; an archived one gets removed in the same commit. Nothing superseded stays publicly readable.
  2. Fix links on move. A live document must never link to _archive/.
  3. Date claims, not documents. "410 tests passing as of 2026-03-05" ages honestly; "410 tests passing" does not.
  4. No Last updated: header without updating it. DevelopmentStatus.md carried a March date through a July edit. Either maintain the line or delete it — git already knows.

Current canon decisions

  • story/bible/ is story canon. The GDD is archived salvage material, not a source.
  • docs/tech/Architecture.md is the single technical truth. The system runs SQL Server and Kusto. The PostgreSQL/ClickHouse specification is archived; do not reintroduce it.
  • The GPT-5.4 card pack (docs/proposals/card-pack-gpt54/) is the intended card design, not a description of the game. Verified 2026-08-27: eleven of twelve spot-checked card names do not exist in code. The shipping pool is data/content/cards.json — 584 published cards, 80 per class. Neither this pack nor the 49-card ProductionRiftContentCatalog.cs bootstrap seed is the card list. See docs/tech/ContentPipeline.md.
  • House names are canon per canon-decisions.md (2026-07-03). Code identifiers, seeded data, and asset filenames still use the pre-July names; that is known propagation debt, not an open question, and is tracked in todo-inventory.md.