msd-core/docs/how-to/read-the-statusline-freshness-marker.md

Read the statusline STATE.md freshness marker

The statusline can tell you, at a glance, that STATE.md is describing a codebase that has moved on without it:

Claude │ v2.0 Auth Rework · executing · state ~34 commits back │ my-project

state ~34 commits back means STATE.md was last written against a commit that is now 34 commits behind HEAD. You come back to a project after two weeks, the state file still says "Phase 4, executing", and this is the thing that tells you that sentence is stale before you act on it.

The marker is advisory and approximate. It never blocks anything.

Turn it on

msd-tools config-set statusline.show_state_freshness true

It is off by default. That is the only step — the state_head stamp it reads is written automatically every time MSD syncs STATE.md, so an active project already has one.

To turn it off again:

msd-tools config-set statusline.show_state_freshness false

The marker also appears in the compact statusline format (statusline.state_format: "compact"), rendered identically.

When it appears

Only when all of these hold:

1. statusline.show_state_freshness is true.
2. .planning/STATE.md carries a state_head: stamp.
3. The project root owns its own .git.
4. The stamp is an ancestor of the current HEAD.
5. HEAD is at least 20 commits past the stamp.

Twenty is the same advisory threshold /msd-health uses for its W024 warning, and it is deliberately not 1. With commit_docs: true (the default) the commit that carries a STATE.md sync advances HEAD by one, so a threshold of > 0 would show state ~1 commits back permanently on a project that is, by construction, perfectly fresh.

I turned it on and see nothing

That is usually correct behavior rather than a fault, but "nothing to report" and "could not look" render identically — both are simply absent. Work down this table to tell them apart.

Reason	How to confirm	Is it a problem?
Fewer than 20 commits behind	git rev-list --count $(grep '^state_head:' .planning/STATE.md | cut -d' ' -f2)..HEAD	No — this is the healthy case
No state_head stamp	grep '^state_head:' .planning/STATE.md returns nothing	No — the stamp appears on the next state write
Project root does not own its .git	ls -d .git at the directory holding .planning/	No — deliberate. See below
planning.sub_repos is set	msd-tools config-get planning.sub_repos	No — deliberate. See below
History was rewound past the stamp	git merge-base --is-ancestor <stamp> HEAD; echo $? prints 1	No — reported as unknown on purpose
The stamp is not a commit in this repo	git cat-file -e <stamp> fails	Possibly — a hand-edited STATE.md
git unavailable, or the repo is enormous	git --version; the read is abandoned after 1.5s	Rarely — the marker yields rather than stall your prompt
A todo task is showing instead	The middle segment shows a task, not MSD state	No — the whole MSD-state segment is replaced

Run /msd-health for the same signal in a form that always explains itself — it reports W024 with the count, and it is not subject to the statusline's silence.

Why it stays quiet instead of guessing

Two cases deserve spelling out, because in both the marker could print a number and that number would be a confident lie:

• A MSD project nested inside an unrelated checkout. git resolves HEAD from the nearest enclosing .git, which might belong to a dotfiles or notes repo that has nothing to do with your project. Rather than report that repo's history as your project's freshness, MSD checks that the directory holding .planning/ owns its own .git and otherwise says nothing.
• A planning.sub_repos workspace. The outer directory legitimately owns both .planning/ and its own repo, while every code commit lands in a nested child. The outer HEAD never advances, so the marker would read "fresh" forever while the code moved arbitrarily far. Per-child freshness would require choosing one HEAD out of several unrelated histories, so MSD declines to answer instead.

The rule in both: a freshness claim the project cannot substantiate degrades to unknown, never to fresh.

What the number does and does not mean

~34 counts every commit between the stamp and HEAD, including commits that touched nothing STATE.md describes. And because state_head is restamped on every state write, a low count means "something wrote STATE.md recently" — not "STATE.md is accurate."

So read it as a prompt to look, not as a measurement of drift:

• A high count is a reliable signal that the state file is worth re-reading.
• A low count is not evidence that the state file is correct.

Do not build automation on it. It is a proxy, deliberately rendered with a ~.

Cost

One git rev-list call per statusline render, and only when the marker is enabled and a state_head stamp is present. With the feature off — the default — it adds no subprocess and no measurable work. The call is abandoned after 1.5 seconds, so a slow or huge repository costs you a missing marker rather than a stalled prompt.

Related

• Configuration reference — statusline.show_state_freshness and the other statusline.* keys
• /msd-health — the W024 warning that thresholds on the same constant