Records that do not drift

A decision log, a requirements list and an architecture diagram are only worth keeping while they still describe the code. In onMain they are written by the work that changes it, and read before the next change is planned.

Why the documents drift

In most repositories the decision log, the non-functional requirements and the architecture diagram start accurate and then stop. Writing them is a separate job from changing the code, done later by someone else or not at all, so the code moves on and the documents describe the version before it.

Written by the work, read before the next

In onMain a decision, a functional or non-functional requirement, and a plan are records, each with its own reference and a status. The coding agent writes them through the MCP while it plans the change: the plan for a card mints the decisions it needs and cites the ones it rests on. The next session reads those records before it plans, so what was decided last time is the first thing the next change sees.

A real chain

One chain from the records behind this site, quoted as they stand. Each record is joined to the one above it: a card is planned in a plan, a plan cites the decisions it rests on, and a decision amends an earlier one rather than rewriting it.

  1. Card 576Different Color Scheme across .dev and .ioA card on this site’s backlog

  2. planned in

    Plan 028The two sites look like two sites: onmain.dev turns soft charcoal and onmain.io's prompt reads "onMain Agency", with every token reader taught that a second scheme exists before one doesThe plan written for that card

  3. cites

    ADR-021Each site has its own scheme: onmain.dev is soft charcoal and onmain.io stays light, chosen by the site at build time; the panel takes its own token; the agency prompt names its editionA decision the plan cites

  4. amends

    ADR-018The page is built from components on a light-only system: a named fluid-token list, two unasserted grounds, color-scheme declared, and a size guard that refuses rather than guessesThe decision it amends

  5. amends

    ADR-010Light only, and the favicon is the mark's pair: the dark scheme and the caret-only favicon goThe decision that one amends

ADR-010 made this site light only. When the site turned charcoal, the decision that did it amended ADR-010 instead of replacing it, so both still say what was decided and why.

One architecture, kept current

Each project keeps one living architecture in five views: the system’s context; its containers, services and realms; its data and boundaries; its deployment; and what cuts across them, such as authentication and transport. A phase of a plan that changes the structure updates the view it changes in that same phase, so the picture moves with the code instead of after it.

Coming: the Knowledge Hub and graph

The next step is one connected graph across every record a product holds, which a person or an agent can walk from a card to the decisions behind it and back. It does not exist yet; the links on this page are the records’ own.

Questions

Who sets a record’s status?

The process, not a lock in the product. A plan proposes the decisions it takes; when the owner approves the plan, the process marks them accepted, and marks any decision one of them replaces as superseded. The tools themselves will set any status, so the rule lives in the Standard every session follows.

Can a decision change after it is accepted?

Yes, in two ways. A record can be revised, and its version moves with each revision. Or a later decision amends it, or supersedes it with a successor, and names what it changes, so the earlier reasoning stays readable instead of being overwritten.

Does every change need a decision record?

No. A plan mints one when it settles something architectural or starts a new pattern. Most plans cite the decisions that already exist and mint none.