Freshness Tiers
- title
- Freshness Tiers
- type
- overview
- summary
- How long each kind of page may go without review, declared once so warren lint can enforce it
- tags
- meta
- created
- 2026-09-01
- updated
- 2026-09-01
Pages in this vault age at different rates. A summary of an article describes a fixed source and does not go stale on its own β the article said what it said. A toolbox page describes a moving target: the repository gets releases, changes license, or dies. A concept page about LLM agents describes something that is rewritten every few months. Treating all of them alike means either re-reading summaries that cannot have changed or never noticing that a tool page is two years behind its repository.
The freshness: list in the frontmatter above is the machine-readable half. warren lint --src . reads it from whichever page carries it, computes a tier for every page in wiki/, toolbox/, books/ and talks/, and reports each page whose updated: is older than its tier allows. This page is the only place the tiers are written, so the table below and the check cannot disagree. planned-pages does the same job for deliberate gaps.
How a page gets its tier
The base comes from the page's type:, then from its section directory, then from default. A tag can shorten a finite base but never lengthen it, and never revives never. So a concept page tagged ai-agents ages in nine months rather than two years, while a summary page with the same tag does not age at all: the summary is about the article, and the article is not going to change.
| Tier | Applies to | Why |
|---|---|---|
never |
summary, book, talk (via default) |
They describe a fixed source. What can go stale is a claim the vault repeats elsewhere, which is the judgment half of the lint, not this check. |
2y |
concept |
Ideas hold; the examples and the tools named around them do not. |
18m |
entity |
Companies, products and people change state β acquired, renamed, discontinued. |
1y |
toolbox, comparison, analysis, overview |
A tool page is a snapshot of a repository; a comparison is a snapshot of several. |
9m |
tags ai-agents, agentic-coding, coding-agent, llm, local-models, mcp |
The fastest-moving area in the vault. A concept page written about agent frameworks in one spring is describing a different field by the next. |
6m |
tag claude-code |
A product with weekly releases; page-level claims about its features and hooks go wrong fastest of all. |
Ages are written as <n>d, <n>w, <n>m (months, 30 days) or <n>y (365 days), or the word never. warren lint rejects anything else with a front-freshness error on this page, because a typo here would silently exempt a whole tier.
The watchlist keeps its own cadence β a next-check date per row, 90 days by default β and is not duplicated here. A watchlist tool is on the toolbox tier like any other; the row is the finer schedule.
What to do with a stale finding
A stale finding is a review request, not a defect. Re-read the page, check it against what has happened since β a release, a newer source in the vault, the repository's current README β and then do one of two things. Revise the page if something changed, or confirm it if nothing did. Both end with bumping updated:, because a review that changed nothing is still the date the page was last known to be right, and that is what the check measures. Bumping updated: without looking is the one move that defeats the purpose.
If the check is being run ahead of a review β "what will be stale by December?" β warren lint --as-of 2026-12-01 measures against that date instead of today.