golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

feat: structured session handoff artifact for cross-session continuity (#940) (#1122)

Browse Source 
Enhance /gsd:pause-work to write .planning/HANDOFF.json alongside
.continue-here.md. The JSON provides machine-readable state that
/gsd:resume-work can parse for precise resumption.

HANDOFF.json includes:
- Task position (phase, plan, task number, status)
- Completed and remaining tasks with commit hashes
- Blockers with type classification (technical/human_action/external)
- Human actions pending (API keys, approvals, manual testing)
- Uncommitted files list
- Context notes for mental model restoration

Resume-work changes:
- HANDOFF.json is primary resumption source (highest priority)
- Surfaces blockers and human actions immediately on session start
- Validates uncommitted files against git status
- Deletes HANDOFF.json after successful resumption
- Falls back to .continue-here.md if no JSON exists

Also checks for placeholder content in SUMMARY.md files to catch
false completions (frontmatter claims complete but body has TBD).

Fixes #940
This commit is contained in:
Tom Boucher
2026-03-18 12:01:25 -04:00
committed by GitHub
parent a97e4c2c6f
commit f54f3df776
5 changed files with 87 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/FEATURES.md
View File

@@ -513,11 +513,13 @@
**Purpose:** Maintain project continuity across context resets and sessions.
**Requirements:**
- REQ-SESSION-01: Pause MUST save current position and next steps to `continue-here.md`
- REQ-SESSION-02: Resume MUST restore full project context from state files
- REQ-SESSION-01: Pause MUST save current position and next steps to `continue-here.md` and structured `HANDOFF.json`
- REQ-SESSION-02: Resume MUST restore full project context from HANDOFF.json (preferred) or state files (fallback)
- REQ-SESSION-03: Progress MUST show current position, next action, and overall completion
- REQ-SESSION-04: Progress MUST read all state files (STATE.md, ROADMAP.md, phase directories)
- REQ-SESSION-05: All session operations MUST work after `/clear` (context reset)
- REQ-SESSION-06: HANDOFF.json MUST include blockers, human actions pending, and in-progress task state
- REQ-SESSION-07: Resume MUST surface human actions and blockers immediately on session start
---

2
docs/USER-GUIDE.md
View File

@@ -296,7 +296,7 @@ Controlled by `workflow.ui_safety_gate` config toggle.
|---------|---------|-------------|
| `/gsd:progress` | Show status and next steps | Anytime -- "where am I?" |
| `/gsd:resume-work` | Restore full context from last session | Starting a new session |
| `/gsd:pause-work` | Save context handoff | Stopping mid-phase |
| `/gsd:pause-work` | Save structured handoff (HANDOFF.json + continue-here.md) | Stopping mid-phase |
| `/gsd:help` | Show all commands | Quick reference |
| `/gsd:update` | Update GSD with changelog preview | Check for new versions |
| `/gsd:join-discord` | Open Discord community invite | Questions or community |