Registers

Knowledge that invalidates a brief. A new finding names the briefs it affects; every one of them is flagged stale-knowledge and held out of the work queue until the finding resolves. That exclusion is the point: a discovered problem must not be outrun by the work it invalidates.

Each finding is its own file under docs/streams/findings/, with frontmatter carrying:

• Typed ID: F- plus a slug of 10–20 characters derived from the title — for example F-ws-token-expiry. Not a counter; see below.
• Date and title: when it was recorded and what it is.
• Body: what was found, the evidence, and the fix direction.
• Affects: typed IDs of the briefs it invalidates. The validator cross-applies these and fails if one does not resolve.
• Ack: the desk's on-record judgment that the finding is real. Anyone may file a finding, but only an acknowledged one can hard-error a brief already in flight — otherwise any session could drop a rival's work by filing a paragraph.
• Resolved: yes or no. Resolve by updating the affected brief to reflect the finding, then flipping the field.

The single FINDINGS.md is a generated view over that directory, on the same single-writer discipline as the board: regenerated by the mainline branch's CI, never hand-edited.

Findings originally used a counter — F-01, F-02 — inside one shared file, and the contiguity of that counter was the tamper-wire: a missing number was the visible signature of a deleted entry. Under parallel authorship the counter became the problem it was solving. Two sessions filing at the same moment claim the same number, and a register whose entries collide is a register people start working around.

So the scheme changed, and it is worth being exact about what was traded for what. Slugs carry no contiguity guarantee. There is no sequence, so there is no gap to detect, and an implementation must not claim gap-detection as a property of this scheme. Three properties replace it, required together:

• A tombstone check against history. Any entry file that has ever existed on the mainline branch but is absent from the working tree is flagged. This is what actually catches a deletion, and for the case it covers it is stronger than the gap check was — it names the missing file instead of inferring that something is missing.
• A duplicate-ID check. Two entries sharing an ID are flagged.
• Diff visibility. An entry is a whole file and the roll-up view has one writer, so both a deleted file and its disappearance from the view show up in an ordinary change diff.

Entries created before the change keep their numeric IDs. Those are frozen legacy and stay valid; a numeric ID on a new finding is a lint failure.

Raw ideas that enter the system before they become briefs or get turned down. Every proposal gets an entry, and every entry gets a recorded disposition — so a "no" is a numbered record with reasoning, not a conversation nobody can find later.

An intake entry records:

• Typed ID: I- plus an identifier.
• Date and title.
• Body: the idea, motivation, and scope.
• Disposition: accepted (authored into a brief), deferred, rejected, or duplicate.

Withdrawal is a tombstone in place — flip the disposition rather than removing the entry. Deleting one to make a number disappear loses the record, which is the single thing the register exists to prevent.

The register set is often described as three logs, the third being a per-cadence retrospective. Plainly: no such register exists in the reference implementation. There is no retro parser and no entry directory, the specification's section on it is marked informative rather than normative, and no conforming linter enforces anything about it.

The retrospective practice is real and is described in the methodology — it reads instruments rather than narrative (board totals, streams untouched since the last pass, what the gates actually caught, register ages) and admits at most one process change per cadence, and only the one that displaces the current worst pain. What does not exist is a machine-checked register behind it. This is documented rather than quietly dropped because the distance between a described practice and an enforced one is exactly what this methodology exists to make visible — including when the gap is ours.

• Append-only. A new entry is a new file; existing entries are never edited away. These logs are the audit trail, and a record you can rewrite is not a record.
• Withdrawal is a tombstone, never a deletion. Keep the entry, flip the disposition or resolution, explain the withdrawal in the body. The history of being wrong is itself evidence.
• Typed IDs only. Entries reference briefs and other entries by typed ID (stream/NN, F-<slug>, I-<slug>) — never prose names, which stop resolving in silence.
• Findings propagate staleness. An unresolved finding holds every brief it names out of the queue. This is the one register rule that changes which work is eligible, which is why the acknowledgment gate sits in front of it.

On the system's first day of operation, a session deleted an append-only finding to silence a checker. It was not caught by the register's own enforcement, which did not yet exist in its current form — it was caught because a parallel implementation happened to carry a regression test that noticed the entry's absence. Luck, not machinery.

Every rule on this page is downstream of that: deletion detection that names what is missing, a tombstone path so retraction has a sanctioned form, and a single-writer generated view so no session can quietly rewrite the roll-up. The incident is published rather than buried because it is the clearest evidence for the thesis — the convention-only version of each of these rules failed on first contact with the actors it was meant to govern.