@pareto4/pp-core 1.5.0

package/pp-core/templates/roadmap.md

@@ -0,0 +1,202 @@
+# Roadmap Template
+
+Template for `.planning/ROADMAP.md`.
+
+## Initial Roadmap (v1.0 Greenfield)
+
+```markdown
+# Roadmap: [Project Name]
+
+## Overview
+
+[One paragraph describing the journey from start to finish]
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [ ] **Phase 1: [Name]** - [One-line description]
+- [ ] **Phase 2: [Name]** - [One-line description]
+- [ ] **Phase 3: [Name]** - [One-line description]
+- [ ] **Phase 4: [Name]** - [One-line description]
+
+## Phase Details
+
+### Phase 1: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Nothing (first phase)
+**Requirements**: [REQ-01, REQ-02, REQ-03]  <!-- brackets optional, parser handles both formats -->
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+  3. [Observable behavior from user perspective]
+**Plans**: [Number of plans, e.g., "3 plans" or "TBD"]
+
+Plans:
+- [ ] 01-01: [Brief description of first plan]
+- [ ] 01-02: [Brief description of second plan]
+- [ ] 01-03: [Brief description of third plan]
+
+### Phase 2: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 1
+**Requirements**: [REQ-04, REQ-05]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+**Plans**: [Number of plans]
+
+Plans:
+- [ ] 02-01: [Brief description]
+- [ ] 02-02: [Brief description]
+
+### Phase 2.1: Critical Fix (INSERTED)
+**Goal**: [Urgent work inserted between phases]
+**Depends on**: Phase 2
+**Success Criteria** (what must be TRUE):
+  1. [What the fix achieves]
+**Plans**: 1 plan
+
+Plans:
+- [ ] 02.1-01: [Description]
+
+### Phase 3: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 2
+**Requirements**: [REQ-06, REQ-07, REQ-08]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+  3. [Observable behavior from user perspective]
+**Plans**: [Number of plans]
+
+Plans:
+- [ ] 03-01: [Brief description]
+- [ ] 03-02: [Brief description]
+
+### Phase 4: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 3
+**Requirements**: [REQ-09, REQ-10]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+**Plans**: [Number of plans]
+
+Plans:
+- [ ] 04-01: [Brief description]
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. [Name] | 0/3 | Not started | - |
+| 2. [Name] | 0/2 | Not started | - |
+| 3. [Name] | 0/2 | Not started | - |
+| 4. [Name] | 0/1 | Not started | - |
+```
+
+<guidelines>
+**Initial planning (v1.0):**
+- Phase count depends on granularity setting (coarse: 3-5, standard: 5-8, fine: 8-12)
+- Each phase delivers something coherent
+- Phases can have 1+ plans (split if >3 tasks or multiple subsystems)
+- Plans use naming: {phase}-{plan}-PLAN.md (e.g., 01-02-PLAN.md)
+- No time estimates (this isn't enterprise PM)
+- Progress table updated by execute workflow
+- Plan count can be "TBD" initially, refined during planning
+
+**Success criteria:**
+- 2-5 observable behaviors per phase (from user's perspective)
+- Cross-checked against requirements during roadmap creation
+- Flow downstream to `must_haves` in plan-phase
+- Verified by verify-phase after execution
+- Format: "User can [action]" or "[Thing] works/exists"
+
+**After milestones ship:**
+- Collapse completed milestones in `<details>` tags
+- Add new milestone sections for upcoming work
+- Keep continuous phase numbering (never restart at 01)
+</guidelines>
+
+<status_values>
+- `Not started` - Haven't begun
+- `In progress` - Currently working
+- `Complete` - Done (add completion date)
+- `Deferred` - Pushed to later (with reason)
+</status_values>
+
+## Milestone-Grouped Roadmap (After v1.0 Ships)
+
+After completing first milestone, reorganize with milestone groupings:
+
+```markdown
+# Roadmap: [Project Name]
+
+## Milestones
+
+- ✅ **v1.0 MVP** - Phases 1-4 (shipped YYYY-MM-DD)
+- 🚧 **v1.1 [Name]** - Phases 5-6 (in progress)
+- 📋 **v2.0 [Name]** - Phases 7-10 (planned)
+
+## Phases
+
+<details>
+<summary>✅ v1.0 MVP (Phases 1-4) - SHIPPED YYYY-MM-DD</summary>
+
+### Phase 1: [Name]
+**Goal**: [What this phase delivers]
+**Plans**: 3 plans
+
+Plans:
+- [x] 01-01: [Brief description]
+- [x] 01-02: [Brief description]
+- [x] 01-03: [Brief description]
+
+[... remaining v1.0 phases ...]
+
+</details>
+
+### 🚧 v1.1 [Name] (In Progress)
+
+**Milestone Goal:** [What v1.1 delivers]
+
+#### Phase 5: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 4
+**Plans**: 2 plans
+
+Plans:
+- [ ] 05-01: [Brief description]
+- [ ] 05-02: [Brief description]
+
+[... remaining v1.1 phases ...]
+
+### 📋 v2.0 [Name] (Planned)
+
+**Milestone Goal:** [What v2.0 delivers]
+
+[... v2.0 phases ...]
+
+## Progress
+
+| Phase | Milestone | Plans Complete | Status | Completed |
+|-------|-----------|----------------|--------|-----------|
+| 1. Foundation | v1.0 | 3/3 | Complete | YYYY-MM-DD |
+| 2. Features | v1.0 | 2/2 | Complete | YYYY-MM-DD |
+| 5. Security | v1.1 | 0/2 | Not started | - |
+```
+
+**Notes:**
+- Milestone emoji: ✅ shipped, 🚧 in progress, 📋 planned
+- Completed milestones collapsed in `<details>` for readability
+- Current/future milestones expanded
+- Continuous phase numbering (01-99)
+- Progress table includes milestone column

package/pp-core/templates/spec.md

@@ -0,0 +1,333 @@
+# Phase Spec Template
+
+Template for `.planning/phases/XX-name/{phase_num}-SPEC.md` — locks requirements before discuss-phase.
+
+**Purpose:** Capture WHAT a phase delivers and WHY, with enough precision that requirements are falsifiable. discuss-phase reads this file and focuses on HOW to implement (skipping "what/why" questions already answered here).
+
+**Key principle:** Every requirement must be falsifiable — you can write a test or check that proves it was met or not. Vague requirements like "improve performance" are not allowed.
+
+**Downstream consumers:**
+- `discuss-phase` — reads SPEC.md at startup; treats Requirements, Boundaries, and Acceptance Criteria as locked; skips "what/why" questions
+- `pp-planner` — reads locked requirements to constrain plan scope
+- `pp-verifier` — uses acceptance criteria as explicit pass/fail checks
+
+---
+
+## File Template
+
+```markdown
+# Phase [X]: [Name] — Specification
+
+**Created:** [date]
+**Ambiguity score:** [score] (gate: ≤ 0.20)
+**Requirements:** [N] locked
+
+## Goal
+
+[One precise sentence — specific and measurable. NOT "improve X" — instead "X changes from A to B".]
+
+## Background
+
+[Current state from codebase — what exists today, what's broken or missing, what triggers this work. Grounded in code reality, not abstract description.]
+
+## Requirements
+
+1. **[Short label]**: [Specific, testable statement.]
+   - Current: [what exists or does NOT exist today]
+   - Target: [what it should become after this phase]
+   - Acceptance: [concrete pass/fail check — how a verifier confirms this was met]
+
+2. **[Short label]**: [Specific, testable statement.]
+   - Current: [what exists or does NOT exist today]
+   - Target: [what it should become after this phase]
+   - Acceptance: [concrete pass/fail check]
+
+[Continue for all requirements. Each must have Current/Target/Acceptance.]
+
+## Boundaries
+
+**In scope:**
+- [Explicit list of what this phase produces]
+- [Each item is a concrete deliverable or behavior]
+
+**Out of scope:**
+- [Explicit list of what this phase does NOT do] — [brief reason why it's excluded]
+- [Adjacent problems excluded from this phase] — [brief reason]
+
+## Constraints
+
+[Performance, compatibility, data volume, dependency, or platform constraints.
+If none: "No additional constraints beyond standard project conventions."]
+
+## Acceptance Criteria
+
+- [ ] [Pass/fail criterion — unambiguous, verifiable]
+- [ ] [Pass/fail criterion]
+- [ ] [Pass/fail criterion]
+
+[Every acceptance criterion must be a checkbox that resolves to PASS or FAIL.
+No "should feel good", "looks reasonable", or "generally works" — those are not checkboxes.]
+
+## Edge Coverage
+
+**Coverage:** [resolved]/[applicable] applicable edges resolved · [unresolved] unresolved
+
+| Category | Requirement | Status | Resolution / Reason |
+|----------|-------------|--------|---------------------|
+| [category] | [Rn] | [✅ covered / ⛔ dismissed / 🧪 backstop / ⚠ UNRESOLVED] | [acceptance criterion ref, dismissal reason, or backstop test note] |
+
+[Generated by the edge-completeness probe (Step 5.5). `covered` rows correspond to
+Acceptance Criteria above; `backstop` rows must be carried into plan-phase `must_haves`.
+`⚠ UNRESOLVED` rows are flagged: planner must treat as assumption.]
+
+## Prohibitions (must-NOT)
+
+**Coverage:** [resolved]/[applicable] applicable prohibitions resolved · [unresolved] unresolved
+
+| Prohibition (must-NOT statement) | Requirement | Status | Verification / Reason |
+|----------------------------------|-------------|--------|------------------------|
+| [MUST NOT … must-NOT statement] | [Rn] | [resolved / dismissed / ⚠ UNRESOLVED] | [verification: test \| judgment, or dismissal reason] |
+
+[Generated by the prohibition probe (Step 5.6). `resolved` prohibitions become NEGATIVE
+acceptance criteria; a `resolved`/`test` row is a checkable negative the verifier iterates
+over, a `resolved`/`judgment` row routes to judgment review. Resolved prohibitions are lifted
+into `must_haves.prohibitions` by plan-phase. `dismissed` rows carry a required non-empty
+reason. `⚠ UNRESOLVED` rows are flagged: planner must treat as assumption.]
+
+## Ambiguity Report
+
+| Dimension          | Score | Min  | Status | Notes                              |
+|--------------------|-------|------|--------|------------------------------------|
+| Goal Clarity       |       | 0.75 |        |                                    |
+| Boundary Clarity   |       | 0.70 |        |                                    |
+| Constraint Clarity |       | 0.65 |        |                                    |
+| Acceptance Criteria|       | 0.70 |        |                                    |
+| **Ambiguity**      |       | ≤0.20|        |                                    |
+
+Status: ✓ = met minimum, ⚠ = below minimum (planner treats as assumption)
+
+## Interview Log
+
+[Key decisions made during the Socratic interview. Format: round → question → answer → decision locked.]
+
+| Round | Perspective    | Question summary         | Decision locked                    |
+|-------|----------------|-------------------------|------------------------------------|
+| 1     | Researcher     | [what was asked]        | [what was decided]                 |
+| 2     | Simplifier     | [what was asked]        | [what was decided]                 |
+| 3     | Boundary Keeper| [what was asked]        | [what was decided]                 |
+
+[If --auto mode: note "auto-selected" decisions with the reasoning Claude used.]
+
+---
+
+*Phase: [XX-name]*
+*Spec created: [date]*
+*Next step: /pp:discuss-phase [X] — implementation decisions (how to build what's specified above)*
+```
+
+<good_examples>
+
+**Example 1: Feature addition (Post Feed)**
+
+```markdown
+# Phase 3: Post Feed — Specification
+
+**Created:** 2025-01-20
+**Ambiguity score:** 0.12
+**Requirements:** 4 locked
+
+## Goal
+
+Users can scroll through posts from accounts they follow, with new posts available after pull-to-refresh.
+
+## Background
+
+The database has a `posts` table and `follows` table. No feed query or feed UI exists today. The home screen shows a placeholder "Your feed will appear here." This phase builds the feed query, API endpoint, and the feed list component.
+
+## Requirements
+
+1. **Feed query**: Returns posts from followed accounts ordered by creation time, descending.
+   - Current: No feed query exists — `posts` table is queried directly only from profile pages
+   - Target: `GET /api/feed` returns paginated posts from followed accounts, newest first, max 20 per page
+   - Acceptance: Query returns correct posts for a user who follows 3 accounts with known post counts; cursor-based pagination advances correctly
+
+2. **Feed display**: Posts display in a scrollable card list.
+   - Current: Home screen shows static placeholder text
+   - Target: Home screen renders feed cards with author, timestamp, post content, and reaction count
+   - Acceptance: Feed renders without error for 0 posts (empty state shown), 1 post, and 20+ posts
+
+3. **Pull-to-refresh**: User can refresh the feed manually.
+   - Current: No refresh mechanism exists
+   - Target: Pull-down gesture triggers refetch; new posts appear at top of list
+   - Acceptance: After a new post is created in test, pull-to-refresh shows the new post without full app restart
+
+4. **New posts indicator**: When new posts arrive, a banner appears instead of auto-scrolling.
+   - Current: No such mechanism
+   - Target: "3 new posts" banner appears when refetch returns posts newer than the oldest visible post; tapping banner scrolls to top and shows new posts
+   - Acceptance: Banner appears for ≥1 new post, does not appear when no new posts, tap navigates to top
+
+## Boundaries
+
+**In scope:**
+- Feed query (backend) — posts from followed accounts, paginated
+- Feed list UI (frontend) — post cards with author, timestamp, content, reaction counts
+- Pull-to-refresh gesture
+- New posts indicator banner
+- Empty state when user follows no one or no posts exist
+
+**Out of scope:**
+- Creating posts — that is Phase 4
+- Reacting to posts — that is Phase 5
+- Following/unfollowing accounts — that is Phase 2 (already done)
+- Push notifications for new posts — separate backlog item
+
+## Constraints
+
+- Feed query must use cursor-based pagination (not offset) — the database has 500K+ posts and offset pagination is unacceptably slow beyond page 3
+- The feed card component must reuse the existing `<AvatarImage>` component from Phase 2
+
+## Acceptance Criteria
+
+- [ ] `GET /api/feed` returns posts only from followed accounts (not all posts)
+- [ ] `GET /api/feed` supports `cursor` parameter for pagination
+- [ ] Feed renders correctly at 0, 1, and 20+ posts
+- [ ] Pull-to-refresh triggers refetch
+- [ ] New posts indicator appears when posts newer than current view exist
+- [ ] Empty state renders when user follows no one
+
+## Ambiguity Report
+
+| Dimension          | Score | Min  | Status | Notes                            |
+|--------------------|-------|------|--------|----------------------------------|
+| Goal Clarity       | 0.92  | 0.75 | ✓      |                                  |
+| Boundary Clarity   | 0.95  | 0.70 | ✓      | Explicit out-of-scope list       |
+| Constraint Clarity | 0.80  | 0.65 | ✓      | Cursor pagination required       |
+| Acceptance Criteria| 0.85  | 0.70 | ✓      | 6 pass/fail criteria             |
+| **Ambiguity**      | 0.12  | ≤0.20| ✓      |                                  |
+
+## Interview Log
+
+| Round | Perspective     | Question summary              | Decision locked                         |
+|-------|-----------------|------------------------------|-----------------------------------------|
+| 1     | Researcher      | What exists in posts today?  | posts + follows tables exist, no feed  |
+| 2     | Simplifier      | Minimum viable feed?         | Cards + pull-refresh, no auto-scroll   |
+| 3     | Boundary Keeper | What's NOT this phase?       | Creating posts, reactions out of scope |
+| 3     | Boundary Keeper | What does done look like?    | Scrollable feed with 4 card fields     |
+
+---
+
+*Phase: 03-post-feed*
+*Spec created: 2025-01-20*
+*Next step: /pp:discuss-phase 3 — implementation decisions (card layout, loading skeleton, etc.)*
+```
+
+**Example 2: CLI tool (Database backup)**
+
+```markdown
+# Phase 2: Backup Command — Specification
+
+**Created:** 2025-01-20
+**Ambiguity score:** 0.15
+**Requirements:** 3 locked
+
+## Goal
+
+A `gsd backup` CLI command creates a reproducible database snapshot that can be restored by `gsd restore` (a separate phase).
+
+## Background
+
+No backup tooling exists. The project uses PostgreSQL. Developers currently use `pg_dump` manually — there is no standardized process, no output naming convention, and no CI integration. Three incidents in the last quarter involved restoring from wrong or corrupt dumps.
+
+## Requirements
+
+1. **Backup creation**: CLI command executes a full database backup.
+   - Current: No `backup` subcommand exists in the CLI
+   - Target: `gsd backup` connects to the database (via `DATABASE_URL` env or `--db` flag), runs pg_dump, writes output to `./backups/YYYY-MM-DD_HH-MM-SS.dump`
+   - Acceptance: Running `gsd backup` on a test database creates a `.dump` file; running `pg_restore` on that file recreates the database without error
+
+2. **Network retry**: Transient network failures are retried automatically.
+   - Current: pg_dump fails immediately on network error
+   - Target: Backup retries up to 3 times with 5-second delay; 4th failure exits with code 1 and a message to stderr
+   - Acceptance: Simulating 2 sequential network failures causes 2 retries then success; simulating 4 failures causes exit code 1 and stderr message
+
+3. **Partial cleanup**: Failed backups do not leave corrupt files.
+   - Current: Manual pg_dump leaves partial files on failure
+   - Target: If backup fails after starting, the partial `.dump` file is deleted before exit
+   - Acceptance: After a simulated failure mid-dump, no `.dump` file exists in `./backups/`
+
+## Boundaries
+
+**In scope:**
+- `gsd backup` subcommand (full dump only)
+- Output to `./backups/` directory (created if missing)
+- Network retry (3 attempts)
+- Partial file cleanup on failure
+
+**Out of scope:**
+- `gsd restore` — that is Phase 3
+- Incremental backups — separate backlog item (full dump only for now)
+- S3 or remote storage — separate backlog item
+- Encryption — separate backlog item
+- Scheduled/cron backups — separate backlog item
+
+## Constraints
+
+- Must use `pg_dump` (not a custom query) — ensures compatibility with standard `pg_restore`
+- `--no-retry` flag must be available for CI use (fail fast, no retries)
+
+## Acceptance Criteria
+
+- [ ] `gsd backup` creates a `.dump` file in `./backups/YYYY-MM-DD_HH-MM-SS.dump` format
+- [ ] `gsd backup` uses `DATABASE_URL` env var or `--db` flag for connection
+- [ ] 3 retries on network failure, then exit code 1 with stderr message
+- [ ] `--no-retry` flag skips retries and fails immediately on first error
+- [ ] No partial `.dump` file left after a failed backup
+
+## Ambiguity Report
+
+| Dimension          | Score | Min  | Status | Notes                          |
+|--------------------|-------|------|--------|--------------------------------|
+| Goal Clarity       | 0.90  | 0.75 | ✓      |                                |
+| Boundary Clarity   | 0.95  | 0.70 | ✓      | Explicit out-of-scope list     |
+| Constraint Clarity | 0.75  | 0.65 | ✓      | pg_dump required               |
+| Acceptance Criteria| 0.80  | 0.70 | ✓      | 5 pass/fail criteria           |
+| **Ambiguity**      | 0.15  | ≤0.20| ✓      |                                |
+
+## Interview Log
+
+| Round | Perspective     | Question summary              | Decision locked                         |
+|-------|-----------------|------------------------------|-----------------------------------------|
+| 1     | Researcher      | What backup tooling exists?  | None — pg_dump manual only             |
+| 2     | Simplifier      | Minimum viable backup?       | Full dump only, local only             |
+| 3     | Boundary Keeper | What's NOT this phase?       | Restore, S3, encryption excluded       |
+| 4     | Failure Analyst | What goes wrong on failure?  | Partial files, CI fail-fast needed     |
+
+---
+
+*Phase: 02-backup-command*
+*Spec created: 2025-01-20*
+*Next step: /pp:discuss-phase 2 — implementation decisions (progress reporting, flag design, etc.)*
+```
+
+</good_examples>
+
+<guidelines>
+**Every requirement needs all three fields:**
+- Current: grounds the requirement in reality — what exists today?
+- Target: the concrete change — not "improve X" but "X becomes Y"
+- Acceptance: the falsifiable check — how does a verifier confirm this?
+
+**Ambiguity Report must reflect the actual interview.** If a dimension is below minimum, mark it ⚠ — the planner knows to treat it as an assumption rather than a locked requirement.
+
+**Interview Log is evidence of rigor.** Don't skip it. It shows that requirements came from discovery, not assumption.
+
+**Boundaries protect the phase from scope creep.** The out-of-scope list with reasoning is as important as the in-scope list. Future phases that touch adjacent areas can point to this SPEC.md to understand what was intentionally excluded.
+
+**SPEC.md is a one-way door for requirements.** discuss-phase will treat these as locked. If requirements change after SPEC.md is written, the user should update SPEC.md first, then re-run discuss-phase.
+
+**SPEC.md does NOT replace CONTEXT.md.** They serve different purposes:
+- SPEC.md: what the phase delivers (requirements, boundaries, acceptance criteria)
+- CONTEXT.md: how the phase will be implemented (decisions, patterns, tradeoffs)
+
+discuss-phase generates CONTEXT.md after reading SPEC.md.
+</guidelines>