# Documentation — the system, not the by-product

**One job: make documentation a deliverable with an address, an obligation and a
gate.** Not "write docs at the end" — a *system*: every settled thing has an id,
every fact has one home, every kind of change names the documents it owes, and a
script can say no.

This file is the **what and why**. [`gates.md`](gates.md) is how the script that
enforces it gets written; [`stages.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/stages.md) says where each piece binds.

**Governance is a by-product here, never a separate step.** The run already
produces decisions — the brief's *Decisions locked*, the spec's locked contracts,
the ADRs the grill writes. Recording one is **transcription plus a stable id**, not
new thinking. Anything below that feels like ceremony is a sign the register is
being written twice; write it once, here.

---

## Contents

- The canons — what makes a document evidence
- The inventory — four questions, answered before the first line of work
- Registers and ids
- Single source of truth
- A hand-corrected document drifts back within one run
- The Doc Loop
- Changing your mind
- The propagation matrix
- Navigation
- Intent and as-built
- Registers are shared state
- Where this binds in the pipeline
- Rationalizations

## The canons — what makes a document evidence

Ten laws. Everything else in this file, and the mechanisms in [`gates.md`](gates.md),
[`learned.md`](learned.md) and [`retrospective.md`](retrospective.md), exist to serve
them. Where a canon is already enforced by something, the enforcement is **named, not
restated** — a canon that repeats its own mechanism is the second home this system
exists to prevent.

**1. A claim carries its address.** Every fact that lands in a document names where it
can be checked: `file:line`, a command with its output, a test name. A lesson names the
commit that earned it. *"We verified it" is the sentence that passes every review and
proves nothing.* Where the subject is non-deterministic — an agent, a model call — the
address is **a trace id and the assertion that ran against it**, because a rerun is not
the same run and a description of the behaviour is not the behaviour. → the retro's
SHA-resolution guard; the finding shape in [`setup.md`](setup.md); [`tdd.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/tdd.md) →
*When the thing under test is an agent*.

**2. Numbers are computed, never restated — and an example that instantiates a number
IS one.** A count in prose is a number that was true once. Derive it at check time and
compare the stated one against the computed one as the same object. → [`learned.md`](learned.md)
rule 8.

The half that costs more, because it is written by the person who understands the rule:
**a document quoting a form as an example is indistinguishable from the form.** A release
note explaining *"the count was written wrongly as `Guards: 412 → 412`"* has just placed a
second readable count in a section whose count a gate reads — so when the probe removes the
real one, the narrative still matches and the guard reports green over a section that states
nothing. Measured three times in one hour on 2026-08-22, each time inside prose *about* this
very failure: the release note, the board row filed against it, and the repair to the probe.

The rule the umbrella already states for commands — **name a dead command, never claim it**
— holds for a number, a version and a shape. Describe the wrong form; do not write it.
*"the bold sat around the whole phrase instead of around the second number"* is checkable by
a reader and invisible to a pattern; the same sentence with the digits in it is a live claim.

**3. Every fact has exactly one home.** Other documents link to it; they never restate
it. Two homes do not disagree on the day they are written — they disagree on the day one
of them is updated. → *Single source of truth*, below.

**4. A reference resolves from where the document is read.** Not from where it lives. A
link correct in `templates/` and broken everywhere the template is seeded stays green
under every link checker, because the checker resolves from the file's home. → invariant
27; the seeded-template guard.

**5. Green nobody watched turn red is not evidence.** A check must be seen rejecting a
planted defect before its pass means anything — and the plant must be proven to have
landed in the text the check actually parses. **A model used as a judge is the same
object**: until it has been seen disagreeing with a human label on a case known to be
bad, its pass is an opinion with a number attached. → [`probing.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/probing.md) →
*Probing — plant, run, restore*; [`learned.md`](learned.md) rules 4 and 5; [`tdd.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/tdd.md) → *When the
thing under test is an agent*.

**6. A check proves its scope and nothing beyond it.** Every gate carries what it does
**not** cover, and quoting it wider is how "the gate is green" becomes a false statement
made in good faith. "The docs are in sync" is a command with an exit code, never a
sentence at the end of a report. → [`gates.md`](gates.md) → *Before you run a check*.

**7. Silence is not a pass.** Ask of any mechanism: what does it print when it did not
look? If that is indistinguishable from what it prints when it looked and found nothing
wrong, it is not evidence. → [`gates.md`](gates.md) → *False success*.

**8. An estimate is never announced as a measurement.** A rule that fires on a judgement
states its **evidence condition** — the observable signal that licenses it. A false
alarm does not cost one interruption; it costs the alarm. A score produced by a model
is an estimate and stays one in every report that quotes it, however many decimal places
it carries. → [`continuity.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/continuity.md) → *The context budget*.

**9. What was not checked is printed beside what was.** Absence is a finding with one
side, so it never surfaces by comparison. Carry it as a named, counted set next to every
verdict — a ratchet, never a TODO — so `PASS` reads as *"green, and here is what nobody
looked at"*. → [`learned.md`](learned.md) rule 7; [`gates.md`](gates.md) → *Ratchets*.

**9a. A measured zero and an unmeasured quantity may not print the same.** Canon 9 says
carry the absence; this says **refuse the number** when nothing measured it. `0 of 34
files read` and *the recorder was never installed* are opposite facts, and a `0` claims
the first while meaning the second — the most reassuring answer available, derived from
an instrument nobody switched on. So the unmeasured case prints a word, and the word says
why it cannot be a number.
The same refusal covers findings: a defect proven by reproduction records
incidence UNKNOWN — a word, never a zero — and stays a defect;
`templates/finding-evidence.json` is the minimal schema that keeps the axes apart.

The rule is written down because it arrived three times under three names before anyone
named it: `references/knowledge-graph.md` → *State zero out loud* (a fresh graph must
still print `current, 0 commits behind`, or freshness is indistinguishable from a harvest
that never looked); `references/verification.md` → *Staleness* (`unanchored` and
`unresolvable` are states, not zeroes); and `scripts/graph.py` → `doctrine`, which prints
`unmeasured` and its reason rather than `0 of 34`, and `next`, which reports how many
runnable nodes declared no `touches` so that no collision is not read as no collision
found. Three sites, one rule, and the fourth will be written from this line rather than
from the same mistake.

**10. The document ships in the change that made it true.** Not in the next ticket —
documentation deferred is documentation that describes a system nobody is running. A
correction is **appended**, never edited over: a register that is rewritten loses the
fact that it was ever wrong, which is usually the useful part. → *The Doc Loop*, below.

### What these are not

They are **epistemic**, not operational: they say what makes a claim documentation, not
what to do at a trigger. The operational layer is [`learned.md`](learned.md) — each rule
there carries a trigger, a check and an exit criterion. When the two seem to say the same
thing, the canon is the *why* and the rule is the *how*; edit the rule, cite the canon.

---

## The inventory — four questions, answered before the first line of work

Stage 0 answers these before the interview, and writes the answers to
`docs/DOCMAP.md` (seeded from [`../templates/docmap.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/templates/docmap.md),
**only when absent** — never overwritten):

1. **Where do settled things live?** The decision home, and its id scheme.
2. **What is each fact's single home?** One place per fact; everything else links.
3. **What does a change of type X oblige?** The propagation matrix.
4. **What proves it?** The gate command, and what it does *not* cover.

A project with no answers gets them seeded. The seeding is itself recorded as the
first entry in the register, which is the cheapest possible demonstration that the
register works.

**There is no "we don't document" answer.** The four questions have answers in every
repository — the smallest one still decides *somewhere* that a thing is true — and
the only choice is whether that answer is written down or re-derived by each new
reader. What scales down is **volume**, never the rules: a register with three
entries is a register, and the seeded gate is green on exactly those three
([`gates.md`](gates.md) → *Progressive arming*).

---

## Registers and ids

**One decision home per project. The doc map names it. Never create a second.**

Two shapes satisfy the contract; the difference is physical, not semantic:

| Shape | Home | Id | Use when |
|---|---|---|---|
| **Register** | `docs/DECISIONS.md`, append-only | `DEC-####` | default; many small decisions, read as a list |
| **ADR set** | `docs/adr/NNNN-<slug>.md` | `ADR-NNNN` | the project already has `docs/adr/`; decisions are long and each wants a page |

**Detect, don't assume:** `docs/adr/` holds at least one `NNNN-*.md` → that is the
register, record it in the doc map and use it. Otherwise seed
[`../templates/decisions.md`](../templates/decisions.md). An existing ADR set is
**never migrated** as a side effect of some other task — migrating is its own
decision, with its own entry.

Both shapes owe the same six things: a **stable id**, an **append-only** history, a
**status line** with the supersede semantics below, a **`Consequences / affects:`**
line, a **`Source:`** line carrying the run and the **commit**, and the **edge
markers**.

Open questions get their own register (`docs/OPEN_QUESTIONS.md`, `OQ-####`) with a
closed status vocabulary: `Open` · `Resolved→DEC-####` · `Dropped (<why>)`.

**Two rules that look like formatting and are not:**

- **Reference facts by id, never by copying the text.** A copy is a second source
  that nobody will update, and the reader cannot tell which one is current.
- **Ids are never renumbered and resolved questions are never deleted.** The
  question is the history of the answer; without it the next reader re-litigates a
  settled thing from scratch.

---

## Single source of truth

**Every fact has exactly one home. Everything else links to it.**

If the same fact is stated in two places, that is a **bug** — collapse it to one
home and link from the other. Not because duplication is untidy: because the two
copies will disagree, and at that moment both become unusable, since nobody can
tell which one moved.

- The *decision* lives in the register. Topic docs describe the *current design*
  and cite the id.
- Each topic (architecture, data model, security, …) has one canonical document.
- Indexes and summaries **link**; they never restate a rule.

### Across repositories

**The owning repository decides; a consumer repository describes.** Where a
consumer document disagrees with the owner, the consumer is wrong — stated rather
than adjudicated case by case, because case-by-case is how a consumer repo starts
legislating.

The boundary is worth writing out, because an unqualified "the owner always wins"
is false in one direction: **build state and task status belong to the repository
doing the work**. A submodule is cloned alone, and a status update must not require
two repositories.

Changing a consumer repo's documentation: compare against the owner's canonical
doc → look for a contradiction with it *and* with any accepted decision → if the
consumer document is wrong, fix it in place; if the **owner** is wrong or stale, it
is corrected there, by a decision entry, through a pull request — and the consumer
document stays divergent and marked until that lands. Quietly aligning a consumer
doc to its own view is the failure this paragraph exists to prevent.

---

## A hand-corrected document drifts back within one run

A board, backlog or status document gets corrected during an audit; the same
contradictions are back inside a day. **Correcting it again is the same
intervention at the same cost, not a fix.**

Measured: four contradictory boards were consolidated into one, every row
re-checked against its source. Within 24 hours a row settled in code that morning
read `open` again — in **two** places, because a row listed in a section table and
again in a summary has to be closed twice. Another called two files missing while
one had been written five hours earlier. A count quoted from a generated ledger had
moved and the row had not.

**Why the manual pass cannot hold.** A document's claims are never executed. Nothing
distinguishes a row that **is** true from one that **was** true, so the audit that
corrects it is the only reader that checks — and it runs once. Between audits the
document is a set of assertions with no mechanism behind any of them, ageing at the
speed of the work it describes.

So a correction is not done when the rows are right. It is done when **something
other than the next audit** will notice them going wrong:

| The claim | What makes it self-checking |
|---|---|
| a row's status | derived from the artefact that settles it, or a gate that fails when the two disagree |
| a count | computed at check time and printed beside its command — never transcribed |
| "these files are missing" | resolved against the filesystem by the check that prints it |
| a row in two tables | one table, or a guard asserting the pair agrees |

Where a claim genuinely cannot be derived, **say that in the row** — an assertion
marked as unverifiable is honest, and the next reader stops treating it as measured.
Silently correcting it a second time is how a document teaches its readers that
somebody else is checking.

---

## The Doc Loop

**Fires whenever something is settled — at any stage.** Scope, a contract, a name,
a policy, a status vocabulary, a price, a retention window. Not only at stage 9.

1. **Orient and reconcile.** Read the register and the topic doc. Run the
   intent/as-built reconcile (below). Do not contradict an accepted decision
   without superseding it. *Skipping this is how a run spends a day building
   against a system that does not exist.*
2. **Reserve the id, then record.** Reading "Next free ID" is **not** reserving it
   (see *Registers are shared state*). Then write the entry: date, status, context,
   decision, consequences, source with the commit.
3. **Resolve.** Flip every answered question to `Resolved→<id>`. Never delete it.
4. **Propagate.** Walk the matrix row for this change type and update every
   document it names, **in the same change**. Keep SSOT: the detail in one home,
   links from the rest.
5. **Adjust scope.** Roadmap, MVP, module map — if scope moved.
6. **Record as-built.** What was actually built, with the ids and the files. Then
   reconcile again.
7. **Commit.** One focused commit, conventional message, **the ids in the subject**.

**Finishing the chat answer is not finishing the task.** Closing the loop is. A
decision that lives only in a spec dies with that spec; one that lives only in the
conversation was never made.

---

## Changing your mind

The register is **append-only**. To reverse or replace:

- add a **new** entry stating the new decision and naming what it replaces;
- edit **only the status line** of the old entry;
- leave the old body intact as history.

**A partial supersede annotates both sides.** Most reversals are partial — a later
decision replaces one clause and leaves the rest standing. If the old entry keeps a
bare `Accepted`, a reader who opens only that entry gets an answer that is no longer
true. So the new entry names which clause it replaces, and the old entry's status
line gains `· **Partially superseded by <id>** — <one line>`.

**Three markers, and they mean different things:**

| Marker | Meaning | Target's status line annotated? |
|---|---|---|
| `Refines:` | **additive only** — every clause of the target still holds | no |
| `Contradicts:` | a **named clause** of the target no longer holds | **yes** |
| `Supersedes:` | the whole target is retired | **yes** |

One word for "adds to" and "replaces a clause of" is unenforceable. Measured on the
project this practice comes from: across **275** refine/supersede edges, **204**
pointed at a target with no annotation — which is not 204 violations, because most
were additive. *That ambiguity is the defect*: neither a reader nor a script could
tell which of the 204 should have been annotated, so the rule could not be gated at
all.

**Existing edges are not retro-classified.** Each needs a judgement about what its
author meant, and a bulk pass would guess. An edge is reclassified when someone
touches it for another reason.

---

## The propagation matrix

The harvest ledger ([`knowledge-sources.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/knowledge-sources.md)) names the
documents you **read**. The matrix names the documents you **owe**. They are not
the same list, and the gap between them is where documentation rots: the document
nobody read is exactly the document nobody updated.

**Build it in five steps** (stage 0; extend it whenever a new doc class appears):

0. **Write the meta-row first: *a new document or rule*.** The most frequent change
   in any documented project is adding a document, and it is the row nobody writes —
   so the matrix ends up unable to catch the class it will meet most often. Its
   *Update these* column is every surface that must **learn the thing exists**: the
   index a reader opens, the map, any manifest, the agent-facing rules file.
   Measured on the project this practice comes from: **nine findings across five
   audits were that one missing row**, and the checks were green throughout, because
   a check can only walk the list it was given.
1. List the project's doc classes — one line each: what is this the home of?
2. For each **change type** the project can undergo, name every document that must
   move.
3. For each row, name the **check** that would notice if it did not — or write
   `review` *with a one-line reason why no check can decide it*.
4. Write the rows into `docs/DOCMAP.md` → *Propagation matrix*.
5. Arm the mechanical half in the gate: **a document named in an entry's
   `Consequences / affects:` line must cite that entry.**

A row with an empty third column is a **finding**, not a blank. Either a check
exists, or somebody has said out loud that none can.

**The backlog is ratcheted, and that is the design.** Turning this check on in an
existing repository finds a lot: **162** missing propagations across **73**
decisions, on the project this comes from — not the four the audit had reported.
Failing on all of them makes the gate something people switch off, and bulk-fixing
them blind adds 162 citations nobody verified. So: entries from a **floor** id
onward fail; everything older is a counted backlog that may only shrink, printed on
every run. Raising the floor is a decision, and it belongs in the register.

---

## Navigation

**One definition per entity, and a mention links to the definition.**

- Every definition carries an explicit anchor.
- A mention links to the **anchor**, not the file. A file link makes the reader
  search; a deep link that rots is caught by the gate.
- **Indexes never restate a rule.** They fall behind and then they lie with
  authority — a navigation aid that omits an entry is worse than none, because a
  reader concludes the entry does not exist.

A deep link is worth more than a file link *and* fails harder, so it only pays with
a check behind it. Land the anchor check with the first rewritten link, not after
the sweep.

---

## Intent and as-built

Two records, deliberately not merged:

| Record | Says | Written by |
|---|---|---|
| **Intent** — the registers, the spec, the plan | how it *should* be | the Doc Loop |
| **As-built** — the run record | how it *turned out* | step 6, at the end |

**Reconcile both before starting and after finishing.** Every divergence has one of
three resolutions: the document is stale, the record is wrong, or they genuinely
disagree and that is a decision to make. There is no fourth, and "I'll keep it in
mind" is not one of them.

Where a coordination tool is installed it does this for you. Where it is not, the
as-built record is a section of the carry-over ledger and the reconcile is a read
of it — **the tool is optional, the discipline is not**.

---

## Registers are shared state

A register is the one file two agents will write in the same minute.

- **Reserve the id before minting it.** "Next free ID" is a *reading*; a second
  agent reading it in the same minute gets the same answer, and now two entries
  carry one number.
- **Take a lease before writing a guarded register**, where a lease mechanism
  exists. [`hooks.md`](hooks.md) is how such a guard blocks the edit;
  [`companion-skills.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/companion-skills.md) names the optional companion that
  implements one.
- **Ask what two instances with the same identity would do**, and make the tool
  answer it. This is [`learned.md`](learned.md) rule 15, and it is in that table
  because it cost an entire day of work performed under another session's identity.
- **When nothing can arbitrate, the run is `ungated` — say so out loud.** That is
  a real state, not a formality. Describing a project as protected while nothing
  enforces it is worse than having no protection, because everyone downstream
  believes the guarantee.
- **A register declared against a backend that cannot reserve is a register in name
  only, and its presence is what stops the manual procedure being written.** Measured
  2026-08-15: a project declared three id registers over a local-filesystem backend
  whose `reserve` correctly refuses — *pretending would hand two agents the same id* —
  and two sessions filed a different `B-073` on the same afternoon. The tool was honest;
  the *declaration* was the problem, because a capability that appears to exist is one
  nobody replaces. Where reservation is not available, write the three-step manual
  allocation down where an agent reads it, and make it follow the lease:
  1. take the lease on the register's file **first**;
  2. compute the next id from the **committed** file — `git show HEAD:<file>` — never
     from a working copy, which holds your own unpushed row and hides somebody else's;
  3. write and **commit** before releasing the lease. An id held only in an uncommitted
     file is an id nobody else can see you took.
- **A version number is the same class with no register at all.** Two branches both
  claimed one version on that same afternoon because each incremented from what its own
  checkout knew. Read the remote — `git ls-remote --tags` — because that list is the only
  place the answer lives.

---

## Where this binds in the pipeline

| Point | What happens | Gate |
|---|---|---|
| **Stage 0**, phase 1b | the inventory — the four questions, into `docs/DOCMAP.md`; the regime recorded | manual |
| **Stage 0**, phase 1c | intent vs as-built reconciled; every divergence resolved | manual |
| **Any stage** | something is settled → the Doc Loop, all seven steps | the stage's own |
| **Stage 9** | the propagation sweep, the registers, the gate green with its ratchets printed | auto |
| **Stage 10** | the gate itself proven — every check seen failing once against a planted defect | manual |

---

## Rationalizations

| Excuse | Reality |
|---|---|
| "It's a small project, a register is overkill" | A register with three entries costs three minutes and is the only reason the fourth decision can be found. What people mean by overhead is *ceremony*, and none is required here — the entries are transcribed from artefacts the run already produced. |
| "I'll write the decision up at the end" | At the end you remember the outcome and not the alternatives you rejected, which is the only part with any value later. |
| "The spec already says it" | A spec is per-run and the next one supersedes it. A decision outlives every artefact that mentions it. |
| "I updated the docs I touched" | The matrix names the documents you did **not** touch. That is the entire reason it exists. |
| "Two docs saying the same thing is harmless" | Until they disagree — and then both are unusable, because nobody can tell which one moved. |
| "I'll just fix the old decision's text" | Then the reason someone chose it is gone and the next person re-litigates it from scratch. Supersede; never edit the body. |
| "It's obviously additive, no need to mark it" | 204 of 275 edges were left unmarked on exactly that reasoning, and afterwards nobody could tell which of them should have been. The marker costs one word. |
| "Nobody else is working in this repo right now" | You cannot know that from inside your session, and being wrong means two entries with one id. |
| "The gate is green, so the docs are fine" | The gate proves what it checks. Read its scope header before quoting it as evidence. |
| "The doc is stale but that's not this task" | Then it is a row in the carry-over ledger with the exact edit, right now. A staleness noticed and unrecorded is the next run's false premise. |