Staleness ages from creation, never from the last edit

Context¶

adr-bd7c4f3c5764 made staleness data: a per-type review_days cadence, an optional verified date, and today - (verified or updated) > review_days. The updated half of that fallback is the defect in issue-6726eabcf871: updated moves on every edit, so a document nobody had vouched for left the review queue as soon as anybody wrote in it.

The fallback has to answer "what is the earliest date docir can honestly claim somebody looked at this?" for a document with no verified. updated answers a different question — "when was this file last touched?" — and the two come apart hardest in the document that matters most: the evidence that an ask is still unanswered is a re-check written into its body. Recording the silence is what ended the report of it.

Decision¶

Staleness ages from a date an edit cannot move. Document.stale_reference_date() returns verified when present and created otherwise; it never reads updated.

created is the one date the write path sets once and never rewrites — not a retype, not a tag rename, not check --fix, not a body edit. A document with no verified therefore enters the queue exactly one cadence after it was written and stays there until somebody stamps docir update <id> --verified.

The stale finding now names the clock it read: never verified, created or verified , plus the command that clears it. Without that, a reader who edited a document yesterday sees it reported as overdue and reads the finding as a bug.

Alternatives considered¶

Age from verified alone, treating absent as infinitely stale. Semantically the cleanest reading of the queue — a document nobody has vouched for is stale by definition — and it was measured before being rejected. On this store on 2026-09-05 (196 live documents, 84 carrying a cadence, 1 carrying verified) it reports 83 of 84 documents stale, including ones written the day before, because the corpus is younger than its shortest cadence. It also makes review_days inert for every unverified document: the cadence never applies, so the queue is "everything", cannot be worked down, and is indistinguishable from a corpus that has genuinely rotted. That is issue-40d1792bc9f9 again — a warning that fires on the product's own defaults — and the same argument the docir schema validate dead-end warning was dropped on.

A second stamp for "I re-checked and it is still unanswered", distinct from verified. This records the real event, which created only approximates, and it is what the reporter's own workaround does with a date declared in the body. Rejected here as the wrong size of change for a defect fix: a frontmatter field, a migration, a CLI verb, an MCP argument and a contract clause, for one workflow. It stays additive — nothing in this decision forecloses it, and a document that carries it would simply age from the later of it and created.

Consequences¶

• The queue is monotonic in the absence of --verified: writing into a document can no longer remove it, which is what makes a re-check safe to record.
• A never-verified document reports stale one cadence after creation rather than after its last edit. On a corpus whose documents are edited more often than their cadence, this reports more documents than before — correctly; those are the documents nobody has confirmed.
• The clock start is created, which is not necessarily when the thing the document tracks began. For a document standing in for an external ask, created precedes the ask, so silence is under-reported by that gap, once, at the document's birth. Bounded by the gap and paid only once, against a defect that cleared the entry on every edit.
• issue-9ed4905e0db8's rule — a mechanical rewrite must not advance updated — no longer has staleness behind it, since updated no longer feeds the clock. It stands on its own ground: updated is the edit clock every read view shows, and a bulk rewrite claiming every document was edited today is a lie about that.
• Two builds reading one store disagree about stale, silently. Measured by the cross-version procedure adr-ab4598c6f707 requires: one document, created: 2024-01-01, updated today, never verified, 365-day cadence — 0.23.0 reports stale: false and this build reports stale: true, from the same file. Neither refuses, so it is not a break by that decision's own test; it is the third thing that decision does not name, a field both builds show with different values. stale is computed and carries no provenance, so nothing reports the disagreement, and doctor's stale-index-build does not cover it — a teammate who runs reindex themselves clears that finding while still reading the old rule. It resolves when everyone upgrades, and until then the review queue is per-build. This did not appear on docir's own corpus, whose oldest document is younger than the shortest cadence in its schema.