# Rows — the row, the verdicts, the residue guard

Load when: writing or reading any row, judging a CONTESTED or QUESTION row, deciding whether a subject is residue, or ruling on a document's right to exist.

## The row

Pipe-delimited, one row per claim, **ten fields**, header line first. A literal `|` inside text is written `¦`; a newline becomes `; `.

```
id|subject|claim|evidence|counter_evidence|verdict|confidence|depends_on|status|resolution
```

| Field | Content |
| --- | --- |
| `id` | `{DOC}-{NNN}` — the target document's stem and a running number, unique within the run |
| `subject` | the stable key — a file, table, route, command, or surface |
| `claim` | one sentence: what is asserted true or false |
| `evidence` | verbose support — `file:line` citations or the exact command and its result. **No citation, no row.** A verdict leaning on a precedent quotes the precedent's naming words here |
| `counter_evidence` | what cuts the other way, including `already-registered: path:line` for a known item |
| `verdict` | one of the seven below |
| `confidence` | 0.0–1.0, honest — a signal that tells the primary where to look, never a routing key |
| `depends_on` | empty, or the owner question the row waits on, as the question's own words in brief |
| `status` | `open` · `resolved` · `reopened` |
| `resolution` | how it closed — `applied` · `registered` · `did not reproduce` · `answered` · `exempt-frozen` — empty while open |

**A negative claim about a long document quotes the passage read** — the sentence believed wrong, or the section where the missing statement should live. Unsupported negative claims are the dominant false-positive class, and they concentrate in the longest documents.

## The seven verdicts

| Verdict | Meaning | Disposition |
| --- | --- | --- |
| `COHERENT` | doc and code agree — emitted at the audited unit so coverage is countable; closed when recorded | none |
| `MISDESCRIBED` | the doc is wrong about built behaviour | an applier fixes the doc |
| `UNDOCUMENTED` | code no doc claims — judged against the precedent pack **first**: condemned code is RESIDUE, never a documentation gap | an applier documents it in the owning doc |
| `UNBUILT` | a documented design with no code behind it — decided-unbuilt (the repo's marker convention), abandoned, or a document that should die; only the owner distinguishes the last two, so suspecting either makes the row a QUESTION | the marker |
| `RESIDUE` | code a standing decision condemns by name — running, even load-bearing, and still retiring | a register row, never a doc edit |
| `CONTESTED` | the evidence conflicts — a verifier and a finder disagree, or a claim has no code to arbitrate and a sibling document says otherwise | the primary judges with both sets of evidence in hand |
| `QUESTION` | only the owner can resolve it — intent, not evidence, is what is missing | asked inline, answered in the same pass |

A disposition is the verdict's default; where the primary overrides it, the resolution says so. **A verification never overwrites a verdict** — disagreement makes the row CONTESTED.

## The residue guard

Before an UNDOCUMENTED row becomes a doc edit, its subject is tested against the precedent pack — the one place the audit can silently undo the repo's own decisions. The test is **naming**: a precedent matches only when it names the subject — the file, table, route, command, or surface by the product's own name for it — and the row quotes the naming words into `evidence`. A precedent describing a *resembling* thing is not a match; shared adjectives ("legacy", "old export lane") are not a match; a misread pronoun is not a match. Unsure → QUESTION, never a silent RESIDUE.

The asymmetry runs both ways. A missed match resurfaces: the register is owner-read, and an UNDOCUMENTED row that should have been RESIDUE is caught when the owner reads the doc it produced. A false match does not: it retires code the product still ships and withholds its documentation — worse than the disease. When in doubt, ask.

## Frozen records and code

- **Frozen records are exempt** — a completed plan, a changelog entry, an archived document resolves `exempt-frozen`; its claims were true when frozen and the tree does not correct history.
- **The audit never edits code.** A code-side finding — a bug, a stale source comment, the unbuilt, residue — exits as a register row for the planning workflow, however small the edit and however directly it is asked for. **Markdown is not source**: every document read may be edited under the applier discipline, package and root READMEs included; the line is doc versus code, not proximity to `src/`.

## A document's right to exist

A wholly stale document passes a sentence-by-sentence audit one true sentence at a time, so a finder that reads a document whose subject is gone, whose authority another doc has absorbed, or whose content belongs inside a sibling emits **one QUESTION row proposing deletion or merge**, carrying the inbound-reference count (who links here, which index rows list it, which ownership globs it claims). Deletion is owner-approved, always. An approved deletion removes the file, repoints every inbound reference to the surviving authority, and leaves **no redirect stub** — an annotation, a banner, or a status flag left in the reading path is not a source of truth however carefully the surviving sentences are hedged. A document whose subject survives but whose content is wrong is MISDESCRIBED, not a deletion candidate.

**Abandonment has no marker.** A design decided against is not owed: its claims come **out** of every marker that carried them rather than being reworded inside one, and the document survives as the record of a decision not to build, its status saying so. The tell that this went wrong: a reader finishes the paragraph still expecting the feature.