DeepWorkPlan — Refine

Modify an existing plan (add / edit /
split / reorder tasks, update the README, promote a Lite plan to Full, or — only
on explicit request — migrate a legacy ending or a v5 plan to v6).

No drafts (2.4.0): create materializes an executable Lite plan directly,
so there is nothing to "refine into a plan" any more. refine operates on a
plan folder under .dwp/plans/. The .dwp/drafts/ directory and the
PLAN_{name}_draft_refined.md artifact were removed in 2.4.0.

Shared resources (read these)

• `../shared/dwp-paths.md` — plans at .dwp/plans/,
  plans at .dwp/plans/<plan>/.
• `../shared/context.sh` — resolve dwp_dir.
• Guide (essential — read for this flow): `../guide/authoring.md` (plan README §4, task-file anatomy §5 incl. the Touched Surface, mandatory elements) and `../guide/structure.md` (§1–§2 naming and folders).
• Guide (conditional — read only when the trigger fires): `../guide/orchestrator.md` / `../guide/team-agents.md` only for plans that use them; `../guide/execution.md` §6.1 when editing the Final Review (or a legacy plan's final tasks). Do not read other guide files for this flow; `../guide/GUIDE.md` is the routing index, consulted only when a section is not named above.
• Shared contract (conditional — read the named steps only when the trigger fires): `../create/SKILL.md` Steps 3.5–3.7 and 4.4–4.5 when promoting a Lite plan, adding or splitting a task, completing a partial materialization, or migrating — the one contract for task anatomy, gate selection, the Final Review, the ledger, the write order and the plan-quality check (refine never has a second template); `../spec/PLAN_STATE.md` §5–§6 when the plan carries state.json (regeneration, evidence invalidation) or on migrate (the declared-migration line).
• Conditional — read only when the trigger fires: `../examples/CREATE_PLAN.md` — prompt patterns for professional rewriting; read it when rewriting plan-level structure or authoring new plan sections — task-level edits and promotions need only the contracts named above.

Parameter Support

Parameter	Description	Example
(none)	Interactive — choose a plan	/dwp-refine
plan {plan_name}	Modify an existing final plan	/dwp-refine plan auth_refactor
plan latest	Modify the most recent plan	/dwp-refine plan latest
migrate {plan_name}	Explicit migration: a legacy three-task ending to the v5 Final Review shape, or a v5 plan to v6; never automatic	/dwp-refine migrate auth_refactor
promote {plan_name}	Promote a ready Lite plan to Full task files without changing scope	/dwp-refine promote small_fix

Trust boundary (write scope)

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

Writes: edits confined to the target plan's files under
.dwp/plans/<plan>/ — task content, ordering, the README's task list and
counts, PROGRESS.md, and the regenerated state.json — kept mutually
consistent. Deleting a completed task, dropping the Final Review (or a legacy
plan's final tasks), or invalidating completed evidence requires explicit
developer confirmation. manifest.json is never rewritten
(../spec/PLAN_STATE.md §2).

It MUST NOT: touch source files, write outside .dwp/, weaken a task's
acceptance criteria or validation gate without saying so in the diff summary,
change a plan's standard without an explicit migrate request, or commit/push
anything (refinement output stays uncommitted working state).

Workflow

Step 2 was the draft workflow; it was removed in 2.4.0. The remaining step
numbers are unchanged so existing cross-references keep resolving.

Step 0 — Determine Target Type

• No parameters → Step 1 (interactive).
• plan {name} / plan latest → Step 3 (Plan Workflow).
• migrate {name} → Step 4 (Explicit Migration).
• promote {name} → Step 5 (Lite Promotion).

Step 1 — Interactive Selection

List the plans under .dwp/plans/ and ask which one to modify (add / edit /
split / reorder tasks, adjust context, promote a Lite plan). Route to Step 3, or
to Step 5 when the developer asks to promote. Mention migrate only if the
selected plan is legacy.

Plan Workflow

Step 3 — Select and Modify a Final Plan

3.1 Select. If not specified, list plans with ../shared/plan_paths.py --plans-dir <dwp_dir>/plans list. Resolve a full name, numeric ID, unique slug,
or latest with the same helper's resolve command. latest is the highest
numbered plan when one exists, or the most recently modified legacy plan.

3.2 Read and classify. Read the plan README, the task files, PROGRESS.md,
and — when present — manifest.json and state.json. Establish:

• The plan's generation. A folder carrying manifest.json with a
  contract pointer, contract.json, or a contracts/ chain is a v6
  plan: scope, acceptance, permissions or envelope changes are
  contract amendments — author the revised contract (a copy of the
  live one, edited), then run python3 ../shared/ledger.py --plan <dir> amend --contract <draft> --authority <who> --note <reason> --human-note <file> (`../spec/V6_LIFECYCLE.md`
  §5: revision under contracts/, amendment event, fresh approval citing
  the new contract id, re-evidence of the revised criteria — one
  resumable verb, never by hand). The markdown task edits
  below still apply to the plan's human layer; the contract never moves
  through them. A v5 plan is never migrated to v6 implicitly; the one
  explicit path is the migration surface below (3.2a).
• 3.2a — v5 → v6 migration (explicit request only). When the developer
  asks to migrate a v5 plan to v6, route to
  `../shared/migrate_v6.py` — never rewrite
  records by hand: preview (integrity check + task mapping + the
  re-evidence list — criteria whose v5 evidence cannot carry become
  blocked by default until their gates re-run under v6), then
  migrate --authority WHO (backup → contract synthesis → manifest swap →
  journal import → projection; resumable at every phase), and rollback
  for the explicit reverse (restores the v5 bytes from the verified
  backup; refuses when post-migration v6 work exists unless --force).
  Imported gate evidence is labeled imported with the v5 source digest —
  never observed. The normative flow is
  `../spec/V6_LIFECYCLE.md` §8. The reverse
  direction (v6 → v5) does not exist.
• The plan's standard (../spec/PLAN_STATE.md §6.1): a declared
  **Standard:** line in the README wins; otherwise manifest.spec_version;
  otherwise (no manifest) the shape of its files. New shape = a single
  {N}.task_final_review.md last. Legacy shape = three final tasks
  (security_review → skills_agents_discovery → executive_report). Refine
  retains the plan's shape; only Step 4 changes it.
• Partial materialization: a folder whose README.md is missing, says
  Plan Status: materializing, or links a task file that does not exist is an
  interrupted create. Read manifest.json and the README task list to report
  the intended shape against what exists; offer to complete it (regenerate
  only the missing files from analysis_results/PLAN_ANALYSIS.md per
  ../create/SKILL.md Step 4.4, leaving existing task files and the manifest
  intact, then flip the status line) or discard it (explicit confirmation).
  Never overwrite unrelated artifacts.
• Objective, context, guidelines, tasks and their [x]/[ ] status, and any
  in-progress checkpoint.

3.3 Show current state — objective, standard (new / legacy), the task list
with status, and the location .dwp/plans/<plan>/.

3.4 Choose modification: Add task(s) / Edit task / Split task / Reorganize /
Update README / View task details / Done.

3.5 Execute modifications

Final-task protection (lifecycle-aware, applies throughout):

• New shape: the Final Review must remain the last task. It CANNOT
  be deleted or reordered, but it CAN be edited (e.g. to add plan-specific
  review criteria). If the user tries to delete or move it, explain: "The Final
  Review is the mandatory final task. It can be edited but not deleted or
  reordered."

• Legacy shape: Security Review stays third-to-last, Skills & Agents
  Discovery second-to-last, Executive Report last; same rule — editable, never
  deleted or reordered — unless the user runs an explicit migrate (Step 4).

• Insert positions are therefore 1..N-1 for a new-shape plan and 1..N-3 for a
  legacy plan; before-final always means "immediately before the first final
  task of this plan's shape".

• Add task(s): ask for the insert position (a number in the range above,
  before-final, or after {k}), gather task details, create the task file with
  the full standard structure (../create/SKILL.md Step 4.4 item 2: ten sections
  incl. Touched Surface, selected gates, the skills-decision checklist step, the
  Skills disposition: / Gate record: log lines), renumber subsequent files,
  and run 3.6 Synchronize.

• Edit task: show current content; apply changes to title / instructions /
  acceptance criteria / Touched Surface / validation / everything. Final tasks are
  editable. Then run 3.7 Invalidate affected evidence and 3.6 Synchronize.

• Split task (unfinished, oversized): split task k into two or more tasks
  k, k+1, … — one objective per child (../spec/DWP_SPECIFICATION.md §6.4) —
  such that every requirement, acceptance criterion, constraint and
  reference of the original lands in exactly one child — nothing is dropped or
  summarized. Distribute the original's Touched Surface, Read Before Starting
  pointers and Outputs to the child that owns them; a child that consumes another
  child's output names it in Read Before Starting. Carry any already-recorded
  evidence (a partial Completion & Log, a checkpoint, a passing gate) into the
  child that owns that work, verbatim, and leave a one-line pointer in the other
  children. A [x] task is never split without explicit confirmation (it is
  completed work). Renumber and run 3.6 Synchronize.

• Reorganize: move / merge / delete. Renumber files as needed and always
  keep the plan's final task(s) last. Warn before deleting a completed [x]
  task (explicit confirmation). Merging keeps every requirement of both tasks.

• Update README: objective / context / global guidelines / execution rules
  (including an explicit Executive Report request, which the Final Review honors).

• View task details: display the full task file.

• Done: run 3.6 Synchronize once more, report modifications (what was
  added / edited / split / reordered, which evidence was invalidated and why),
  and offer to execute/resume via the Execute (../execute/SKILL.md) or
  Resume (../resume/SKILL.md) sub-skill.

3.6 Synchronize (after every modification — the plan must never be left
inconsistent):

• README: task list entries, links (N.task_{title}.md), the Plan Status: X/N count, the Analysis Outputs table, and any Team Agents Configuration
  tables (Parallel Task Groups / roles) that name task numbers.
• Task files: numbers in file names and titles; Read Before Starting
  references to renumbered tasks; Team Agents Metadata (Can Run With,
  Blocks); Blocks/Depends wording that names a task.
• PROGRESS.md: the active task / next action, and a dated entry describing
  the refinement (what changed, what was invalidated).
• state.json (when present): regenerate it from the markdown
  (../spec/PLAN_STATE.md §5) — one entry per task file, ids and files matching
  the disk, task_count = current number of task files, completed_count =
  README [x] count. Entries of completed tasks keep their completed_at,
  commit, gates and outcome (re-keyed if renumbered). Write atomically.
  manifest.json is not touched: its task_count is the count at creation;
  the live count is state.json.task_count.
• Never leave a README [x] for a task file that no longer exists, or a task
  file with no README entry.

3.7 Invalidate affected evidence (when requirements change): when an edit
changes a task's acceptance criteria, scope, Touched Surface or gate — or
changes an upstream task whose outputs a completed task consumed — list the
affected completed tasks and, with the user's explicit confirmation, mark them
for re-validation: README checkbox back to [ ] with a (re-validate: requirements changed by refine on YYYY-MM-DD) note, state.json entry status
pending with its gate records kept and their evidence prefixed
invalidated by refine YYYY-MM-DD:, and an appended "Invalidated" note in
the task's Completion & Log. Completed logs, commits and outcome records are
never deleted or rewritten — the executor re-runs the gates and re-marks the
task (../spec/PLAN_STATE.md §5.1). Without confirmation, record the concern in
PROGRESS.md and change nothing.

Amendment record (append to the affected task's Completion & Log, and mirror
the entry in PROGRESS.md): every scope, criterion or deferral change leaves
one durable record with these fields — no field is optional padding, and an
amendment is never backdated:

### Amendment {n} — YYYY-MM-DD
Original criterion: <verbatim quote of the criterion as authored>
Observed: <investigation finding, blocker, failed gate or changed input>
Disposition: revised criterion | deferred requirement | unexecuted scenario | failed gate
Revised criterion: <verbatim new criterion — only for "revised criterion">
Reason: <why the original cannot or should not stand>
Authority: user (explicit acceptance) | developer (refine request) | evidence (machine-detected mismatch)
Affected tasks: <ids>
Evidence invalidated: <gate commands per task, prefixed by refine>
Evidence preserved: <gate commands whose inputs are unchanged>

What an amendment may close and what it may not. Name the state honestly
(the five evidence states, ../spec/PLAN_STATE.md "Evidence truth and
amendments"): a completed
investigation is real work but is never the execution of the original
criterion; an unexecuted scenario is recorded as not performed and
contributes no passing evidence; a deferred requirement moves the criterion
to a named destination task and needs Authority: user or developer; a
failed gate stays failing until the same acceptance intent is re-run and
passes; only an achieved product outcome — the criterion as written,
verified by its gate — completes the task unchanged. Correcting a broken
command preserves the same acceptance intent; substituting an easier check is
not repair, it is a revised criterion and needs its own amendment.

Bounded exceptions. The user may explicitly accept a bounded exception to a
criterion; record Authority: user with the acceptance (quote or reference)
and the boundary of what it covers. Pre-approval and trust authorize unattended
execution — they are never blanket permission to abandon a core objective. A
mandatory criterion that cannot be met is recorded as a blocker
(state.json blocked), never as completed work; the guarded writer refuses
that closure and read-only verification reports it.

Explicit Migration

Step 4 — Migrate a Legacy Plan (only on migrate {name})

Migration is the only way a plan changes standard, and it happens only
when the developer asks for it explicitly (../spec/DWP_SPECIFICATION.md §6.5,
../spec/PLAN_STATE.md §6.1). Never suggest it as a side effect of another edit.

Route by recorded generation before Step 4.1. For a v5 plan, use the v5 →
v6 migration path in Step 3.2a and ../spec/V6_LIFECYCLE.md §8: run
python3 ../shared/migrate_v6.py --plan <dir> preview, inspect the re-evidence
list and blockers, then run python3 ../shared/migrate_v6.py --plan <dir> --authority <who> migrate on the explicit request. Report the migrated
contract, journal, projection, and criteria requiring new evidence. Do not
apply Steps 4.1–4.6 below to a v5 plan. Those steps only migrate a pre-v5
three-task ending to the retained v5 Final Review shape. A v6 plan already
uses the current generation and has no migration step.

1. Classify (Step 3.2). If the plan already has the v5 Final Review shape, say
   so and stop.
2. Preserve completed work. Any [x] task — including a legacy final task
   that has already run — is left exactly as it is. Only unstarted tasks may
   take the new shape.
3. Reshape the ending. If none of the three legacy final tasks has started,
   replace them with a single {N}.task_final_review.md (content per
   ../create/SKILL.md Step 4.4 item 3, incl. the security pass, final-state
   validation, skills reconciliation, documentation reconciliation, completion
   and report offer). If the
   Security Review already ran, keep it and replace only the two unstarted
   closing tasks with the Final Review's remaining parts (b)–(e); the Final
   Review security pass (a) still runs the required local review over the
   accumulated change set. Record the decision in PROGRESS.md.
4. Add the new-shape elements to unstarted tasks and to the plan: a Touched
   Surface (planned surface, risk class, selected gate — derived from
   docs/TESTING_GUIDE.md, or the full-suite fallback where the repository
   documents no scoped invocation) on every unstarted behavior-changing task; the
   skills-decision checklist step and the Skills disposition: / Gate record:
   log lines; analysis_results/SKILLS_CANDIDATES.md; the Analysis Outputs
   table rows; the Final Review note in the README.
5. Declare it. Add to the README Plan Variables the line
   **Standard:** DWP spec 2.3.0 (migrated from A.B.C on YYYY-MM-DD — <reason>)
   and a dated entry in PROGRESS.md. Leave manifest.json untouched (creation
   provenance).
6. Synchronize (Step 3.6) and report: what was reshaped, what was preserved,
   what the executor will do differently from here.

Step 5 — Lite Promotion

Promotion changes only task representation. Read spec/LITE_PLANS.md, the Lite
README decision record and v2 state first. An explicit promotion request approves
the current proposal's representation change; record Approval: approved before
starting. It does not authorize product execution or a scope change. Refuse an
active task, an unresolved product-work blocker, or an unknown format. A
scope/requirement change is refine, not promotion.

Recovery comes before starting a new transaction. If a promotion marker
already exists (including after the format switched to Full), resume that same
transaction from its recorded phase. Verify the existing destination files
against the source records and evidence; write only missing files, preserve user
edits, and never overwrite conflicting evidence. A conflict becomes an actionable
blocker. Do not reject the marker that execute/resume sent here to recover, and
do not create a second promotion transaction.

1. Record promotion: lite → full intent atomically in state and README.
2. Generate Full task files for unchanged logical task IDs, preserving criteria,
   gates, logs, completion status and lineage. Promotion never splits tasks or
   grants invented evidence. Split or add work separately through refine, with
   the affected approval and evidence invalidated before promotion resumes.
3. Validate contiguous IDs, links, gates, final review and Markdown/state
   correspondence before switching the README's authoritative task representation.
4. Rewrite the state projection atomically with format: full, then clear the
   promotion marker last. Preserve manifest creation provenance and never rewrite
   it to disguise a changed live task count.

If interrupted, retain the marker and identify the exact missing boundary;
complete only missing files and preserve user edits. Execute/resume must not run
a marked plan. Full-to-Lite downgrade is not automatic.

Important Notes

• Preserve completed work: never alter [x] tasks unless explicitly asked;
  invalidation (3.7) marks them for re-validation, it does not rewrite them.
• Renumber carefully: keep task file numbers, README references, dependency
  pointers, team-agents metadata and state.json ids in sync (3.6).
• Maintain consistency: task files follow the standard structure
  (../guide/authoring.md §5; the shared contract in ../create/SKILL.md).
• One shape per plan: refine keeps the plan's standard; migrate is the only
  exception and is explicit.
• No mandatory report: refine never adds an Executive Report task; it may
  record an explicit report request in the README guidelines.
• Git ignore: everything under .dwp/ is git-ignored.
• No draft artifact: refine always operates on a plan folder under
  .dwp/plans/. Nothing is written to .dwp/drafts/ — it no longer exists.

Error Handling

• Plan not found → list available plans and let the user select.
• Partial materialization (no README.md, Plan Status: materializing, or a dangling task link) → offer complete / discard (3.2).
• Task number out of range → show the valid range for this plan's shape and re-ask.
• Deleting or splitting a completed [x] task → confirm explicitly first.
• Plan has work in progress (a checkpoint or an in_progress task) → warn about
  impact; suggest finishing the current task first; never edit the in-progress
  task's evidence.
• migrate on a plan already in the requested generation and shape → report and stop.