# Doctrine — the epistemic core

Load when: composing or auditing any working-surface file; deciding what a turn's substance *is*
(a force, a fork, a commitment); judging whether a record is complete enough to harvest.

The session's product is a defensible design position. Five elements carry it — thesis, forces,
forks, commitments, consequences. They are ADR epistemics with the ceremony removed: everything
that made a decision record *citable* survives; everything that made it *bureaucratic* is dropped.

## The five elements

**Thesis** — the claim under construction. One composed document (`thesis.md`) in a mandated
readable shape: the **claim** (what we are building and the position taken), the **argument** (the
forces bearing on it and the reasoning chain from forces to claim), then **what most recently
changed and why**. Composed prose from turn one, rewritten whole at every compose — a document
maintained by appending can never read well. Every compose carries a `Current as of:` stamp so
staleness is visible instead of trusted.

**Forces** — the pressures that shape the design: user constraints stated in the conversation,
evidence from the repo or the field, platform realities, costs, prior doctrine. Forces are not a
file; they are the argument's raw material. A force lives wherever the reasoning that uses it
lives — the thesis argument, a commitment's Why — and is stated concretely enough to be checked
("the CLI gates consumer refresh", never "deployment concerns").

**Forks** — the open questions. A fork is the session's only convergence currency: flaws, gaps,
contradictions, uncovered aspects all funnel into `forks.md` or they don't exist. Every fork
carries a **close condition** — what resolution looks like: a pick, a confirmed fact, an accepted
risk. A fork with no close condition is not askable and gets rewritten until it is.

**Commitments** — the resolved calls, in `ledger.md`. Field set per entry:

- **Decision** — the call, one sentence, present tense.
- **Why** — the forces and reasoning that produced it. This is where declined options live:
  a **Declined:** line inside the commitment names the option, the evidence it was declined
  against *at decline time*, and a **re-evaluate condition** where one exists — the condition
  under which the rejection deserves another look. A deliberate call must never read later as an
  unexamined one; the re-evaluate condition is what turns a past-tense rejection into a standing
  tripwire.
- **How to apply** — what acting on the decision looks like in this repo.
- **Resolves** — the fork(s) this closes.

The ledger is **append-only with amendment-by-annotation**: a decision is real the moment it
lands; reversing it is a new entry that names what it reverses, plus a one-line annotation on the
old entry ("Reversed by …"). There is no tentative/committed/rescinded state machine — the fleet's
best sessions all proved append-plus-annotation carries the same information with none of the
ceremony.

**Consequences** — what a commitment obligates beyond itself: follow-on work, constraints it
places on future decisions, and where its knowledge must land at harvest. Consequences surface as
new forks ("committing to X opens the question of Y"), backlog candidates, or fragment content —
they are the element that keeps a ledger from being a list of verdicts with no forward pressure.

## What ADR epistemics keep

The parts that made decision records worth citing in shipped source:

- A decision is **addressable** — it can be named, cited, amended, and reversed by reference.
- The **reasoning travels with the verdict** — Why is mandatory, and declined alternatives ride
  inside it with their evidence.
- **Reversal is first-class** — a new entry naming what it reverses, never a silent edit.
- **Consequences are part of the record** — a decision that obligates work says so.

## What ceremony drops

The parts that died in every real session, kept out deliberately:

- **Status lifecycles** (Proposed → Accepted → Deprecated) — a commitment is live when it lands;
  reversal is an entry, not a state transition.
- **One-document-per-decision granularity** — the ledger is one file; harvest may split by
  subject, the session never does.
- **Immutability ritual** — annotation is allowed and expected; only the *meaning* of past entries
  is protected (annotate, never rewrite history).
- **Committee numbering as identity** — entries get short stable handles for cross-reference
  (D-notation), but conversation names decisions by what they are in plain words; codes are
  parenthetical.

## Epistemic rules

These bind every writer of the working surface — facilitator (ops), twin (everything else):

1. **Distilled, never verbatim.** Capture is interpretation: name the claim, the reasoning, and
   the implication. The ban is on transcript-pasting, not on quoting — integrity copies (printed
   enumerations, cited excerpts) are self-containment, not stenography.
2. **Examples are examples.** Record the general claim and cite the user's phrase as an instance
   of it. Never promote one phrasing into the frame — a thesis that reads beautifully but no
   longer says what the user meant is worse than one that reads badly.
3. **No naked pointers.** No pillar may lean on anything undefined in-folder: an enumeration
   cited by number gets printed once, a term gets a one-line gloss, an external citation carries
   an excerpt of its substance. A cold reader must never need the transcript or an external file
   to parse the surface. The same bar applies to harvest destinations — the uselessness test
   checks it there.
4. **Both sides are session knowledge.** The facilitator's own substance — causal diagnoses,
   informed rejections of options it presented, definitions of terms the surface cites, reasoning
   chains behind recommendations — is captured with the same discipline as the user's words. This
   is the historically leaked knowledge class; the ops ledger exists so it lands at zero cost.
5. **Directional steering is not feature truth.** A harvested principle informs many decisions
   and changes slowly; a feature fact belongs to its feature doc and changes at code speed. The
   harvest links between the two layers, never duplicates prose across them.

## Field lessons — capture and converge

Measured on live sessions; each is the rule, distilled.

- **Separate user voice from facilitator re-derivation before ledgering** when both arrive in one
  turn. Only the user's half is ledgerable; a re-derivation that quietly re-reads an existing
  commitment into a new shape is caught as a fork with a named amendment to the affected `D#`,
  never as an edit — a commitment recorded in the user's words is amended only by the user.
- **Stamp in UTC, always** — take the stamp from `date -u`, never from the runtime's injected
  local date; the two disagree for part of every working day in some offsets, and a local-date
  stamp runs the ledger a day ahead of capture.
- **Run the blindspot pass immediately after a converge burst, before the manifest gate.** When
  several picks land in one sitting the strain migrates *between* them — collisions between
  commitments taken within the same hour, found only by reading two together. The burst is the
  cheapest moment to catch them and the last before they freeze.
- **When a pick answers three of a fork's four close-condition clauses, close it and file the
  residue as a new fork in the same pass** — closing silently and leaving it open both lose
  information; name the unanswered clause in the resolving entry and carry it under a new `F#`.
- **When a ledger entry's `Why` contains "already", verify it before the manifest.** A commitment
  that declines to build something because it already exists rests on a fact, not a judgment, and
  the stop gate is the last place that fact is checkable — after the folder moves it is not.
- **Verify a doctrine claim against disk before building an argument on it.** Truth docs outrun
  package rebuilds: a guardrail can assert a guard path that exists nowhere, inside a suppression
  wrapper naming packages already deleted. When a session's centre is a recorded prohibition, `ls`
  the guard path, read the owning package's config, and confirm the package is still in the tree.
- **Read the decision records before framing a session around a pillar contradiction.** An AD
  accepted last week can already contradict the pillars; a session convened to *decide* a reversal
  may be *ratifying* one that shipped — a materially different conversation.
- **Give the opening map at least one aspect organised by seam.** A map organised by system layer
  owns none of the questions that land on the boundary between two planes or two phases, which is
  where the real design questions sit.
- **Ledger only the user's half of a re-derivation turn.** When the user states a segregation and
  the facilitator re-derives a whole architecture from it in the same entry, only the first half is
  ledgerable; a re-derivation that re-reads an existing commitment into a new shape is a fork with a
  named amendment, never an edit.
- **Check the ledger prefix against the product's vocabulary.** `D#` reads two ways in a product
  whose state lives in a database called D1; add a disambiguation line to the ledger header and
  write the colliding term in full inside entries.
- **The repo's rule files are a first-class blindspot source.** They carry platform facts a design
  can contradict unnoticed — a registry answering `404`, not `401`, to a restricted read turned a
  celebrated "containers hold no credentials" property into an open question. Read the rules that
  touch the session's substrate against the new commitments, not only the basis.
- **Absence in this repo is not absence.** Evidence for a premise often lives in a sibling
  repository; grep finding nothing proves only that this repo does not own the fact. Check the
  owning repo before filing a fork as unevidenced, and when the fact is confirmed there, the
  harvested record cites the external doc rather than restating it. A doc saying "this surface
  reports, it does not enforce" does not contradict "the platform enforces" — different layers,
  both true, neither edited.