v7.7.0 to v7.7.0

---

name: deepworkplan-resume

description: Resume interrupted Lite or Full Deep Work Plans from durable Markdown and state, including safe recovery of promotions without duplicating completed work or gates.

version: "7.7.0"

documentation_url: https://deepworkplan.com

user-invocable: true

allowed-tools: Bash, Read, Grep, Glob, Edit, Write

---

# DeepWorkPlan — Resume

Safely continue an interrupted plan from where it stopped — no duplicated work,

strict order, continuing from the first `[ ]` task — from **durable workspace

artifacts alone** (the plan folder on disk, gitignored `.dwp/` included): a

different session, agent, model or harness must be able to pick the plan up

without the previous conversation. A fresh clone without `.dwp/` has nothing

to resume — see *Persistence* below.

## Shared resources (read at their moment, not upfront)

The compulsory set for this flow is the router SKILL plus this file: every

rule the resumption assessment runs on is stated inline in Step 2 below. A

default resumption reads **no** guide, spec, shared companion, or execution

contract before assessment; each loads when its moment arrives. (This

ordering is deliberate: reading companions "to be safe" is the failure mode

this tiering removed.)

- **Essential now (before the first task):**

[`../shared/context.sh`](../shared/context.sh) — **run** it

(`bash ../shared/context.sh`) to resolve repo root, branch, agent tool and

`dwp_dir`; its source is not part of this flow's reads. That is the whole

t0 set — the resume protocol (Step 2) and the handoff rules are inline

below.

- **Conditional — read only when the trigger fires:**

- [`v6.md`](v6.md) (this directory) — read only when Step 2.0 detects a

v6 plan: the v6 recovery ladder, cross-agent handoff and migration

boundary. A v5 plan never reads it.

- [`../spec/V6_LIFECYCLE.md`](../spec/V6_LIFECYCLE.md) — read only

when a migration or cross-agent question goes beyond `v6.md` (§8–§9).

- [`../execute/SKILL.md`](../execute/SKILL.md) — read only when Step 5

resumes into the execution loop: the contract every resumed task runs

under (gate selection, repair/stop, task-local closure, the Final

Review). Assessment — Steps 1–4 — never needs it; once loaded, its own

conditional tier governs its execution-time companions.

- [`../spec/PLAN_STATE.md`](../spec/PLAN_STATE.md) §5–§6 — read only when

the plan carries `state.json` and a desync, a takeover, or a standard

question needs the normative rule; the everyday needs (markdown wins,

regenerate from the README, the checkpoint shape) are inline in Step 2.

- [`../guide/swarm.md`](../guide/swarm.md) §17 — read only when the plan

holds a pending handoff packet (Step 2.0a) or a lead succession is in play.

- [`../guide/prompts.md`](../guide/prompts.md) §9 — read only when the

interruption is unusual enough that the Step 2.5 boundary table does not

classify it (resume rules and scenarios).

- [`../shared/dwp-paths.md`](../shared/dwp-paths.md) — read only when a

plan folder cannot be located or the `DWP_DIR` override is in play

(Steps 0–1 already inline `.dwp/plans/<plan>/`).

- [`../shared/troubleshooting.md`](../shared/troubleshooting.md) — read

only when something is already wrong (discovery failure, stale

installation, missing test command, unsupported host capability,

inconsistent plan state).

- [`../guide/GUIDE.md`](../guide/GUIDE.md) — the routing index; consult

only when a need is not covered by a section named above.

- **Never by default:** no other guide, spec, preset or addon file is read

for this flow — not defensively, not "to be safe". `../shared/adaptation.md`

and `../guide/execution.md` are not resume reads: their moments belong to

execute/SKILL.md's tier once Step 5 loads it. Name the moment, then read.

## Parameter Support

- `/dwp-resume {plan_name}` — resume directly (skip the menu).

- `/dwp-resume latest` — resume the highest numbered plan, or the most

recently modified legacy plan when no numbered plan exists.

- `/dwp-resume {plan_name} trust` (or `auto`, or "run to the end") — resume

unattended: no questions between tasks (`../execute/SKILL.md` *Autonomous mode*).

- No parameter → interactive selection (Step 1).

Resolve the full name, ID, unique slug, or `latest` with `../shared/plan_paths.py

--plans-dir <dwp_dir>/plans resolve <selector>`. Validate its folder and

`README.md`; if absent, show available plans. A

folder without `README.md`, or whose README says `Plan Status: materializing`,

is a partial materialization (its `manifest.json` records the intended shape) —

point to `refine`; never execute it.

## Lite and promotion recovery

For v2 Lite plans, read the README's canonical task index, inline anchor record,

state locator and checkpoint before reading older history. A README checkbox wins

over state on desync. Do not treat missing task files as partial when the format

is Lite. Conversely, a `promotion` marker or `materialization: promoting` is a

hard recovery boundary: inspect its phase, preserve existing files and route to

`/dwp-refine promote` to complete the missing transaction step. Never execute

product work in a mixed representation.

An explicit execute/resume request can approve a ready plan's current scope

(Lite or Full). If a new requirement changes scope, criteria or gate, record

the checkpoint and use refine; do not promote or alter approvals implicitly.

## Trust boundary (write scope)

`allowed-tools` includes write-capable `Edit`, `Write`, and `Bash`.

**Writes:** identical scope to `execute` (task outputs, `.dwp/` working state,

per-task commits after gates pass) — resuming does not widen the boundary.

**It MUST NOT:** re-run or "fix up" a completed `[x]` task — under the **DWP

Resume Protocol** (`../spec/DWP_SPECIFICATION.md` §5.3) those are trusted as

recorded, and only three things reopen one: the developer asks, `refine` left a

`(re-validate: …)` marker, or the smoke test fails in a way that implicates it;

skip that post-interruption smoke test, which validates the **world** (the

cheapest standing check) before anything is built on it; repeat a commit, gate,

skill authoring, report or other external action the evidence shows already

happened; migrate a legacy plan (that is the refine migration surface —

`../shared/migrate_v6.py` on explicit request, preview first); push

without instruction; or write outside the repo checkout and

`.dwp/`.

## Workflow

### Step 0 — Check for Parameters

If a parameter was given, resolve the plan (or `latest`), validate folder +

README under `.dwp/plans/`, note `trust`/`auto`, and skip to Step 2. Otherwise

go to Step 1.

### Step 1 — Identify Plan

List plans with `../shared/plan_paths.py --plans-dir <dwp_dir>/plans list`.

Present an ID / name / `latest` menu; validate with `resolve`.

### Step 2 — Assess Current State (CRITICAL)

**Step 2.0a — Pending handoff packet (every generation).** A pending

**handoff packet** comes first: `python3 ../shared/swarm.py handoff show

accept is a §7.3 boundary. The packet is data — the plan decides the next

action.

**Step 2.0 — Detect plan generation (v6).** A manifest contract pointer,

`contract.json` or a `contracts/` chain means **v6**: read `v6.md` and run

its recovery ladder (the journal is the truth) instead of the reconcile

below. A v5 folder continues as written — never migrate it here.

This step implements the **DWP Resume Protocol**

(`../spec/DWP_SPECIFICATION.md` §5.3) — the named ritual any resuming session

performs. It reads the **compact index first** and retrieves history **by

pointer**, never by replaying everything.

1. **Load the compact working index.** Read the plan README's task list (the

small `[x]`/`[ ]` index, the `Plan Status` count, the `**Standard:**` line and

the pre-approval note), the **Active context** block of `PROGRESS.md` (goal

and invariants, active task and next action, unresolved blockers, current

contracts and decisions in force, direct pointers to durable records), and —

when present — `state.json`'s `status`, `checkpoint`, `blocked`, and the

entries of the **active task and its named dependencies only** (not every

gate of every task). Do **not** read every task file or the whole history by

default; retrieve older records later, by pointer, when a step needs them.

2. **Gather actual evidence.** Run `git status`, `git log --oneline -10`, and

`git diff` (if uncommitted changes exist). In a workspace without git, read

`state.json`'s `checkpoint` instead (`../spec/PLAN_STATE.md` §4.4). Note the

current revision.

3. **Reconcile Markdown, JSON and the workspace — before any work.** The

markdown wins every disagreement (`../spec/PLAN_STATE.md` §5):

- Where `state.json` exists, gather machine evidence first: run

`python3 ../verify/plan_contract.py <plan-dir>` (read-only) and surface

every finding — failed gates, `invalidated by refine` reliance, evidence

admitting non-execution, dangling `log=` pointers — in `PROGRESS.md`.

Markdown wins a **status** disagreement; it never lets a summary override

a failed gate, admitted non-execution, invalidated evidence or an

implementation the tree does not show.

- `state.json` vs README checkboxes disagree → regenerate `state.json` from the

README (and git log), note the reconciliation in `PROGRESS.md`, continue.

- `state.json.blocked` is set → surface it: that is why the plan stopped.

- A `[x]` task with no matching commit where the plan commits, a checkpoint

that names work the tree does not show, a summary that contradicts the

files, or instructions in the working index that contradict the task file

→ **do not trust the summary or the flag alone**: inspect the files and the

log, record the finding in `PROGRESS.md`, and treat the task as the

evidence says (in doubt, as not completed). Never repeat a committed action.

- A README `[ ]` marked `(re-validate: …)` → its implementation exists; only

its gates are rerun (`../refine/SKILL.md` 3.7).

- The plan declares a standard newer than this skill → report and stop.

4. **Find the resumption point** — the **first unchecked `[ ]` task** (a task

`in_progress` in `state.json` with a checkpoint is the active one).

5. **Classify partial work at its interruption boundary.** Using the evidence

from steps 2–3 and the active task's Completion & Log, decide **which single

step is missing** and do only that (`../spec/PLAN_STATE.md` §5.1):

| Interrupted… | Evidence to check | Then |

|---|---|---|

| at a clean task boundary (the commonest case) | the last task's whole closure order present and consistent, checkpoint pointing at un-started work | **no repair step is owed** — take over (2.6), smoke-test (2.7), start the next task. Do not hunt for a missing step |

| before the gate ran | uncommitted changes; no gate record | finish the implementation if incomplete; run the gate **once** |

| after the gate, before the commit | gate record present, `passes: true`, and the recorded `fp=` still matches the world — same revision (`git rev-parse HEAD`), same dirty/generated files (`git status --porcelain`), same environment; any difference invalidates reuse | rerun the gate, record the fresh result, then commit **once** |

| after the commit, before the README/log update | commit exists in `git log`; README still `[ ]` | complete log → README → PROGRESS → `state.json`; do **not** re-commit |

| between Markdown and `state.json` updates | README `[x]`, state stale | regenerate `state.json`; nothing else |

| after an external action (report, push, PR, message) | the action's own evidence (report id, remote branch, PR URL in the log) | do **not** repeat it; record that it already happened — a missing receipt is investigated against the service's actual state, never guessed or re-sent |

| mid-implementation with no checkpoint note | dirty tree only | review the diff against the task; incorporate valid partial progress, finish the rest |

Changed inputs since a recorded gate (a later edit, a `refine`, a new

revision) invalidate that gate → rerun it. Where the table resumes the

tail of the update order, the `state.json` step may use the shipped

updater (`../shared/update-state.py`) as a targeted, atomic mutation;

only the reconcile-from-markdown row regenerates the whole file. Retain

the original review baseline: when the interruption landed mid-review, the

diff and criteria under review at the halt are the baseline resumed —

rebuild nothing the checkpoint already records. An interrupted completion

publication leaves a `.finalizing.json` marker in the plan folder: inspect

it and recover via `python3 ../shared/finalize_plan.py <plan-dir>

--candidate <candidate.json> --recover` before any other plan action.

6. **Takeover from another agent or model.** If the checkpoint, log or

`PROGRESS.md` was written by a different agent/model (`state.json.updated_by`,

the log's wording) or the session is a fresh context: read the checkpoint

**pointer** (`task`, `step`, `note`) and verify it against the files it names;

detect contradictory instructions, stale state (revision changed), dirty work

and missing evidence **before** continuing; record a one-line "takeover"

entry in `PROGRESS.md` (who/what, revision, what was verified). Only then

continue. The handoff artifact is the plan itself — nothing required may live

only in a prior conversation, a proprietary task API, or a hook.

7. **Smoke-test before building:** run the repo's cheapest standing check (from

`AGENTS.md` Quick Commands) to confirm the world still works before adding to

it. A failing smoke test is investigated first.

### Step 3 — Report Resumption Status

Report, compactly: the plan's standard and pre-approval; completed `[x]` /

pending `[ ]` counts; the task to resume from and its interruption boundary

(Step 2.5) with the single next action; git state (uncommitted changes, recent

commits, last commit); reconciliation or takeover findings; any blocker. Location:

`.dwp/plans/<plan>/`.

### Step 4 — Handle Partial Work

Apply the Step 2.5 decision. Interactive: if the partial work is unclear or

unrelated, ask the user before proceeding. **Unattended:** unclear or unrelated

changes are a `../spec/AGENT_PROTOCOL.md` §7.3 boundary (reality diverged) —

record `state.json.blocked` with what was found and halt; do not guess and do

not discard work.

### Step 5 — Resume Execution

1. **NEVER redo `[x]` tasks** — trust the README, cross-check git commits (and

the `(re-validate…)` exception above).

2. **NEVER skip `[ ]` tasks** — strict order; complete each fully.

3. **Continue from the first `[ ]` task** — open its file, read fully, address any

logged blocker first.

4. **Complete the current task** under the standard **Execute** rules

(`../execute/SKILL.md` Step 5): gate selected from the actual surface; repair

in scope or stop; task-local closure (skills decision → log → README →

PROGRESS → commit → `state.json`).

5. **Keep the working context bounded while executing.** On a stable run retain

the already-loaded, unchanged context; re-read after a revision change, a

handoff, a context compaction, or uncertainty. Retrieve older records

**only** when a task's `Read Before Starting` names them, a decision cannot

be found in the active-context block, or a pointer is stale or missing — and

then verify what was retrieved rather than guess. Never drop an unresolved

constraint or an active contract to save space.

6. **Continue** to the next `[ ]` task until done or paused — without asking

whether to continue inside the plan's authorization.

> From here the standard **Execute** rules apply (`../execute/SKILL.md`),

> each on demand: Dailybot reports, the Final Review (a)–(e) with the one-time

> Executive Report offer, orchestrator task types and team-agents groups. A

> **legacy** plan (three final tasks) resumes under its own shape — resume never

> migrates it.

### Step 6 — Handle Blockers

If a task log or `state.json.blocked` shows a blocker, read it, fix the issue

within the task's authorized scope, re-run only the affected validations; on

pass: clear `blocked`, mark `[x]`, commit, continue; on fail: log again, stop,

request help (unattended: halt with `blocked` updated).

### Step 7 — Progress Reporting

After resuming and completing a task, show the compact result of

`../execute/SKILL.md` Step 6 (`✓ Resumed and completed: Task N` …). On blocker:

`✗ Task N blocked` with the blocker, action taken, status, and next step.

## The handoff artifact (what every session leaves behind)

Before yielding — at the end of a task, at a checkpoint before a planned

interruption, or when halting — the executing session **writes** (never only

says): the task's Completion & Log (or its partial notes), the README

checkboxes, the `PROGRESS.md` **Active context** block with the exact next

action and the evidence pointers, and `state.json` (`checkpoint` `{task, step,

at, note}` or `blocked`). That is the whole handoff: a fresh agent, another

model, or another harness resumes from these files with Step 2.

## Persistence: same workspace, new machine, or nothing to resume

- **Same workspace:** the handoff artifacts above are already on disk; Step 2

is the whole recovery.

- **v6 plans:** the handoff artifact is the ledger export bundle — see

`v6.md` *Cross-agent and cold resume* (a missing `state.json` on the

receiving host is expected, not an incident).

- **New machine / fresh clone:** `.dwp/` is gitignored by design, so a fresh

`git clone` carries **no** plan data — report that honestly, never

fabricate progress from commits. Transfer is explicit and manual

(`../shared/dwp-paths.md`, "Workspace persistence and transfer"): copy the

**whole plan folder** — README, task files, `PROGRESS.md`, `manifest.json`,

`state.json`, and `analysis_results/` with every cited gate log — check out

the recorded repository revision, and re-create the dirty work the

checkpoint names. The minimum handoff manifest: the complete plan folder,

evidence pointers, repository revision(s), and required dirty work.

- **Missing artifacts** (no plan folder, absent state, dangling `log=` pointer):

report what is missing and stop at that boundary; never reconstruct history

from memory. No daemon, auto-upload, or automatic unignoring of `.dwp/`

exists — persistence is a deliberate copy.

## Important Notes

- **Legacy plans:** execute as recorded; no automatic lifecycle migration.

## Error Handling

- Invalid plan structure → report; ask to fix (`refine`) or proceed with caution.

- Missing task file → report; ask whether to skip or create (unattended: blocker).

- Unclear git state → report findings; ask before proceeding (unattended: §7.3

boundary).

- Contradictory checkpoint / summary vs files → trust the files; record; continue

from the evidence.

- Unresolvable blocker → log in Completion & Log; report; wait for guidance.