Arch Save

/arch-save — save state, clear, and come back as yourself

Long sessions accumulate stale context. This is the deliberate cure: you choose the moment, you choose what survives, and a fresh session resumes from what you wrote.

$ARGUMENTS carries the architect name, a next task for the session that comes back, or both:

/arch-save                                  save, clear, re-init, then wait
/arch-save file and spawn that issue        … and start on that first, unprompted
/arch-save main file and spawn that issue   explicit name, then the next task

The next task is how an owner who already knows what the refreshed session should do first says so once, at the moment they direct the refresh, instead of watching for the re-init to land and typing it again.

When NOT to run this

On the owner's direction, or when the owner runs it themselves. Do not invoke this autonomously mid-task on your own judgement — the irreversible step is a human decision, relocated from "press /clear" to "invoke /arch-save", not removed. If the owner tells you to run it, run it; if you think it is time, suggest it and wait.

Only at a resumable boundary — a gate approval, a PR merge, a completed investigation, the end of a long tool-heavy stretch. Never mid-task. Nothing here can check that; the state file must describe a point a fresh session can resume from, not a half-finished action. A mid-task snapshot resumes into confusion.

The procedure

Do these in order. The order is the feature — step 3 must precede step 4, because the context that knows what to write is the one about to be destroyed.

1. Resolve your name, then split off the next task

Always run afx whoami first, whatever $ARGUMENTS holds — the split below cannot tell a name from a task until it knows your name. The name rules are unchanged:

• type: architect → the reported name is yours.
• type: builder → STOP. This terminal is a builder. Report the mismatch.
• Non-zero exit → you have no name yet. A single-token $ARGUMENTS that validates as a name is still accepted as one; anything else → STOP and ask which architect you are. Do not guess, and do not default to main — writing another architect's state file is the exact failure /arch-init exists to prevent (#1094).

Validate the name before building any path: [a-z][a-z0-9-]*, at most 64 characters. Reject slashes, .., uppercase, spaces. Never interpolate an unvalidated name into codev/state/<name>.md.

Then split $ARGUMENTS:

1. $ARGUMENTS is empty → name from afx whoami, and there is no next task.
2. The first whitespace-separated token equals the whoami name (or, when whoami could not resolve one, is a single token that validates as a name) → that token is the name, and the remainder is the next-task text, which may be empty.
3. Otherwise → the whole of $ARGUMENTS is the next-task text, and the name comes from afx whoami.

So /arch-save and /arch-save main behave exactly as they always have. The one ambiguity — a next task whose first word happens to be your own architect name — is accepted rather than worked around: lead with the explicit name (/arch-save main main is stalled, look at it) to disambiguate.

If you had to ask which architect you are, the next task still stands. The answer supplies the name; $ARGUMENTS already supplied the task. Do not make the owner retype it.

Guard, applied after the split: a leading token that names a different architect stops you. If the first token validates as a name, differs from the name whoami reported, and codev/state/<token>.md exists → STOP and ask which architect you are. Write nothing. whoami can be wrong (#1094), and rule 3 would otherwise bury a real name-override inside next-task text and save to whoami's file; a task that merely opens with a sibling's name is the only case this costs, and it costs one clarification.

This is not how /arch-init resolves a name, and the asymmetry is deliberate: /arch-init takes no next task, so any non-empty argument there is unambiguously a name and overrides whoami outright. Here the first token is weighed against whoami, which is why the guard above exists — never save into a name you did not verify.

2. Stop your own monitors

Enumerate every monitor, watcher or background task you armed, and stop it.

This is the half that only you can do. Monitors are session-bound, not context-bound: they survive /clear and keep firing into a context that cannot evaluate their alerts. pgrep cannot see them — they are harness background tasks, not shell processes — so the instance after the clear has no handle on them. You do. Use it.

3. Write the pruned state file

Rewrite codev/state/<name>.md. Pruning is part of the save, not polish afterwards — a save that only appends has not done its job.

• Rewrite the current-state / open-loops section in place. Do not accumulate stale "current state" blocks. Never leave two sections with the same heading — a duplicated "How to resume" means you appended where you should have overwritten.
• Delete resolved loops outright. A closed item's record is the log entry, not a lingering line in current state.
• Append one short dated entry for what changed this stretch.
• Collapse older entries into one-line summaries that point at durable artifacts — the merged PRs, closed issues and reviews where the detail actually lives.
• Aim for one screen. If the file has grown past easy reading, prune as part of this save rather than leaving it for next time.

Prune by pointer, never by deletion. These files are gitignored (.gitignore:15), so there is no history to recover from — pruned prose is gone for good. Replace detail with a pointer to something durable; never delete the only record of something. Copying the file first (cp codev/state/<name>.md codev/state/.<name>.bak.md) is cheap insurance.

Content guardrails. No secrets — tokens, keys, credentials. No transcript dumps, no raw tool output. Only: current focus, open loops, and what a fresh session needs to resume.

Write the next task into the banner, if step 1 produced one. Add a single line to the banner block, directly after the ⭐ THIS /clear IS INTENTIONAL line:

# ⏭ NEXT TASK (owner-directed at save, 2026-09-19T02:10Z): file and spawn that issue

• Verbatim. Collapse newlines to spaces; do not paraphrase, expand, or "helpfully" plan it. Those are the owner's words, and the context writing them down is the one about to be destroyed — this is the last moment at which a paraphrase can be caught.
• New text replaces any existing NEXT TASK line.
• No new text preserves an existing one. A NEXT TASK line still in the banner means the previous cycle never came back to pick it up; dropping it silently would lose an owner instruction that nothing else is holding. Mark it carried over when you preserve it: append [carried over — gloss orients only; re-confirm before acting] to the line (once; a line already marked stays as it is). A gloss carries the owner's word only for the cycle that wrote it.

Then resolve its referents — resolve, don't plan. After the clear, "them" points at nothing; this context is the only one that knows what the owner meant. So pin every referent in the owner's words to a concrete, durable identifier, and append it to the same line, after the verbatim text, as a [resolved at save: …] gloss:

# ⏭ NEXT TASK (owner-directed at save, 2026-09-22T13:40Z): merge them all  [resolved at save: PRs #1710, #1712, #1715]

• Every referent. Pronouns and deictics — "them", "that issue", "his PR", "the failing one" — become PR numbers, issue numbers, builder ids, branch names, file paths.
• Resolution only. The gloss names what, never how: no steps, no ordering, no caveats, no "after CI is green". A gloss that contains a plan has overstepped; the resumed session plans.
• No referents → no gloss. /arch-save review PR #1712 needs nothing; write the line as above without one. Never add an empty or redundant gloss.
• Cannot resolve → do not clear. If any referent is ambiguous or unknown to you, stop before step 4 and ask the owner which items are meant. Clearing with an unresolved task destroys the only context that could have answered. This is the one case where /arch-save may pause its own cycle — it is cheap, and the alternative is a wrong merge. Tell the owner your monitors are already stopped (step 2), and on their answer resume from here: write the gloss, then continue to step 4.

The gloss is more than orientation: /arch-init treats the items it names as approved for the act the owner's words name, so it is how the owner's word survives the clear.

Use the template at the end of this document.