[AIR #1220] arch-init: architect auto-state-saving lifecycle

[waleedkadous]

Summary

Makes /arch-init instruct a complete context-lifecycle loop, not just recovery. Today the skill reads codev/state/<name>.md at session start and never writes — so the recovery flow assumes a file nothing tells anyone to write (the durability gap named in #1212). This change adds an architect auto-save section: the architect curates its state file at a resumable checkpoint, then suggests the human /clear.

/arch-init (recover) → work → save at checkpoint → suggest /clear → human /clears → /arch-init → …

The state file stops being crash insurance and becomes deliberate memory management: a summary written at a moment the architect chooses, at a resumable boundary — better than auto-compaction because both timing and content are intentional. Self-reinforcing: every recovery re-reads the skill and re-primes the save habit, so the gap closes after each architect's first /arch-init.

Supersedes #1212 (closed wontfix — approach switched from "separate save command / standing instruction" to "auto-saving built into /arch-init itself").

Key decisions

• Save-then-suggest ordering is the core safety property. The agent cannot clear its own context and must never decide unilaterally to lose it. The skill instructs: save first, then tell the human it is a good time to /clear. The irreversible action stays behind a human keystroke, and accepting the suggestion can never lose anything because the save already happened.
• Write format = read format (symmetry with the Spec 1134 minimum contract). Recovery reads "role banner + most recent dated section", so a save rewrites the current-state/open-loops section in place and appends one short dated log entry — leaving exactly what recovery expects.
• Placed inside /arch-init, not a new /arch-save skill — per the issue's self-reinforcement rationale.
• Skill-text only, both trees. No runtime code. codev-skeleton/.claude/skills/arch-init/SKILL.md and .claude/skills/arch-init/SKILL.md are byte-identical (drift guard test enforces it).

What the skill now instructs (all five issue requirements)

1. When to save — resumable boundaries (gate approval, PR merge, completed investigation, end of a long tool-heavy stretch); never mid-task.
2. How to save — rewrite current-state section in place + append one dated entry.
3. Compaction discipline — keep it to one screen; prune stale dated sections when appending (summary, not transcript).
4. Advisory, never nagging — the /clear suggestion appears only right after a save, phrased softly, and is not repeated.
5. Content guardrails — no secrets, no transcript dumps; only current focus + open loops + resume instructions.

Existing recovery behavior (identity resolution via afx whoami, name validation / path-traversal guard, missing-file flow with _thread.md exclusion, four architect guardrails) is unchanged.

Test plan

packages/codev/src/agent-farm/__tests__/spec-1134-arch-init-skill.test.ts — all existing assertions preserved (two-tree byte-equality, required/forbidden content), plus new #1220 required-content assertions:

• save target codev/state/<name>.md at checkpoints
• save-then-suggest /clear ordering
• never save mid-task
• write=read symmetry (rewrite current-state + append dated)
• compaction (one screen / prune stale)
• content guardrails (no secrets / no transcript dumps)
• advisory-not-nagging framing

Verification:

• vitest run spec-1134-arch-init-skill.test.ts → 19 passed
• tsc --noEmit → clean
• porch check 1220 → build ✓, tests ✓

Acceptance criteria

• Both SKILL.md copies byte-identical, tests green.
• Skill text instructs: save at resumable checkpoints → then suggest /clear; save = rewrite current-state + append dated; prune stale; never mid-task; no secrets.
• Existing recovery behavior (identity resolution, missing-file flow, four guardrails) unchanged.

Closes #1220.

🤖 Generated with Claude Code