Verified close

The export is written and the session is ending. You type /done. A close is where that work either becomes a recorded result or stops being claimed as one. It happens in a fixed order: walk the six checks the plan named, hand a short composed record to the one tool allowed to write the project's live files, and let that tool run its own checks before anything is written.

The order is the point. Verification comes before recording, and recording is refused while a check is red.

The ordinary alternative

The session ends with a summary of what it did. This is the most common way agent-assisted work goes wrong, and it is not a bad edit — it is a confident report. A summary describes intentions, and intentions read exactly like results.

A careful person avoids this by hand: walk a checklist written before the work started, then save an honest handoff. That works. /done makes it the standard path and adds one rule a person can talk themselves out of: a check that is red cannot be written up as completion.

Walking the roster

The plan card named the six checks before any code existed: authorization, current filters, approved columns, escaping, an empty result and unchanged list behavior. Each is answered individually, and there are three answers, not two.

Writing "done" over a red check is the specific outcome this whole stage exists to prevent. If the authorization check is red, the close records the blocker and the repair as the next action. The approved fields stay recorded; the rejected background job and the queued historical IDs do not become in-scope work merely because the session is ending.

What gets written, and by what

The close composes one short record: the date, which session it was, what was done, what comes next, and the card that holds the reasoning. Every field has a length cap. What lands in docs/PROGRESS.md is a single line.

The close above does not write that line, because its authorization check is red. It writes the checkpoint instead:

- 2026-08-11 · orders s1 · BLOCKED: a non-manager can reach the export ·
  → add the authorized CSV route -- approved columns only ·
  docs/orders/decisions/export-fields.md

The completed record only exists after the repair, when the same session closes a second time and the roster comes back green:

- 2026-08-11 · orders s1 · filtered CSV export behind the manager check,
  approved columns only · → /coldstart orders s2 — historical order IDs ·
  docs/orders/decisions/export-fields.md

Each is one physical line in the file, wrapped here to fit the page. Neither is a narrative of the session, and neither is meant to be read instead of the work — the last field is an address to the card where the export-field decision actually lives.

Both records go to a single writer. The tool /done runs owns every write to the project's live files, and before writing anything that means completion it refreshes the project's generated views and runs the whole check roster itself, refusing on a tree it finds unclean. A refusal names the defect. The correct response is to fix what it named and re-run — never to hand-edit a machine-written file until it passes.

That is why a refused close still leaves something behind. The checkpoint above is minimal on purpose: the blockers naming what is red, the next action naming the repair, and the section marked blocked, and nothing else. The checkpoint deliberately records no completion. That is what makes the retry safe — when you fix the authorization check and close again, the second close is the only write that records the work as done, so it lands once rather than twice. Without the checkpoint a refusal would leave the project holding a red check and no record of why.

When the gate is clean, the write happens in one sweep: the session record is prepended and older entries move to a monthly history file, the finished session's block is lifted out of the live plan card into a dated history file of its own, the resume pointer is rewritten whole, and the session's local trace is cleared. The absence of that trace is how the next start knows the last session ended cleanly. Moving the block out is what keeps the plan card a description of the work still to come rather than an archive of everything the section has already done.

Closing the last session of a section does a little more: it adds a one-line status entry to the master plan and hands the pointer on to the next section, so the ordered plan stays a current account of which areas are finished rather than a list written once at the start.

It then stages the files this session set out to change, by name, and suggests a one-line commit message. Never a blanket stage of whatever the tree happens to be holding: a blanket stage is how an unrelated file joins a commit, and how a secret leaves a machine.

Finally it prints the open items recorded against places this session actually touched — and does nothing about them. Printing them is deliberate: draining them is a decision for you, on a visit you were already making.

The three answers a close can give

A close ends in one of three states, kept distinct rather than blended into a percentage.

When to use it, and when not

Close a session when its outcome is either established or established as blocked. Both are results, and a blocked close is more useful to the next session than an optimistic one, because it hands over an accurate reason rather than a plan that will not work.

Do not close to tidy up mid-session. The close rewrites the pointer and clears the trace; running it because the terminal is getting long produces a handoff describing an unfinished state as a finished one.

Do not close to make a red check go away. The supported repair is to fix the tree, never the record of it.

Limits

The gate checks the tree, not the work. It can confirm that the project's own checks are green and that its files are in the shape the product expects. It cannot confirm that the feature is correct, that the checks were the right ones, or that a passing check tests what its name suggests.

The walk depends on the plan. A check list written vaguely produces a vague close, which is why the planning pass refuses to scaffold "test it works".

The record is short by design, and short records lose detail. What crosses to the next session is a line and a pointer, not the reasoning behind them. Anything that must survive belongs in the project's durable record, written deliberately, which is a later section's subject.

Next

What the close leaves behind for the next session is one small file: the resume pointer.