---
status: accepted
date: 2026-08-23
deciders: jochen
reconstructed: false
---

# 24. The folder numbering is the flow, and decision records run oldest first

## Context

Two orderings were wrong in ways that only show up when someone new reads the repository.

**The folders.** Decisions lived in an unnumbered folder that sorted after the numbered ones,
so the repository's most load-bearing content read as an annex.

The sibling HQ repository for the PAPA platform had already solved this and solved it
crookedly: its design folder existed from its initial commit, and when its decision folder was
finally promoted it took the **next free number** rather than its place in the sequence. That
repository now reads `01 research → 03 decision → 02 design`. A decision precedes the design
it authorises and is numbered after it. By the time this was visible, the design folder was too
settled to renumber.

**The records.** Fourteen decisions had been taken in implementation and never written down —
the broker, the module abstraction, the mesh database, the artifact, the three silos and the
rest. Meanwhile two records existed, holding numbers 0001 and 0002, for decisions taken last.

## Considered options

1. **Match the sibling repository exactly**, inheriting its ordering. Rejected: structural
   parity is worth something, but not the cost of copying a scar the other repository would
   not choose again.
2. **Leave the folder unnumbered.** Rejected — the annex problem, and it leaves an unexplained
   gap for anyone arriving from the sibling repository.
3. **Number by position in the flow, and renumber the records chronologically.** Chosen, on
   the grounds that this repository was four commits old and nothing outside it cited a
   number. That is the only window in which either renumbering is free.

## Decision

**The numbering is the flow.** Research produces a decision; the decision authorises a design.
So `01-RESEARCH`, `02-DECISIONS`, `03-DESIGN`, `04-ISSUES`. Following the folder numbers walks
the process in the order it happens.

**Decision records are a chronological ledger.** They run oldest first. The fourteen decisions
already taken in implementation were back-filled as records 0001–0014, each dated from the
history, each carrying `reconstructed: true` and saying so in its first lines, and each citing
the commit, pull request or knowledge-base entry it was recovered from. The two existing
records moved to 0015 and 0016.

A reconstructed record is not a transcript. Where the deliberation is not recoverable it states
what the alternatives were and why the chosen one won on the evidence available — not a
discussion that did not happen. Where a date is not establishable it says so.

The foundational folder is `00-META`, matching the sibling repository.

## Consequences

- The repository reads in process order, and the gap at `03` that a reader coming from the
  sibling repository would notice is explained by this record.
- The design documents can cite reasoning instead of asserting rules, because the reasoning now
  exists.
- Structural divergence from the sibling repository, deliberately, in exactly one place. It is
  recorded here so that the difference reads as a choice rather than an accident.
- **Record numbers are now stable and renumbering is over.** This decision spends the one
  window that existed; a future record takes the next free number regardless of its date.
- Reconstructed records carry a standing risk: they are the most confident-sounding documents
  in the repository and the least directly witnessed. The `reconstructed` flag exists so that
  is never invisible.

## References

- The sibling repository's restructure of 2026-07-13 moved its decision folder in a single
  commit of twelve renames with no content change, alongside the same status-into-frontmatter
  and playbook changes made here.
- [`02-DECISIONS/README.md`](README.md) — the format, and the note on reconstructed records.