Operating state

Your repository records what the code became. It does not record what you were trying to do, what you ruled out, what blocked you, or where you meant to pick up. That second category is operating state: the governed state about active work that makes continuing it possible. It is the only thing mcue holds.

The boundary

Git records source history. mcue preserves the governed operating state needed to continue the work.

A repository is an attachment to a project, not its definition. A project can have one repository, several, or none at all — a project created in Hub with no source attached is a complete project, with lanes, plans, checkpoints, and resume views. When a repository joins later, mcue attach connects it to the same project.

mcue never writes to your repository and never copies it anywhere. The only file it places outside $MCUE_HOME is a small .mcue footprint dropped by mcue attach, which exists so commands can tell which project a directory belongs to. Publishing to Hub sends operating state and nothing else — your source never leaves your machine through mcue.

Why this is a boundary and not a feature

It would be easy to make mcue a little bit smarter by letting it read your diffs, watch your editor, or infer intent from commit messages. Each of those would quietly convert mcue from a tool you can reason about into a tool you have to trust.

What mcue does observe is bounded and warning-only: the current branch, HEAD, and whether the tree is dirty, so mcue drift can tell you the environment has moved since the last checkpoint. It does not read diffs, and it never infers a new objective, resolves a blocker, or changes a decision because the repository changed. Environment evidence can warn; only an explicit closeout can change operating state.

The boundary is what makes the rest of the guarantees possible:

• It can work offline, because it never needed your network in the first place.
• It can be inspected, because the state is small enough to read by hand.
• It can be repaired, because Markdown with YAML front matter survives its own tooling.
• It can be handed to an agent, because a bounded packet of intent is useful in a way that a repository dump is not.

What the state is made of

Everything mcue stores reduces to a few kinds of thing:

• Projects — a governed intent with a stable id: the durable identity and ownership boundary for a body of work. Repositories attach to it; it is not defined by one.
• Lanes — independently resumable streams of work inside a project, each with its own state, plan, blockers, and next action. Not branches; see Projects, lanes, and plans.
• Checkpoints — timestamped records written by mcue closeout. Append-only.
• Decisions — a running log of what was chosen and why.
• Plans — the current intended sequence of steps on a lane.
• Perspectives — origin-tagged accounts of a lane (this machine, that agent, the Hub web surface). More than one can be live at once; see Authority and conflicts.
• Resume packets — derived, bounded briefs assembled on demand. Never stored as truth.

The first six are durable. The last is computed, which matters: a resume packet is a view over governed state, so improving how packets are built never requires rewriting history.

Human-readable on purpose

State is Markdown with YAML front matter, on disk, under $MCUE_HOME:

cat ~/.mcue/projects/payments-api/project_state.md

You can diff it, grep it, put it in a private repository, and fix it in a text editor when something is wrong. That is a deliberate durability property rather than a convenience: if mcue stopped existing tomorrow, nothing you recorded would become unreadable.

The complete layout is in Files on disk.

Where Hub fits

Hub does not change the model. It holds accepted operating state so that the persistent MCP endpoint can answer while your machines are off, and so a second machine can clone a project and carry on.

mcue stays authoritative for anything you have not published. Hub becomes authoritative for the ordering of operations on projects you have published — which is what Authority and conflicts is about.