Automatic builder context refresh at porch phase boundaries (the /arch-save loop, porch-triggered)

[waleedkadous]

Motivation

Builders are using more and more context. Long protocol runs (SPIR especially) accumulate tool output and history until the context ceiling degrades work quality or forces a manual afx reset. Architects already have a deliberate memory-management loop — /arch-save: save curated state → /clear → re-init — but it is human-triggered. Builders should get the same loop triggered automatically by porch at protocol phase boundaries.

Proposal

Porch emits a context-refresh step at configured protocol boundaries. For SPIR: after spec approval, after plan approval, and just before review — with per-plan-phase resets inside implement worth including too, since implement is where context actually burns (recent example: an 11-plan-phase project run in essentially one context).

Design decisions (prescribed)

1. Reuse the afx reset machinery; do not build a parallel save/clear path. afx reset already packages save-state request → verified receipt (nonce, min-bytes, quiet-window) → /clear → re-orient, failing safe without clearing when any gate trips. The new work is the porch-side trigger plus a builder-side self-refresh skill mirroring /arch-save (in-harness self-clear is proven by arch-save itself).
2. Builders are the easy case — lean on externalized state. A builder's durable state already lives in the spec, the plan, status.yaml, the thread narrative, and git. At a phase boundary the save step captures near-zero in-flight nuance; after /clear, porch's next task emission effectively is the re-init. Keep the builder save minimal — do not invent an architect-style free-text state file for builders.
3. At-most-once per boundary, recorded in status.yaml. Porch transitions can loop (see porch: SPIR verify-approval triggers phase-transition that resets all plan phases to pending (state loop) #1408, verify-approval resetting all plan phases). A transition side-effect that wipes context must be idempotent per boundary — "already refreshed at this boundary" is a recorded fact in the state machine, never inferred.
4. Never clear on an unverified save. Inherit the fail-safe gates wholesale. An automatic clear firing on a failed save destroys in-flight knowledge with no human watching — the auto path must be more conservative than the manual one, not less.
5. Reset after gate approval, never while parked at a gate. Post-approval the gate outcome is durable in status.yaml, so a refreshed builder cannot confuse "waiting" with "approved."
6. Always-fire at configured boundaries, not threshold-triggered. Deterministic and testable; an unnecessary refresh at a clean boundary costs almost nothing since re-orientation comes from artifacts. Context-percentage triggering would add a harness-introspection dependency porch doesn't have. (A threshold mode can be a follow-up if always-fire proves too chatty.)
7. Per-protocol configuration in the protocol definition (e.g. contextRefresh: [after-spec, after-plan, per-plan-phase, before-review] for SPIR; BUGFIX likely none). Framework change ⇒ lands in both codev/ and codev-skeleton/.

Side benefit worth designing for

The before-review refresh is a quality feature, not just a context one: a builder reviewing its own work in a fresh context reads the diff cold instead of through the memory of writing it. Evaluate it as such.

Scope

SPIR-shaped: porch capability + protocol-definition schema + builder-side refresh skill + tests, mirrored into the skeleton.