fix(handoff): safe-append CLAUDE.md via new subcommand (ship-blocker #15)

Closes the "HANDOFF appends to ./CLAUDE.md without dry-run, backup, or
conflict detection" issue from docs/v4-release/ship-readiness-discovery.md.

Before: phases/HANDOFF.md Step 3 instructed the AI to Read+Edit CLAUDE.md
directly, guarded only by an exact-string presence check. A user with a
hand-crafted CLAUDE.md could get silent append damage on every re-run
that didn't happen to match verbatim.

After: new `script.py append-workflow` subcommand handles it deterministically.
  - HTML-comment sentinels (BEGIN/END prd-taskmaster-v2 workflow) make the
    check idempotent and survive user edits inside the block.
  - Timestamped backup (.prd-taskmaster-backup-<ts>) on every append to an
    existing file — follows the same pattern as backup-prd.
  - --dry-run previews the planned action + content, returns JSON, writes
    nothing. Wired into HANDOFF Step 3 for user review before ExitPlanMode.
  - JSON response with action ∈ {created, skipped, appended, would_*}
    makes the outcome machine-readable for downstream consumers.

HANDOFF.md Step 3 rewritten to call the subcommand instead of
expressing raw Read+Edit intent — keeps mutation logic in the
deterministic layer, matches the codification contract.

Tests: 4 new tests in TestAppendWorkflow covering all four branches
(created / appended-with-backup / skipped-on-markers / dry-run-writes-nothing).
Full suite: 217 passed, 1 skipped, 0 regressions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: claude

phases/HANDOFF.md

@@ -104,26 +104,42 @@ Then **re-invoke the mode picker with Mode D removed from the options.**
 
 ## Step 3: Append Task Workflow to CLAUDE.md
 
-Read the project's `./CLAUDE.md`. Append this section (if not already present):
-
-```markdown
-## Task Execution Workflow (prd-taskmaster-v2)
-
-When implementing tasks, prefer task-master-ai MCP tools over the CLI:
-1. `mcp__task-master-ai__next_task()` or `task-master next` -- get next ready task
-2. `set_task_status(id, "in-progress")` -- note hyphen; underscore is rejected
-3. Implement the task (follow the plan step linked to this task)
-4. `set_task_status(id, "done")` -- mark complete
-5. Update TodoWrite with progress
-6. Repeat from step 1
-
-Valid statuses: `pending`, `in-progress`, `done`, `review`, `blocked`, `deferred`, `cancelled`.
-
-### Progress Tracking
-- Update TodoWrite BEFORE and AFTER each task
-- Cannot proceed to next task without updating TodoWrite
-- TodoWrite = user visibility. TaskMaster = source of truth.
-```
+Use the deterministic subcommand — do **not** do raw Read+Edit. This path is idempotent, takes a timestamped backup when modifying an existing file, and uses HTML-comment sentinels so re-runs are no-ops.
+
+1. Write the workflow content to a tempfile (it is the same content every run):
+
+   ```markdown
+   ## Task Execution Workflow (prd-taskmaster-v2)
+
+   When implementing tasks, prefer task-master-ai MCP tools over the CLI:
+   1. `mcp__task-master-ai__next_task()` or `task-master next` -- get next ready task
+   2. `set_task_status(id, "in-progress")` -- note hyphen; underscore is rejected
+   3. Implement the task (follow the plan step linked to this task)
+   4. `set_task_status(id, "done")` -- mark complete
+   5. Update TodoWrite with progress
+   6. Repeat from step 1
+
+   Valid statuses: `pending`, `in-progress`, `done`, `review`, `blocked`, `deferred`, `cancelled`.
+
+   ### Progress Tracking
+   - Update TodoWrite BEFORE and AFTER each task
+   - Cannot proceed to next task without updating TodoWrite
+   - TodoWrite = user visibility. TaskMaster = source of truth.
+   ```
+
+2. **Preview first** with `--dry-run` so the user (in plan mode) can see what would be written:
+
+   ```bash
+   python3 $SKILL_DIR/script.py append-workflow \
+     --target ./CLAUDE.md \
+     --content-file /tmp/pdtm-workflow-section.md \
+     --dry-run
+   ```
+
+3. After `ExitPlanMode` approval in Step 5, run the real write (same command without `--dry-run`). The JSON response reports one of:
+   - `action: "created"` — no prior CLAUDE.md, fresh file with markers
+   - `action: "skipped"` (reason: `markers_present`) — already wired, no-op
+   - `action: "appended"` — existing CLAUDE.md untouched except for the appended marker block; `backup_path` points at `CLAUDE.md.prd-taskmaster-backup-<ts>`
 
 ## Step 4: Display Summary
 

script.py

@@ -945,6 +945,60 @@ def cmd_backup_prd(args: argparse.Namespace) -> None:
     })
 
 
+WORKFLOW_BEGIN_MARKER = "<!-- BEGIN prd-taskmaster-v2 workflow -->"
+WORKFLOW_END_MARKER = "<!-- END prd-taskmaster-v2 workflow -->"
+
+
+def cmd_append_workflow_section(args: argparse.Namespace) -> None:
+    """Idempotently append the task-execution workflow section to a CLAUDE.md.
+
+    Contract:
+      - If target missing: create it with marker-wrapped content. action=created.
+      - If markers already present: no write. action=skipped.
+      - Else: backup to CLAUDE.md.prd-taskmaster-backup-<ts>.md, then append
+        marker-wrapped content. action=appended.
+      - --dry-run: emit the planned action and content, do not write.
+
+    Replaces the raw Read+Edit flow in phases/HANDOFF.md Step 3, which had no
+    backup, no conflict detection beyond exact-string match, and no dry-run.
+    """
+    target = Path(args.target)
+    content_path = Path(args.content_file)
+    if not content_path.is_file():
+        fail(f"Content file not found: {args.content_file}")
+    content = content_path.read_text()
+
+    wrapped = f"\n{WORKFLOW_BEGIN_MARKER}\n{content.rstrip()}\n{WORKFLOW_END_MARKER}\n"
+
+    if not target.exists():
+        action, backup_path = "created", None
+    else:
+        existing = target.read_text()
+        if WORKFLOW_BEGIN_MARKER in existing:
+            emit({"ok": True, "action": "skipped", "reason": "markers_present",
+                  "target": str(target), "backup_path": None})
+            return
+        action = "appended"
+        backup_path = None
+        if not args.dry_run:
+            ts = datetime.now().strftime("%Y%m%d-%H%M%S")
+            backup_path = str(target.parent / f"{target.name}.prd-taskmaster-backup-{ts}")
+            shutil.copy2(str(target), backup_path)
+
+    if args.dry_run:
+        emit({"ok": True, "action": f"would_{action}", "target": str(target),
+              "content_preview": wrapped, "backup_path": None, "dry_run": True})
+        return
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    mode = "w" if action == "created" else "a"
+    with open(target, mode) as f:
+        f.write(wrapped)
+
+    emit({"ok": True, "action": action, "target": str(target),
+          "backup_path": backup_path, "dry_run": False})
+
+
 def cmd_read_state(args: argparse.Namespace) -> None:
     """Read crash recovery state."""
     state = _read_execution_state()
@@ -1715,6 +1769,13 @@ def build_parser() -> argparse.ArgumentParser:
     # validate-setup
     sub.add_parser("validate-setup", help="Run all Phase 0 setup checks with diagnostic output")
 
+    # append-workflow
+    p = sub.add_parser("append-workflow",
+                       help="Idempotent, backup-safe append of workflow section to CLAUDE.md")
+    p.add_argument("--target", required=True, help="Path to CLAUDE.md")
+    p.add_argument("--content-file", required=True, help="Path to content to append")
+    p.add_argument("--dry-run", action="store_true", help="Preview without writing")
+
     return parser
 
 
@@ -1732,6 +1793,7 @@ def build_parser() -> argparse.ArgumentParser:
     "init-taskmaster": cmd_init_taskmaster,
     "detect-capabilities": cmd_detect_capabilities,
     "validate-setup": cmd_validate_setup,
+    "append-workflow": cmd_append_workflow_section,
 }
 
 

tests/test_script.py

@@ -859,3 +859,71 @@ def test_now_iso_format(self):
         result = self.mod.now_iso()
         assert "T" in result
         assert "+" in result or "Z" in result
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# APPEND-WORKFLOW — ship-blocker #15 (CLAUDE.md safe-append)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+class TestAppendWorkflow:
+    """Closes ship-readiness issue #15: HANDOFF's raw append had no backup,
+    no dry-run, and only exact-string idempotency. Exercise all four branches.
+    """
+
+    def _content(self, tmp_path):
+        c = tmp_path / "section.md"
+        c.write_text("## Task Execution Workflow (prd-taskmaster-v2)\nline one\n")
+        return c
+
+    def test_created_when_target_absent(self, tmp_path):
+        target = tmp_path / "CLAUDE.md"
+        rc, out = run_script(SCRIPT_PY, [
+            "append-workflow", "--target", str(target),
+            "--content-file", str(self._content(tmp_path)),
+        ])
+        assert rc == 0 and out["action"] == "created"
+        body = target.read_text()
+        assert "BEGIN prd-taskmaster-v2 workflow" in body
+        assert "END prd-taskmaster-v2 workflow" in body
+
+    def test_appended_preserves_existing_and_backs_up(self, tmp_path):
+        target = tmp_path / "CLAUDE.md"
+        original = "# User CLAUDE.md\n\nmy own stuff\n"
+        target.write_text(original)
+        rc, out = run_script(SCRIPT_PY, [
+            "append-workflow", "--target", str(target),
+            "--content-file", str(self._content(tmp_path)),
+        ])
+        assert rc == 0 and out["action"] == "appended"
+        assert out["backup_path"] is not None
+        assert Path(out["backup_path"]).read_text() == original
+        assert target.read_text().startswith(original)
+        assert "BEGIN prd-taskmaster-v2 workflow" in target.read_text()
+
+    def test_skipped_when_markers_present(self, tmp_path):
+        target = tmp_path / "CLAUDE.md"
+        target.write_text("# Existing\n<!-- BEGIN prd-taskmaster-v2 workflow -->\n"
+                          "old\n<!-- END prd-taskmaster-v2 workflow -->\n")
+        before = target.read_text()
+        rc, out = run_script(SCRIPT_PY, [
+            "append-workflow", "--target", str(target),
+            "--content-file", str(self._content(tmp_path)),
+        ])
+        assert rc == 0 and out["action"] == "skipped"
+        assert out["reason"] == "markers_present"
+        assert target.read_text() == before  # byte-identical
+
+    def test_dry_run_writes_nothing(self, tmp_path):
+        target = tmp_path / "CLAUDE.md"
+        original = "# Existing\n"
+        target.write_text(original)
+        rc, out = run_script(SCRIPT_PY, [
+            "append-workflow", "--target", str(target),
+            "--content-file", str(self._content(tmp_path)),
+            "--dry-run",
+        ])
+        assert rc == 0 and out["dry_run"] is True
+        assert out["action"] == "would_appended"
+        assert target.read_text() == original  # unchanged
+        assert "BEGIN prd-taskmaster-v2 workflow" in out["content_preview"]