@pareto4/pp-core 1.5.0

package/pp-core/templates/verification-report.md

@@ -0,0 +1,335 @@
+# Verification Report Template
+
+Template for `.planning/phases/XX-name/{phase_num}-VERIFICATION.md` — phase goal verification results.
+
+---
+
+## File Template
+
+```markdown
+---
+phase: XX-name
+verified: YYYY-MM-DDTHH:MM:SSZ
+status: passed | gaps_found | human_needed
+score: N/M must-haves verified
+behavior_unverified: 0 # Count of ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truths (present + wired, behavior not exercised)
+behavior_unverified_items: # Only if behavior_unverified > 0 — the truths above as structured items; emitted regardless of overall status
+  - truth: "Observable truth whose state transition or cancellation/cleanup/ordering invariant no test exercises"
+    test: "What to trigger"
+    expected: "What state must hold afterward"
+    why_human: "Why presence checks can't see it"
+---
+
+# Phase {X}: {Name} Verification Report
+
+**Phase Goal:** {goal from ROADMAP.md}
+**Verified:** {timestamp}
+**Status:** {passed | gaps_found | human_needed}
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | {truth from must_haves} | ✓ VERIFIED | {what confirmed it} |
+| 2 | {truth from must_haves} | ✗ FAILED | {what's wrong} |
+| 3 | {truth from must_haves} | ⚠️ PRESENT_BEHAVIOR_UNVERIFIED | {present + wired; transition/invariant not exercised by a test — see Human Verification} |
+| 4 | {truth from must_haves} | ? UNCERTAIN | {why can't verify} |
+
+**Score:** {N}/{M} truths verified ({P} present, behavior-unverified)
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/components/Chat.tsx` | Message list component | ✓ EXISTS + SUBSTANTIVE | Exports ChatList, renders Message[], no stubs |
+| `src/app/api/chat/route.ts` | Message CRUD | ✗ STUB | File exists but POST returns placeholder |
+| `prisma/schema.prisma` | Message model | ✓ EXISTS + SUBSTANTIVE | Model defined with all fields |
+
+**Artifacts:** {N}/{M} verified
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|----|--------|---------|
+| Chat.tsx | /api/chat | fetch in useEffect | ✓ WIRED | Line 23: `fetch('/api/chat')` with response handling |
+| ChatInput | /api/chat POST | onSubmit handler | ✗ NOT WIRED | onSubmit only calls console.log |
+| /api/chat POST | database | prisma.message.create | ✗ NOT WIRED | Returns hardcoded response, no DB call |
+
+**Wiring:** {N}/{M} connections verified
+
+## Requirements Coverage
+
+| Requirement | Status | Blocking Issue |
+|-------------|--------|----------------|
+| {REQ-01}: {description} | ✓ SATISFIED | - |
+| {REQ-02}: {description} | ✗ BLOCKED | API route is stub |
+| {REQ-03}: {description} | ? NEEDS HUMAN | Can't verify WebSocket programmatically |
+
+**Coverage:** {N}/{M} requirements satisfied
+
+## Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| src/app/api/chat/route.ts | 12 | `// TODO: implement` | ⚠️ Warning | Indicates incomplete |
+| src/components/Chat.tsx | 45 | `return <div>Placeholder</div>` | 🛑 Blocker | Renders no content |
+| src/hooks/useChat.ts | - | File missing | 🛑 Blocker | Expected hook doesn't exist |
+
+**Anti-patterns:** {N} found ({blockers} blockers, {warnings} warnings)
+
+## Human Verification Required
+
+{If no human verification needed:}
+None — all verifiable items checked programmatically.
+
+{If human verification needed:}
+
+### 1. {Test Name}
+**Test:** {What to do}
+**Expected:** {What should happen}
+**Why human:** {Why can't verify programmatically}
+
+### 2. {Test Name}
+**Test:** {What to do}
+**Expected:** {What should happen}
+**Why human:** {Why can't verify programmatically}
+
+## Gaps Summary
+
+{If no gaps:}
+**No gaps found.** Phase goal achieved. Ready to proceed.
+
+{If gaps found:}
+
+### Critical Gaps (Block Progress)
+
+1. **{Gap name}**
+   - Missing: {what's missing}
+   - Impact: {why this blocks the goal}
+   - Fix: {what needs to happen}
+
+2. **{Gap name}**
+   - Missing: {what's missing}
+   - Impact: {why this blocks the goal}
+   - Fix: {what needs to happen}
+
+### Non-Critical Gaps (Can Defer)
+
+1. **{Gap name}**
+   - Issue: {what's wrong}
+   - Impact: {limited impact because...}
+   - Recommendation: {fix now or defer}
+
+## Recommended Fix Plans
+
+{If gaps found, generate fix plan recommendations:}
+
+### {phase}-{next}-PLAN.md: {Fix Name}
+
+**Objective:** {What this fixes}
+
+**Tasks:**
+1. {Task to fix gap 1}
+2. {Task to fix gap 2}
+3. {Verification task}
+
+**Estimated scope:** {Small / Medium}
+
+---
+
+### {phase}-{next+1}-PLAN.md: {Fix Name}
+
+**Objective:** {What this fixes}
+
+**Tasks:**
+1. {Task}
+2. {Task}
+
+**Estimated scope:** {Small / Medium}
+
+---
+
+## Verification Metadata
+
+**Verification approach:** Goal-backward (derived from phase goal)
+**Must-haves source:** {PLAN.md frontmatter | derived from ROADMAP.md goal}
+**Automated checks:** {N} passed, {M} failed
+**Human checks required:** {N}
+**Total verification time:** {duration}
+
+---
+*Verified: {timestamp}*
+*Verifier: Claude (subagent)*
+```
+
+---
+
+## Guidelines
+
+**Status values (overall, frontmatter `status:`):**
+- `passed` — All must-haves verified, no blockers
+- `gaps_found` — One or more critical gaps found
+- `human_needed` — Automated checks pass but human verification required
+
+**Per-truth states (Observable Truths `Status` column):**
+- `✓ VERIFIED` — supporting artifacts pass all checks; for a behavior-dependent truth, a behavioral test exercised the asserted behavior
+- `⚠️ PRESENT_BEHAVIOR_UNVERIFIED` — present + wired, but a state transition or cancellation/cleanup/ordering invariant was not exercised by any test. Counts toward `behavior_unverified`, routes to human verification, and is *excluded* from the verified score. Per-truth only — on its own the overall `status:` becomes `human_needed` (unless a higher-precedence `gaps_found` also applies); the item is preserved in `behavior_unverified_items` regardless.
+- `✗ FAILED` — artifact missing, stub, or unwired
+- `? UNCERTAIN` — can't verify programmatically
+
+**Evidence types:**
+- For EXISTS: "File at path, exports X"
+- For SUBSTANTIVE: "N lines, has patterns X, Y, Z"
+- For WIRED: "Line N: code that connects A to B"
+- For FAILED: "Missing because X" or "Stub because Y"
+
+**Severity levels:**
+- 🛑 Blocker: Prevents goal achievement, must fix
+- ⚠️ Warning: Indicates incomplete but doesn't block
+- ℹ️ Info: Notable but not problematic
+
+**Fix plan generation:**
+- Only generate if gaps_found
+- Group related fixes into single plans
+- Keep to 2-3 tasks per plan
+- Include verification task in each plan
+
+---
+
+## Example
+
+```markdown
+---
+phase: 03-chat
+verified: 2025-01-15T14:30:00Z
+status: gaps_found
+score: 2/5 must-haves verified
+---
+
+# Phase 3: Chat Interface Verification Report
+
+**Phase Goal:** Working chat interface where users can send and receive messages
+**Verified:** 2025-01-15T14:30:00Z
+**Status:** gaps_found
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | User can see existing messages | ✗ FAILED | Component renders placeholder, not message data |
+| 2 | User can type a message | ✓ VERIFIED | Input field exists with onChange handler |
+| 3 | User can send a message | ✗ FAILED | onSubmit handler is console.log only |
+| 4 | Sent message appears in list | ✗ FAILED | No state update after send |
+| 5 | Messages persist across refresh | ? UNCERTAIN | Can't verify - send doesn't work |
+
+**Score:** 1/5 truths verified
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/components/Chat.tsx` | Message list component | ✗ STUB | Returns `<div>Chat will be here</div>` |
+| `src/components/ChatInput.tsx` | Message input | ✓ EXISTS + SUBSTANTIVE | Form with input, submit button, handlers |
+| `src/app/api/chat/route.ts` | Message CRUD | ✗ STUB | GET returns [], POST returns { ok: true } |
+| `prisma/schema.prisma` | Message model | ✓ EXISTS + SUBSTANTIVE | Message model with id, content, userId, createdAt |
+
+**Artifacts:** 2/4 verified
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|----|--------|---------|
+| Chat.tsx | /api/chat GET | fetch | ✗ NOT WIRED | No fetch call in component |
+| ChatInput | /api/chat POST | onSubmit | ✗ NOT WIRED | Handler only logs, doesn't fetch |
+| /api/chat GET | database | prisma.message.findMany | ✗ NOT WIRED | Returns hardcoded [] |
+| /api/chat POST | database | prisma.message.create | ✗ NOT WIRED | Returns { ok: true }, no DB call |
+
+**Wiring:** 0/4 connections verified
+
+## Requirements Coverage
+
+| Requirement | Status | Blocking Issue |
+|-------------|--------|----------------|
+| CHAT-01: User can send message | ✗ BLOCKED | API POST is stub |
+| CHAT-02: User can view messages | ✗ BLOCKED | Component is placeholder |
+| CHAT-03: Messages persist | ✗ BLOCKED | No database integration |
+
+**Coverage:** 0/3 requirements satisfied
+
+## Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| src/components/Chat.tsx | 8 | `<div>Chat will be here</div>` | 🛑 Blocker | No actual content |
+| src/app/api/chat/route.ts | 5 | `return Response.json([])` | 🛑 Blocker | Hardcoded empty |
+| src/app/api/chat/route.ts | 12 | `// TODO: save to database` | ⚠️ Warning | Incomplete |
+
+**Anti-patterns:** 3 found (2 blockers, 1 warning)
+
+## Human Verification Required
+
+None needed until automated gaps are fixed.
+
+## Gaps Summary
+
+### Critical Gaps (Block Progress)
+
+1. **Chat component is placeholder**
+   - Missing: Actual message list rendering
+   - Impact: Users see "Chat will be here" instead of messages
+   - Fix: Implement Chat.tsx to fetch and render messages
+
+2. **API routes are stubs**
+   - Missing: Database integration in GET and POST
+   - Impact: No data persistence, no real functionality
+   - Fix: Wire prisma calls in route handlers
+
+3. **No wiring between frontend and backend**
+   - Missing: fetch calls in components
+   - Impact: Even if API worked, UI wouldn't call it
+   - Fix: Add useEffect fetch in Chat, onSubmit fetch in ChatInput
+
+## Recommended Fix Plans
+
+### 03-04-PLAN.md: Implement Chat API
+
+**Objective:** Wire API routes to database
+
+**Tasks:**
+1. Implement GET /api/chat with prisma.message.findMany
+2. Implement POST /api/chat with prisma.message.create
+3. Verify: API returns real data, POST creates records
+
+**Estimated scope:** Small
+
+---
+
+### 03-05-PLAN.md: Implement Chat UI
+
+**Objective:** Wire Chat component to API
+
+**Tasks:**
+1. Implement Chat.tsx with useEffect fetch and message rendering
+2. Wire ChatInput onSubmit to POST /api/chat
+3. Verify: Messages display, new messages appear after send
+
+**Estimated scope:** Small
+
+---
+
+## Verification Metadata
+
+**Verification approach:** Goal-backward (derived from phase goal)
+**Must-haves source:** 03-01-PLAN.md frontmatter
+**Automated checks:** 2 passed, 8 failed
+**Human checks required:** 0 (blocked by automated failures)
+**Total verification time:** 2 min
+
+---
+*Verified: 2025-01-15T14:30:00Z*
+*Verifier: Claude (subagent)*
+```

package/pp-core/workflows/_runtime-launcher.snippet.sh

@@ -0,0 +1 @@
+_PP_SHIM_NAME="pp-tools.cjs"; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; pp_run() { "$PP_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi

package/pp-core/workflows/add-backlog.md

@@ -0,0 +1,91 @@
+# Add Backlog Item Workflow
+
+Invoked by `/pp:capture --backlog` (`commands/gsd/capture.md`).
+
+Adds an idea to the ROADMAP.md backlog parking lot using 999.x numbering. Backlog items
+are unsequenced ideas that aren't ready for active planning — they live outside the normal
+phase sequence and accumulate context over time.
+
+<process>
+
+## Step 1: Read ROADMAP.md
+
+Check for existing backlog entries:
+
+```bash
+cat .planning/ROADMAP.md
+```
+
+## Step 2: Find next backlog number
+
+```bash
+_PP_SHIM_NAME="pp-tools.cjs"; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; pp_run() { "$PP_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+NEXT=$(pp_run query phase.next-decimal 999 --raw)
+```
+
+If no 999.x phases exist yet, `phase.next-decimal` returns `999.1`. Sparse numbering
+is fine (e.g. 999.1, 999.3) — always use `phase.next-decimal`, never guess.
+
+## Step 3: Write ROADMAP entry
+
+**Write the ROADMAP entry BEFORE creating the directory.** Directory existence is a
+reliable indicator that the phase is already registered, which prevents false duplicate
+detection in any hook that checks for existing 999.x directories (#2280).
+
+Add under a `## Backlog` section. If the section doesn't exist, create it at the end
+of ROADMAP.md:
+
+```markdown
+## Backlog
+
+### Phase {NEXT}: {description} (BACKLOG)
+
+**Goal:** [Captured for future planning]
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (promote with /pp:review-backlog when ready)
+```
+
+## Step 4: Create the phase directory
+
+Apply the `project_code` prefix (if set in `.planning/config.json`) so the backlog directory name is consistent with all other phase-creation paths:
+
+```bash
+SLUG=$(pp_run query generate-slug "$ARGUMENTS" --raw)
+PROJECT_CODE=$(pp_run query config-get project_code --raw 2>/dev/null || echo "")
+PREFIX=$([ -n "$PROJECT_CODE" ] && echo "${PROJECT_CODE}-" || echo "")
+PHASE_DIR=".planning/phases/${PREFIX}${NEXT}-${SLUG}"
+mkdir -p "${PHASE_DIR}"
+touch "${PHASE_DIR}/.gitkeep"
+```
+
+## Step 5: Commit
+
+```bash
+pp_run query commit "docs: add backlog item ${NEXT} — ${ARGUMENTS}" --files .planning/ROADMAP.md "${PHASE_DIR}/.gitkeep"
+```
+
+## Step 6: Report
+
+```
+## 📋 Backlog Item Added
+
+Phase {NEXT}: {description}
+Directory: {PHASE_DIR}/
+
+This item lives in the backlog parking lot.
+Use /pp:discuss-phase {NEXT} to explore it further.
+Use /pp:review-backlog to promote items to active milestone.
+```
+
+</process>
+
+<notes>
+- 999.x numbering keeps backlog items out of the active phase sequence
+- Phase directories are created immediately so /pp:discuss-phase and /pp:plan-phase work on them
+- No `Depends on:` field — backlog items are unsequenced by definition
+- Sparse numbering is fine (999.1, 999.3) — always uses next-decimal
+- Promote backlog items to the active milestone with /pp:review-backlog
+</notes>

package/pp-core/workflows/add-phase.md

@@ -0,0 +1,113 @@
+<purpose>
+Add a new integer phase to the end of the current milestone in the roadmap. Automatically calculates next phase number, creates phase directory, and updates roadmap structure.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- All arguments become the phase description
+- Example: `/pp-add-phase Add authentication` → description = "Add authentication"
+- Example: `/pp-add-phase Fix critical performance issues` → description = "Fix critical performance issues"
+
+If no arguments provided:
+
+```
+ERROR: Phase description required
+Usage: /pp-add-phase <description>
+Example: /pp-add-phase Add authentication system
+```
+
+Exit.
+</step>
+
+<step name="init_context">
+Load phase operation context:
+
+```bash
+_PP_SHIM_NAME="pp-tools.cjs"; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; pp_run() { "$PP_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+INIT=$(pp_run query init.phase-op "0")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Check `roadmap_exists` from init JSON. If false:
+```
+ERROR: No roadmap found (.planning/ROADMAP.md)
+Run /pp:new-project to initialize.
+```
+Exit.
+</step>
+
+<step name="add_phase">
+**Delegate the phase addition to `pp-tools.cjs query phase.add`:**
+
+```bash
+RESULT=$(pp_run query phase.add "${description}")
+```
+
+The CLI handles:
+- Finding the highest existing integer phase number
+- Calculating next phase number (max + 1)
+- Generating slug from description
+- Creating the phase directory (`.planning/phases/{NN}-{slug}/`)
+- Inserting the phase entry into ROADMAP.md with Goal, Depends on, and Plans sections
+
+Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
+</step>
+
+<step name="update_project_state">
+Update STATE.md to reflect the new phase:
+
+1. Read `.planning/STATE.md`
+2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
+   ```
+   - Phase {N} added: {description}
+   ```
+
+If "Roadmap Evolution" section doesn't exist, create it.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {N} added to current milestone:
+- Description: {description}
+- Directory: .planning/phases/{phase-num}-{slug}/
+- Status: Not planned yet
+
+Roadmap updated: .planning/ROADMAP.md
+
+---
+
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
+
+**Phase {N}: {description}**
+
+`/clear` then:
+
+`/pp:plan-phase {N}`
+
+---
+
+**Also available:**
+- `/pp-add-phase <description>` — add another phase
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] `pp-tools.cjs query phase.add` executed successfully
+- [ ] Phase directory created
+- [ ] Roadmap updated with new phase entry
+- [ ] STATE.md updated with roadmap evolution note
+- [ ] User informed of next steps
+</success_criteria>