approved-plan-continuity-hard-gate/docs/plans/2026-04-24-approved-plan-continuity-hard-gate.md

# Approved-Plan Continuity Hard-Gate Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Prevent approved-plan flows from stopping after a task completes by requiring a real next-dispatch receipt unless the workflow explicitly transitions to `waiting_user`, `blocked`, or `pending_verification`.

**Architecture:** Build this in very small slices. First define continuity receipt fields and failure states, then pin the continuity failure with fail-first tests, then implement a minimal evaluator, then bind planner output to real dispatch receipts, then enforce reply-closure continuity. Keep every slice narrow enough to verify in isolation.

**Tech Stack:** Node.js, MJS test runners, file-backed JSON receipts, force-recall hook integration

---

### Task 1: Define continuity receipt fields

**Files:**
- Create: `docs/runbooks/approved-plan-continuity.md`

**Step 1: Write only the receipt field list**
- Define:
  - `planId`
  - `currentTask`
  - `nextDerivedAction`
  - `dispatchedAt`

**Step 2: Verify file exists**
Run: `test -f docs/runbooks/approved-plan-continuity.md && echo OK`
Expected: `OK`

**Step 3: Commit**
```bash
git add docs/runbooks/approved-plan-continuity.md
git commit -m "docs: define continuity dispatch receipt core fields"
```

### Task 2: Define receipt linkage fields

**Files:**
- Modify: `docs/runbooks/approved-plan-continuity.md`

**Step 1: Add linkage fields**
- Define:
  - `dispatchRunId`
  - `childSessionKey`
  - `replyClosureState`

**Step 2: Verify field names exist**
Run: `grep -n "dispatchRunId\|childSessionKey\|replyClosureState" docs/runbooks/approved-plan-continuity.md`
Expected: matching lines found

**Step 3: Commit**
```bash
git add docs/runbooks/approved-plan-continuity.md
git commit -m "docs: define continuity receipt linkage fields"
```

### Task 3: Define legal terminal states

**Files:**
- Modify: `docs/runbooks/approved-plan-continuity.md`

**Step 1: Add legal closure states**
- Define the only legal non-dispatch closures:
  - `waiting_user`
  - `blocked`
  - `pending_verification`

**Step 2: Verify text exists**
Run: `grep -n "waiting_user\|blocked\|pending_verification" docs/runbooks/approved-plan-continuity.md`
Expected: matching lines found

**Step 3: Commit**
```bash
git add docs/runbooks/approved-plan-continuity.md
git commit -m "docs: define legal approved-plan terminal states"
```

### Task 4: Create continuity gate script skeleton

**Files:**
- Create: `scripts/approved_plan_continuity_gate.mjs`

**Step 1: Add CLI skeleton**
- Support `--input` and placeholder JSON output.

**Step 2: Verify it runs**
Run: `node scripts/approved_plan_continuity_gate.mjs --compact --input /dev/null || true`
Expected: placeholder response or controlled failure

**Step 3: Commit**
```bash
git add scripts/approved_plan_continuity_gate.mjs
git commit -m "chore: add approved-plan continuity gate skeleton"
```

### Task 5: Create continuity gate test skeleton

**Files:**
- Create: `scripts/test_approved_plan_continuity_gate.mjs`

**Step 1: Add test harness skeleton**
- Basic runner + fixture helper only.

**Step 2: Verify it runs**
Run: `node scripts/test_approved_plan_continuity_gate.mjs || true`
Expected: test runner executes

**Step 3: Commit**
```bash
git add scripts/test_approved_plan_continuity_gate.mjs
git commit -m "test: add continuity gate test skeleton"
```

### Task 6: Add fail-first test for missing dispatch receipt

**Files:**
- Modify: `scripts/test_approved_plan_continuity_gate.mjs`

**Step 1: Write the test**
- task complete
- next action known
- no dispatch receipt
- not waiting/blocked/pending_verification
- expect continuity failure

**Step 2: Run tests to verify it fails**
Run: `node scripts/test_approved_plan_continuity_gate.mjs`
Expected: FAIL

**Step 3: Commit**
```bash
git add scripts/test_approved_plan_continuity_gate.mjs
git commit -m "test: fail when approved plan step stops without dispatch receipt"
```

### Task 7: Add pass test for existing dispatch receipt

**Files:**
- Modify: `scripts/test_approved_plan_continuity_gate.mjs`

**Step 1: Write the test**
- task complete
- next action known
- dispatch receipt exists
- expect pass

**Step 2: Run tests to verify it fails**
Run: `node scripts/test_approved_plan_continuity_gate.mjs`
Expected: FAIL until evaluator exists

**Step 3: Commit**
```bash
git add scripts/test_approved_plan_continuity_gate.mjs
git commit -m "test: allow approved plan step with dispatch receipt"
```

### Task 8: Add pass test for waiting_user closure

**Files:**
- Modify: `scripts/test_approved_plan_continuity_gate.mjs`

**Step 1: Write the test**
- task complete
- next action known
- no dispatch receipt
- replyClosureState=`waiting_user`
- expect pass

**Step 2: Run tests to verify it fails**
Run: `node scripts/test_approved_plan_continuity_gate.mjs`
Expected: FAIL until evaluator exists

**Step 3: Commit**
```bash
git add scripts/test_approved_plan_continuity_gate.mjs
git commit -m "test: allow waiting_user continuity closure"
```

### Task 9: Add pass test for blocked closure

**Files:**
- Modify: `scripts/test_approved_plan_continuity_gate.mjs`

**Step 1: Write the test**
- replyClosureState=`blocked`
- expect pass

**Step 2: Run tests to verify it fails**
Run: `node scripts/test_approved_plan_continuity_gate.mjs`
Expected: FAIL until evaluator exists

**Step 3: Commit**
```bash
git add scripts/test_approved_plan_continuity_gate.mjs
git commit -m "test: allow blocked continuity closure"
```

### Task 10: Add pass test for pending_verification closure

**Files:**
- Modify: `scripts/test_approved_plan_continuity_gate.mjs`

**Step 1: Write the test**
- replyClosureState=`pending_verification`
- expect pass

**Step 2: Run tests to verify it fails**
Run: `node scripts/test_approved_plan_continuity_gate.mjs`
Expected: FAIL until evaluator exists

**Step 3: Commit**
```bash
git add scripts/test_approved_plan_continuity_gate.mjs
git commit -m "test: allow pending verification continuity closure"
```

### Task 11: Implement minimal continuity evaluator

**Files:**
- Modify: `scripts/approved_plan_continuity_gate.mjs`

**Step 1: Add evaluator logic**
- Fail only when:
  - approved plan task complete
  - next action known
  - no dispatch receipt
  - and not in legal terminal state

**Step 2: Run tests**
Run: `node scripts/test_approved_plan_continuity_gate.mjs`
Expected: PASS for Tasks 6-10

**Step 3: Commit**
```bash
git add scripts/approved_plan_continuity_gate.mjs scripts/test_approved_plan_continuity_gate.mjs
git commit -m "feat: evaluate approved-plan continuity closure"
```

### Task 12: Create dispatch binding skeleton

**Files:**
- Create: `scripts/approved_plan_dispatch_binding.mjs`

**Step 1: Add CLI skeleton**
- Support input parsing and placeholder receipt output.

**Step 2: Verify it runs**
Run: `node scripts/approved_plan_dispatch_binding.mjs --compact --input /dev/null || true`
Expected: placeholder response or controlled failure

**Step 3: Commit**
```bash
git add scripts/approved_plan_dispatch_binding.mjs
git commit -m "chore: add approved-plan dispatch binding skeleton"
```

### Task 13: Add fail-first test for planner action without bound dispatch

**Files:**
- Modify: `scripts/test_approved_plan_continuity_gate.mjs`

**Step 1: Write the test**
- planner returns `derivedAction`
- but no dispatch receipt is written
- expect fail

**Step 2: Run tests to verify it fails**
Run: `node scripts/test_approved_plan_continuity_gate.mjs`
Expected: FAIL

**Step 3: Commit**
```bash
git add scripts/test_approved_plan_continuity_gate.mjs
git commit -m "test: fail when derived action has no bound dispatch"
```

### Task 14: Add pass test for planner action with bound dispatch receipt

**Files:**
- Modify: `scripts/test_approved_plan_continuity_gate.mjs`

**Step 1: Write the test**
- planner returns `derivedAction`
- receipt is written
- expect pass

**Step 2: Run tests to verify it fails**
Run: `node scripts/test_approved_plan_continuity_gate.mjs`
Expected: FAIL until binding exists

**Step 3: Commit**
```bash
git add scripts/test_approved_plan_continuity_gate.mjs
git commit -m "test: pass when derived action is bound to dispatch receipt"
```

### Task 15: Define continuity receipt state storage

**Files:**
- Create: `state/approved-plan-continuity/.gitkeep`
- Create: `state/approved-plan-continuity/README.md`

**Step 1: Write the state shape**
- Include receipt filenames and minimum fields.

**Step 2: Verify files exist**
Run: `test -f state/approved-plan-continuity/README.md && test -f state/approved-plan-continuity/.gitkeep && echo OK`
Expected: `OK`

**Step 3: Commit**
```bash
git add state/approved-plan-continuity/.gitkeep state/approved-plan-continuity/README.md
git commit -m "docs: define approved-plan continuity receipt storage"
```

### Task 16: Implement minimal dispatch receipt writer

**Files:**
- Modify: `scripts/approved_plan_dispatch_binding.mjs`

**Step 1: Write dispatch receipts**
- When a known action is truly bound, write file-backed receipt.

**Step 2: Run tests**
Run: `node scripts/test_approved_plan_continuity_gate.mjs`
Expected: binding tests pass

**Step 3: Commit**
```bash
git add scripts/approved_plan_dispatch_binding.mjs scripts/test_approved_plan_continuity_gate.mjs state/approved-plan-continuity/.gitkeep state/approved-plan-continuity/README.md
git commit -m "feat: write approved-plan continuity dispatch receipts"
```

### Task 17: Add fail-first regression for “task done but stopped”

**Files:**
- Modify: `scripts/test_approved_plan_continuity_gate.mjs`

**Step 1: Write the regression test**
- completed task
- next step known
- no dispatch receipt
- reply tries to close anyway
- expect violation

**Step 2: Run tests to verify it fails if regression exists**
Run: `node scripts/test_approved_plan_continuity_gate.mjs`
Expected: PASS after fix, but must detect regression if broken

**Step 3: Commit**
```bash
git add scripts/test_approved_plan_continuity_gate.mjs
git commit -m "test: lock regression for task done but stopped"
```

### Task 18: Hook continuity gate into force-recall handler

**Files:**
- Modify: `hooks/force-recall/handler.ts`

**Step 1: Wire continuity gate into reply closure path**
- Enforce continuity before normal closeout.

**Step 2: Run targeted verification**
Run:
- `node scripts/test_approved_plan_continuity_gate.mjs`
- `node scripts/test_force_recall_long_task_preflight.mjs`
- `node --check hooks/force-recall/handler.ts`
Expected: PASS

**Step 3: Commit**
```bash
git add hooks/force-recall/handler.ts scripts/approved_plan_continuity_gate.mjs scripts/approved_plan_dispatch_binding.mjs scripts/test_approved_plan_continuity_gate.mjs
 git commit -m "feat: enforce approved-plan continuity at reply closure"
```

### Task 19: Peer review continuity evaluator and binding

**Files:**
- Review: `scripts/approved_plan_continuity_gate.mjs`
- Review: `scripts/approved_plan_dispatch_binding.mjs`
- Review: `scripts/test_approved_plan_continuity_gate.mjs`

**Step 1: Request review**
- Focus: does this really fix continuity failure instead of adding prompt-only guidance?

**Step 2: Record verdict**
- Include commands and findings.

**Step 3: Apply follow-up fixes if needed**
```bash
# only if reviewer requests changes
git add <changed-files>
git commit -m "fix: address continuity gate review feedback"
```

### Task 20: Peer review hook integration and handoff

**Files:**
- Review: `hooks/force-recall/handler.ts`
- Review: `docs/runbooks/approved-plan-continuity.md`
- Review: `state/approved-plan-continuity/README.md`

**Step 1: Request review**
- Focus: can approved-plan task completion still stop without dispatch receipt?

**Step 2: Record verification output**
- Include commands and reviewer verdict.

**Step 3: Final state**
- Leave task in `pending_verification`; do not mark complete.