The Document Filing Standard

01The one-screen rules

1. Two filename families only. Project docs: NNN-CC-ABCD-short-description.ext (001–999). Canonical cross-repo standards: 000-CC-ABCD-short-description.ext.
2. NNN is chronological — one global sequence for the whole repo, flat root and every subfolder. A file's number means when it was filed. 000 is reserved for canonical standards.
3. All codes are mandatory: CC (2-letter category) + ABCD (4-letter document type). Both come from the fixed tables below — never invented.
4. Descriptions are short: 1–4 words, lowercase kebab-case. No underscores, no camelCase, no sentence titles.
5. Sub-documents share the parent number: 005a-… letter suffix or 006-1-… numeric suffix. Never a folder.
6. Everything lives in 000-docs/ at the repo root, flat by default. A mandatory 000-INDEX.md lists what each file is.
7. Numbers never renumber. Renames are recorded in the index's rename table so references in old commits stay resolvable.

02Worked example — loose files → filed names

A real cleanup, from the reference repo. Left is what accumulates in every project; right is the same content, filed:

✗  AUTH-FLOW.md                       →  ✓  003-DR-REFF-live-auth-flow.md
✗  SOURCES.md                         →  ✓  004-BL-POLI-cca-source-reuse.md
✗  ATTRIBUTIONS.md                    →  ✓  005-BL-LICN-cca-attributions.md
✗  upstream-sync-migration-plan.md    →  ✓  007-OD-CHNG-upstream-v2-sync-map.md
✗  waiting-list-plan-FINAL-v2.md      →  ✓  011-PP-PLAN-waiting-list-gated-surfaces.md

Read any right-hand name cold and you know four things before opening it: when it entered the record (007), what part of the work it belongs to (OD — Operations & Deployment), what kind of document it is (CHNG — change management), and what it's about. The left-hand names tell you none of that, and they sort by accident.

03The decision path — naming any document in four steps

04Category codes (CC) — the complete table

These are the core categories you'll use daily. The 2-letter code answers "what part of the work does this belong to?"

Six additional single-purpose codes exist for legacy compatibility (PR, TM, AD, OP, RP, PL) — prefer the core table above for new documents.

05Type codes (ABCD) — per category

The 4-letter code answers "what kind of document is this?" Each category has a fixed vocabulary — do not invent new codes; if nothing fits, the category is probably wrong.

The combinations you'll reach for constantly: PP-PROD (a PRD), AT-ADEC (an architecture decision record), PP-PLAN (an execution plan), AA-AACR (an after-action report), DR-REFF (a reference doc), OD-CHNG (a change-management doc), RA-AUDT (an audit).

06Flat by default — nesting only at scale

Flat is the default because one ls showing the entire doc history is the whole point. Nesting is allowed only when both thresholds are met:

A folder is a cluster, not a category bucket

A nested folder must be a real cluster: docs bound by one subject you can name in a single sentence — an engagement (040-UC-kobiton/), an initiative (055-OD-vps-migration/), a subsystem, a report series, a research thread. Folders are coded like files (NNN-CC-cluster-name/, the NNN marking when the cluster opened), one level deep only, and the files inside keep the global numbering — a folder is a view; the number is the timeline.

A folder must never be:

• a category bucket (OD/, UC/) — the CC already lives on the filenamebanned
• a doc-type bucket (audits/, plans/) — the ABCD already lives on the filenamebanned
• a lifecycle bucket (archive/, wip/, done/)banned
• a catch-all (misc/, stuff/)banned

07What never gets filed — and why README.md stays put

Filing is the default for every loose .md. A file may only stay outside 000-docs/ if it falls in one of three provable classes — and the proof is recorded in the index:

Everything else gets filed. Deletion is never a default disposition — dead scratch is surfaced for explicit approval, never removed unilaterally.

08Reference implementation — a real 000-docs/

The now-lms repository (the Intent Solutions Learn platform fork) is the reference: eleven documents, one chronological sequence, PRD and decision records at their historical positions, and an index that carries the rename table:

000-docs/
├── 000-INDEX.md                                  # mandatory: what each file is + rename table
├── 001-PP-PROD-now-lms-fork-prd.md               # the PRD — what the product IS
├── 002-AT-ADEC-adopt-and-mature-upstream.md      # ADR-1 · the governing decision
├── 003-DR-REFF-live-auth-flow.md                 # reference: verified auth flow
├── 004-BL-POLI-cca-source-reuse.md               # policy: source reuse rules
├── 005-BL-LICN-cca-attributions.md               # licensing: attribution record
├── 006-AT-ADEC-rebuild-on-v2-sync.md             # ADR-2 · sync strategy
├── 007-OD-CHNG-upstream-v2-sync-map.md           # change mgmt: measured sync map
├── 008-AT-ADEC-curriculum-private-fork-public.md # ADR-3
├── 009-AT-ADEC-native-contact-message-storage.md # ADR-4
├── 010-AT-ADEC-gate-courses-doctrine-teaser.md   # ADR-5
└── 011-PP-PLAN-waiting-list-gated-surfaces.md    # the newest doc = the highest number

Note what the numbers do: reading 001 → 011 in order is reading the project's history — product definition, governing decision, references and policies, the sync strategy, three more decisions, the newest plan. The decision records (AT-ADEC) sit at their chronological positions in the global sequence, while each carries its own contiguous ADR-N number inside — the filename number is the timeline; the ADR number is the decision series.

Two floors every repo should meet, beyond naming: a PRD (PP-PROD — what this thing is, so future work has a baseline to diff against) and an ADR log (AT-ADEC, one immutable file per decision, superseded rather than edited — so nobody re-derives why).