ADR-0008: The tree marks, the work list filters

Status: accepted · 2026-09-11

Context

A workspace accumulates finished work. Every completed plan, accepted ADR and approved brief stays where it was, and after a few months the page tree is mostly things nobody needs to open. The tree drew no status at all — a plan finished in June rendered identically to the one being worked on — and the type view listed every finished page open, sorted by the last time someone happened to touch it.

The obvious fixes each break something. Hiding finished pages from the tree makes the tree lie about what the workspace contains. Re-sorting the tree so finished pages sink to the bottom fights the manual order people set by dragging, and does it again every time something finishes. Archiving finished plans confuses “this is done” with “this should not exist”, and teaches people to delete records. Auto-collapsing branches whose children are all finished hides without being asked.

Underneath all of this, the code could not say which statuses meant “finished”. The MCP set_status tool had an ad-hoc check — plan complete, ADR accepted — and nothing else used it. Completion time was stamped by that tool and not by the web use case, so any sort by completion would have been wrong for half the pages.

Decision

The tree marks. The work list filters. They answer different questions and treat finished work differently.

The tree answers where is it? It never hides a page and never reorders one by status. A finished page stays exactly where it was placed, drawn in muted ink with a check; an in-flight page gets a dot. One explicit, per-person toggle folds finished pages away, and the count of what is folded is always shown, so nothing vanishes silently. The toggle is a preference, not a URL parameter: a link should show the reader the whole map.

The type view answers what is still open? It is already grouped by lifecycle for that reason. Finished groups fold to one line by default, open on a click, and sort by when the page finished. Status filters are chips backed by the URL — ?status=in-progress,draft — using the same words list_pages takes over MCP, so a filtered view is a link you can send and the API’s twin.

Three things support this:

• isSettledStatus(docType, status) in the domain names the statuses where nobody needs to act, per type. It is deliberately not “the last state in the lifecycle”: an active runbook and a current audit are live reference documents, not open work and not finished either. The line is “needs a person” against “is a record”. One function, used by the tree, the type view, the home page, search and both status paths, replacing the ad-hoc check in the MCP tool.
• settledAt is stamped whenever a status change enters a settled state and cleared when it leaves one, from the web use case and the MCP tool alike. lastVerifiedAt keeps its narrower meaning — a plan completed or an ADR accepted was confirmed; an abandoned plan was not.
• Search offers the same distinction as a scope — everything, open, finished — expanded server-side from the same function.

Alternatives rejected

Hide finished pages from the tree by default. The tree would no longer be a map. A reader who knows a page is “in there somewhere” is right to expect to see it.

Sink finished siblings below active ones. Manual position is a decision a person made by dragging. The tree does not overrule it.

Archive finished plans. The trash is for pages that should not exist. A finished plan should. Conflating them teaches the wrong habit.

A separate “Done” view. The type view with finished groups folded is that view, one click away, without a second navigation entry to explain.

Auto-collapse branches whose children are all finished. It hides, and it does so without being asked. The explicit toggle is the honest version.

Consequences

• The tree payload now carries settledAt; nothing else about the tree’s data changes, because status was already on every node and merely not drawn.
• A page finished before this change has no settledAt; the type view falls back to updatedAt for it, which is the order it always had.
• /home gains a block of in-progress plans across the person’s workspaces with open-task counts. Finished plans cannot appear there by construction.
• The next request for auto-collapse, or for hiding by default, is answered here rather than relitigated.