Resume Mission

• Treat .mission/<slug>/ files as the only reliable mission memory.
• Resolve shared references in this order: .mission-kit/references/, ~/.mission-kit/references/, then shared/references/.
• If the current session feels stale, contradictory, or over-compacted, stop trusting the conversation and reconstruct context from files.
• Never guess the current mission state from chat history when state.json or features.json can answer it directly.

Phase 0: Discover Candidate Missions

1. Look for .mission/ in the working directory.
2. If .mission/ does not exist or contains no mission directories, stop with a clear diagnostic and direct the user to $start-mission.
3. For each .mission/<slug>/, inspect at minimum:
   • state.json
   • mission.md
   • features.json
   • validation-state.json
   • AGENTS.md
4. Treat planning, in_progress, validating, paused, and blocked as resumable active states.

Phase 1: Select the Mission to Resume

Single mission

• If exactly one mission directory exists, use it after validation.

Multiple missions

When multiple mission directories exist:

1. Prefer missions whose state.json says they are active.
2. If exactly one active mission exists, resume it.
3. If multiple active missions exist, sort them by updatedAt descending and resume the most recent active mission.
4. Before continuing, report the other active missions so the user knows which one was selected.
5. If timestamps are missing, malformed, or tied in a way that makes the choice ambiguous, stop and ask the user to pick a slug instead of choosing arbitrarily.

This satisfies the multiple-mission rule: never pick a mission at random.

Phase 2: Validate Mission State and Handle Corruption

Read the selected mission's files defensively.

Required file checks

• state.json must exist and parse as valid JSON.
• features.json must exist and parse as either the canonical top-level { "features": [...] } object or a legacy top-level array from older Claude dry runs.
• validation-state.json must exist and contain assertion entries.
• mission.md and AGENTS.md must exist so scope and boundaries can be reconstructed.

If features.json is the legacy top-level array shape, treat it as a compatibility shim by reconstructing it as { "features": <array> }, and note that the next write should normalize it back to the canonical object wrapper.

Corrupted or missing state handling

If any required file is missing, truncated, or invalid:

1. Stop the resume flow.
2. Report the exact file path that is broken.
3. Explain what was expected (for example, state.json with mission lifecycle fields, or features.json with a features array).
4. Do not continue execution on partial or guessed state.
5. If state.json is corrupted but other files still exist, mention that the mission can be repaired manually from the remaining file-backed artifacts, but do not pretend the state is healthy.

The goal is a clear diagnostic error, never a crash and never silent recovery by guesswork.

Phase 3: Reconstruct Context from Durable Files

Once the mission passes validation, rebuild context from files in this order:

1. mission.md — mission goal, milestones, environment, validation strategy.
2. AGENTS.md — mission boundaries, off-limits areas, conventions, pre-existing issues.
3. features.json — ordered queue, current statuses, milestone grouping, fulfills mappings.
4. state.json — lifecycle state, current feature, timestamps, session bookkeeping.
5. validation-state.json — assertion pass/fail/blocked ledger.
6. .mission/<slug>/services.yaml — test, lint, typecheck, build, and service commands.
7. Relevant .mission/<slug>/library/ notes — architecture, environment, and user-testing guidance.

If file contents disagree with earlier conversation, trust the files.

Phase 4: Display a Progress Summary Before Acting

Before re-entering execution, print a concise progress summary containing:

• mission slug or title,
• current lifecycle state,
• current milestone and milestone position when derivable,
• completed features versus total features,
• current in-progress feature if one exists,
• assertion counts (passed / failed / blocked / pending),
• the most recent Git commit that touched the mission workspace when available, otherwise state.json.lastCommitId,
• last updatedAt timestamp,
• next planned action,
• continueHere.lastAction, continueHere.nextStep, and continueHere.ephemeralNotes when state.json.continueHere exists.

Example summary shape:

Mission: codex-skills-rollout
State: in_progress
Milestone: codex-skills (2 of 5)
Features: 4 / 7 completed
Current feature: codex-resume-and-config
Assertions: 9 passed, 0 failed, 2 pending
Last commit: 9e7544cdef02977c0fda8427bd5e76de7c047b2e
Last activity: 2026-03-07T22:15:00Z
Next action: resume feature execution
Continue here: finished validator triage -> update config and rerun checks

Phase 5: Choose the Correct Resume Point

Use state.json plus features.json to determine where to continue.

Case A — state: planning

• Resume planning work.
• Re-read the mission artifacts already written.
• Finish any missing planning outputs before switching the mission back to in_progress.

Case B — state: in_progress with currentFeatureId

• Re-open that feature first.
• Verify the feature still exists and is marked in_progress.
• If state.json.continueHere exists, display it in the progress summary and carry lastAction, nextStep, and ephemeralNotes into the resumed feature execution context before taking any new steps.
• Resume its TDD loop from the current evidence, tests, modified files, and any durable continueHere notes.

Case C — state: in_progress without currentFeatureId

• Select the first pending feature whose preconditions are satisfied.
• If the first pending feature is blocked by unmet preconditions, either reorder with a documented reason or escalate instead of skipping silently.

Case D — state: validating

• Resume milestone validation before starting any new feature.
• Re-read the milestone's completed features and their fulfills assertions.
• Continue scrutiny-style checks and user-surface validation inline.

Case E — state: paused

• Display the continueHere context describing which milestone completed and that human review was requested.
• Transition state.json back to in_progress.
• Append a mission_resumed event to progress_log.jsonl.
• Continue the inline execution loop from the next pending feature or milestone.

Case F — state: blocked or failed

• Report the blocker or failure summary first.
• Only continue automatically if the file-backed state now shows the blocker was resolved.
• Otherwise return control with the exact reason the mission cannot safely proceed.

Case G — state: completed

• Display the completed summary and do not restart execution.

Phase 6: Re-Enter the Inline Execution Loop

After reconstructing context and choosing the resume point, continue using the same loop as $start-mission:

1. Re-read mission state files before each iteration.
2. Execute the current feature or next ready feature inline with RED -> GREEN -> VERIFY.
3. Update features.json and state.json immediately at feature start and feature completion.
4. Detect milestone boundaries and run inline validation.
5. If validation fails, insert fix features at the top of the pending queue.
6. Respect the retry budget of 3 attempts per original feature or failure cluster.
7. End only when all features are complete and all assertions are passed.

State-File-Backed Restart Pattern

When context becomes stale, noisy, or unreliable, use this restart pattern:

1. Stop the current session instead of continuing from bad memory.
2. Start a fresh Codex session in the same repository.
3. Invoke $resume-mission.
4. Read all mission state files again:
   • .mission/<slug>/mission.md
   • .mission/<slug>/AGENTS.md
   • .mission/<slug>/features.json
   • .mission/<slug>/state.json
   • .mission/<slug>/validation-state.json
   • .mission/<slug>/services.yaml
   • relevant .mission/<slug>/library/ notes
5. Reconstruct progress from those files before taking any new action.

This is the durable restart model for long missions: fresh session + file reconstruction, never “keep going and hope the old context is still right.”

Safety Rules

• Never overwrite existing mission files during resume unless the execution loop explicitly updates state as part of normal progress.
• Never discard failed or blocked evidence from validation-state.json.
• Never resume a mission by choosing an arbitrary slug from multiple candidates.
• Never continue after a corrupted-state diagnostic unless the files are fixed.