How staleness works

Every document in Sync carries a status. When code changes, Sync marks the documents that describe it stale — so your agent knows what it can still trust.

This is the idea at the heart of Sync. It's worth understanding, because it's what stops your agent from acting on documentation that quietly went out of date.

Every document has a status

When a document is written, Sync binds it to the parts of the code it describes. From then on, the document carries a status:

Fresh — it still matches the code. Safe to rely on.
Stale — the code it describes has changed since it was last confirmed. It might be wrong now.

You don't maintain this by hand. When you change code and commit, Sync looks at what moved and marks any document that describes those files stale — pointing at the exact commit and files that changed. Nothing is rewritten or deleted; the document simply stops claiming to be current.

Why the status matters

The status is what your agent reads.

When the agent pulls up a document, it sees whether that document is fresh or stale before it relies on the contents:

A fresh document, the agent can trust and build on.
A stale document is a signal: "this may no longer be true — check it against the actual code instead of taking my word for it."

That single signal is what prevents the classic failure of AI coding: an agent confidently pattern-matching against an old design doc and re-introducing a decision you reversed months ago. With Sync, it knows what's still true.

A stale document isn't an error — it's a to-do. It means "someone (you or the agent) should take a look and confirm or update this."

Clearing staleness

Resolving a stale document is quick:

If it's still correct, confirm it — Sync re-stamps it against the current code and it goes back to fresh.
If it's wrong, update it (usually the agent does this as it fixes the code) and it becomes fresh again.

Sync can also warn you before you push if documents are still stale, so out-of-date knowledge doesn't quietly ship. (You can always push anyway.)

Project health — a separate signal

Alongside each document's status, Sync shows how much of your knowledge is currently stale, as a simple ratio.

This is a different thing from the per-document status, and it's for you, not the agent. A handful of stale documents is normal — you're actively changing code. But when a large share of your documentation is stale, it's telling you something about the project: the knowledge base has drifted far from the code, and it's worth a pass to bring it back in line.

Think of the ratio as a health gauge, not a target. A high stale share means the project's documentation has fallen behind — time for a cleanup — not that any single document is more or less trustworthy than its own status says.

In short

Each document tells you and your agent whether it's still true.
That per-document status is what keeps the agent honest.
The overall stale ratio is a separate, project-level health signal — useful for you, not something the agent acts on.