feat: compaction-proof Nelson at every phase boundary#118
Merged
Conversation
Today the only natural compaction window is between Step 4 and Step 5.
Step 3's drafted plan lives only in admiral chat context, and cmd_recover
emits the same generic briefing regardless of phase, so a resumed admiral
can't pick up where the last one left off without rebuilding state.
Three coordinated changes:
- Persist battle-plan.md at the end of Step 3 — SKILL.md §3 now directs
the admiral to write the drafted plan to {mission-dir}/battle-plan.md
before Step 4. The .md becomes the prose authority; battle-plan.json
remains the structured authority.
- Phase-aware cmd_recover — new PHASE_RECOVERY_GUIDANCE table drives
recommended_actions per phase. UNDERWAY (and unknown) keep the
existing handoff-packet logic. BATTLE_PLAN/FORMATION/PERMISSION
prepend a warning when battle-plan.md is missing on disk. Phase
is now surfaced in both JSON briefing (current_phase) and text
output (Phase: …).
- Document safe compaction windows in SKILL.md Admiralty Doctrine and
references/damage-control/session-resumption.md. The unsafe window
is the single tightly coupled turn inside Step 5.
Tests: 8 new Recover tests covering phase guidance, missing
battle-plan.md warning, and phase visibility; updated existing
text-output and full-handoff-lifecycle tests. 286 tests pass.
Closes #113.
- Rename _BATTLE_PLAN_MD_REQUIRED_PHASES to BATTLE_PLAN_MD_REQUIRED_PHASES so tests can import the set directly instead of re-listing phases. - Add comment explaining phase guidance precedence over handoff packets in anomalous mid-flight states. - Parameterise test_recover_warns_when_battle_plan_md_missing over the required-phases set so FORMATION and PERMISSION are also locked in as regression tests (was BATTLE_PLAN only).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/compactis now safe at every phase boundary except inside Step 5. Admiral state persists to disk after each step instead of living only in chat context.cmd_recoveris phase-aware: the briefing carriescurrent_phase, surfacesPhase: …in text output, and emits per-phaserecommended_actions(with a missing-battle-plan.mdwarning in BATTLE_PLAN / FORMATION / PERMISSION).{mission-dir}/battle-plan.mdbefore Step 4 — the prose authority alongsidebattle-plan.jsonas the structured authority.Why
Issue #113 — the only natural compaction window today is between Steps 4 and 5. Step 3's plan exists only in admiral chat context, so compacting there loses the prose draft.
cmd_recoverreturned the same generic briefing regardless of phase, so a resumed admiral couldn't pick up where the last one left off without rebuilding state.Changes
skills/nelson/scripts/nelson_data_lifecycle.py— addPHASE_RECOVERY_GUIDANCE(one entry per non-UNDERWAY phase), make_build_recovery_briefingphase-aware, printPhase:in_format_recovery_text. UNDERWAY (and unknown) keep the existing handoff-packet-derived actions.skills/nelson/scripts/test_nelson_data.py— parameterisedtest_recover_phase_specific_actionsover all six phases,test_recover_warns_when_battle_plan_md_missing,test_recover_includes_phase_in_briefing, plus updated assertions ontest_recover_text_outputandtest_full_handoff_lifecycle.skills/nelson/SKILL.md— new "Persist the drafted plan" directive in §3 marking the safe compaction point; softened the template pointer line; added Admiralty Doctrine bullet on safe/compactwindows.skills/nelson/references/damage-control/session-resumption.md— appended "Safe compaction windows" subsection.skills/nelson/references/admiralty-templates/battle-plan.md— preamble declaring.mdas prose authority and.jsonas execution-data authority.Out of scope (follow-ups noted in plan risks)
battle-plan.md(needscmd_headlessinteraction first).battle_plan_draftedevent type — file existence is sufficient signal for this pass.Test plan
python3 -m pytest skills/nelson/scripts/ -k Recover -v— 15 passed (7 existing + 8 new/updated).python3 -m pytest skills/nelson/scripts/— 286 passed.init→recover(SAILING_ORDERS guidance),phase advance→recover(ESTIMATE guidance), advance to BATTLE_PLAN →recovershows missing-battle-plan.mdwarning; warning disappears after writing the file.bash scripts/check-references.sh— all cross-references valid.