feat: close ship-blockers #4 (preflight state) and #20 (uninstall.sh)

#4 — cmd_preflight now emits a `recommended_action` field with one of:
  recover | run_setup | generate_prd | parse_prd | resume | complete
The previously-ambiguous row (prd exists + task_count == 0) resolves
explicitly to `parse_prd`. Decision logic lives in the deterministic
layer; callers no longer have to re-derive state from raw fields.

#20 — new uninstall.sh mirrors install.sh conventions:
  - --yes for non-interactive, --dry-run for preview, --help prints usage
  - Removes ~/.claude/skills/prd-taskmaster-v2/ only
  - Best-effort prune of the updates.json tracker entry (jq-gated, non-fatal)
  - Explicit non-goal: leaves downstream .taskmaster/ artifacts untouched
    (user data, not skill data)
  - Status output goes to stderr to match install.sh's pipe-through behavior

Tests: 5 new recommended_action cases cover all preflight state transitions.
One pre-existing crash-state test had its trailing assertions restored after
they were accidentally split by a prior edit. Full suite: 222 passed / 1 skip.

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

Author: claude

script.py

@@ -154,6 +154,24 @@ def cmd_preflight(args: argparse.Namespace) -> None:
 
     # Check crash state
     crash_state = _read_execution_state()
+    has_crash = crash_state.get("has_incomplete", False)
+
+    # Decision table — single authoritative mapping of state -> next action.
+    # Closes ship-blocker #4: callers no longer have to assemble the 4-way
+    # ambiguity (prd×tasks) themselves. Order matters: crash recovery wins,
+    # then setup gap, then the prd/tasks axis.
+    if has_crash:
+        recommended_action = "recover"
+    elif not has_taskmaster:
+        recommended_action = "run_setup"
+    elif prd_path is None:
+        recommended_action = "generate_prd"
+    elif task_count == 0:
+        recommended_action = "parse_prd"
+    elif tasks_pending > 0:
+        recommended_action = "resume"
+    else:
+        recommended_action = "complete"
 
     emit({
         "ok": True,
@@ -164,8 +182,9 @@ def cmd_preflight(args: argparse.Namespace) -> None:
         "tasks_pending": tasks_pending,
         "taskmaster_method": tm_method["method"],
         "has_claude_md": has_claude_md,
-        "has_crash_state": crash_state.get("has_incomplete", False),
-        "crash_state": crash_state if crash_state.get("has_incomplete") else None,
+        "has_crash_state": has_crash,
+        "crash_state": crash_state if has_crash else None,
+        "recommended_action": recommended_action,
     })
 
 

tests/test_script.py

@@ -63,6 +63,45 @@ def test_preflight_with_crash_state(self, tmp_project, execution_state):
         assert out["crash_state"]["mode"] == "sequential"
         assert out["crash_state"]["checkpoint"] == "2"
 
+    # Closes ship-blocker #4 — recommended_action disambiguates state.
+    def test_recommended_action_run_setup(self, tmp_path):
+        rc, out = run_script(SCRIPT_PY, ["preflight"], cwd=str(tmp_path))
+        assert rc == 0 and out["recommended_action"] == "run_setup"
+
+    def test_recommended_action_generate_prd(self, tmp_path):
+        (tmp_path / ".taskmaster" / "docs").mkdir(parents=True)
+        (tmp_path / ".taskmaster" / "tasks").mkdir(parents=True)
+        rc, out = run_script(SCRIPT_PY, ["preflight"], cwd=str(tmp_path))
+        assert rc == 0 and out["recommended_action"] == "generate_prd"
+
+    def test_recommended_action_parse_prd_when_prd_but_no_tasks(self, tmp_path):
+        """The original ambiguous row — prd exists, task_count == 0."""
+        docs = tmp_path / ".taskmaster" / "docs"
+        docs.mkdir(parents=True)
+        (tmp_path / ".taskmaster" / "tasks").mkdir(parents=True)
+        (docs / "prd.md").write_text("# stub\n")
+        rc, out = run_script(SCRIPT_PY, ["preflight"], cwd=str(tmp_path))
+        assert rc == 0 and out["recommended_action"] == "parse_prd"
+
+    def test_recommended_action_resume_when_tasks_pending(self, tmp_path):
+        docs = tmp_path / ".taskmaster" / "docs"
+        tasks = tmp_path / ".taskmaster" / "tasks"
+        docs.mkdir(parents=True); tasks.mkdir(parents=True)
+        (docs / "prd.md").write_text("# stub\n")
+        (tasks / "tasks.json").write_text(
+            '{"tasks":[{"id":1,"status":"pending"},{"id":2,"status":"done"}]}')
+        rc, out = run_script(SCRIPT_PY, ["preflight"], cwd=str(tmp_path))
+        assert rc == 0 and out["recommended_action"] == "resume"
+
+    def test_recommended_action_complete_when_no_pending(self, tmp_path):
+        docs = tmp_path / ".taskmaster" / "docs"
+        tasks = tmp_path / ".taskmaster" / "tasks"
+        docs.mkdir(parents=True); tasks.mkdir(parents=True)
+        (docs / "prd.md").write_text("# stub\n")
+        (tasks / "tasks.json").write_text('{"tasks":[{"id":1,"status":"done"}]}')
+        rc, out = run_script(SCRIPT_PY, ["preflight"], cwd=str(tmp_path))
+        assert rc == 0 and out["recommended_action"] == "complete"
+
     def test_preflight_detects_claude_md(self, tmp_project):
         """Detects CLAUDE.md in project root."""
         (tmp_project / "CLAUDE.md").write_text("# Project guide")

uninstall.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# ============================================================================
+# prd-taskmaster-v2 uninstaller (closes ship-readiness issue #20)
+# ============================================================================
+# Usage:
+#   bash uninstall.sh          # interactive confirmation
+#   bash uninstall.sh --yes    # non-interactive
+#   bash uninstall.sh --dry-run
+#
+# Removes ~/.claude/skills/prd-taskmaster-v2/ and the update-tracker entry
+# created by install.sh. Leaves user-generated .taskmaster/ artifacts in
+# downstream projects alone — those are user data, not skill data.
+# ============================================================================
+
+set -euo pipefail
+
+SKILL_NAME="prd-taskmaster-v2"
+SKILL_DIR="${SKILL_DIR:-${HOME}/.claude/skills/${SKILL_NAME}}"
+UPDATES_FILE="${HOME}/.config/claude-skills/updates.json"
+
+YES=0
+DRY_RUN=0
+for arg in "$@"; do
+    case "$arg" in
+        --yes|-y)    YES=1 ;;
+        --dry-run)   DRY_RUN=1 ;;
+        -h|--help)
+            sed -n '2,14p' "$0"; exit 0 ;;
+        *) echo "unknown arg: $arg" >&2; exit 2 ;;
+    esac
+done
+
+if { [[ -t 1 ]] || [[ -t 2 ]]; } && [[ -z "${CI:-}" ]] && [[ -z "${NO_COLOR:-}" ]]; then
+    RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[0;33m'
+    CYAN='\033[0;36m'; BOLD='\033[1m'; RESET='\033[0m'
+else
+    RED=''; GREEN=''; YELLOW=''; CYAN=''; BOLD=''; RESET=''
+fi
+
+info() { printf "${CYAN}[info]${RESET}  %s\n" "$*" >&2; }
+ok()   { printf "${GREEN}[ok]${RESET}    %s\n" "$*" >&2; }
+warn() { printf "${YELLOW}[warn]${RESET}  %s\n" "$*" >&2; }
+err()  { printf "${RED}[error]${RESET} %s\n" "$*" >&2; }
+
+if [[ ! -d "${SKILL_DIR}" ]]; then
+    warn "Skill not installed at ${SKILL_DIR} — nothing to do."
+    exit 0
+fi
+
+info "Found skill at ${BOLD}${SKILL_DIR}${RESET}"
+if [[ -f "${SKILL_DIR}/.version" ]]; then
+    info "Installed version: $(head -1 "${SKILL_DIR}/.version" 2>/dev/null || echo unknown)"
+fi
+
+if [[ ${YES} -eq 0 ]] && [[ ${DRY_RUN} -eq 0 ]]; then
+    printf "${YELLOW}Remove ${SKILL_DIR}? [y/N]${RESET} " >&2
+    read -r reply
+    case "$reply" in
+        y|Y|yes|YES) ;;
+        *) info "Aborted."; exit 0 ;;
+    esac
+fi
+
+if [[ ${DRY_RUN} -eq 1 ]]; then
+    info "[dry-run] would remove: ${SKILL_DIR}"
+    [[ -f "${UPDATES_FILE}" ]] && info "[dry-run] would prune ${SKILL_NAME} entry from ${UPDATES_FILE}"
+    exit 0
+fi
+
+rm -rf "${SKILL_DIR}"
+ok "Removed ${SKILL_DIR}"
+
+# Best-effort prune of the updates tracker entry. Non-fatal if jq is missing
+# or the file doesn't exist — worst case a stale entry survives.
+if [[ -f "${UPDATES_FILE}" ]] && command -v jq >/dev/null 2>&1; then
+    tmp="$(mktemp)"
+    if jq "del(.[\"${SKILL_NAME}\"])" "${UPDATES_FILE}" > "${tmp}" 2>/dev/null; then
+        mv "${tmp}" "${UPDATES_FILE}"
+        ok "Pruned ${SKILL_NAME} from ${UPDATES_FILE}"
+    else
+        rm -f "${tmp}"
+        warn "Could not prune updates tracker (non-fatal)"
+    fi
+fi
+
+ok "Uninstall complete. Downstream .taskmaster/ directories in your projects were left untouched."