@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plan-build-run/references/plan-format.md

@@ -0,0 +1,351 @@
+# Plan Format Reference
+
+Complete reference for the XML task specification used in Plan-Build-Run plan files.
+
+---
+
+## Plan File Structure
+
+Every plan file has two sections:
+1. **YAML Frontmatter** — metadata about the plan
+2. **XML Tasks** — the executable task specifications
+
+---
+
+## YAML Frontmatter
+
+```yaml
+---
+phase: "02-authentication"
+plan: "02-01"
+type: "feature"
+wave: 1
+depends_on: []
+files_modified:
+  - "src/auth/discord.ts"
+  - "src/middleware/auth.ts"
+autonomous: true
+discovery: 1
+gap_closure: false
+must_haves:
+  truths:
+    - "User can authenticate via Discord OAuth"
+    - "JWT token is set in httpOnly cookie"
+  artifacts:
+    - "src/auth/discord.ts: >50 lines"
+    - "src/middleware/auth.ts: >30 lines"
+  key_links:
+    - "Auth middleware applied to protected routes"
+    - "Login button calls authenticateWithDiscord()"
+provides:
+  - "AuthService class"
+  - "POST /api/auth/login endpoint"
+  - "requireAuth() middleware"
+consumes:
+  - "Database connection (from plan 01-01)"
+implements:
+  - "REQ-F-001"
+  - "REQ-F-002"
+closes_issues:
+  - 42
+  - 57
+---
+```
+
+### Frontmatter Fields
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `phase` | YES | string | Phase directory name (e.g., "02-authentication") |
+| `plan` | YES | string | Plan ID: `{phase_num}-{plan_num}` (e.g., "02-01") |
+| `type` | YES | enum | `feature`, `bugfix`, `refactor`, `infrastructure`, `docs` |
+| `wave` | YES | int | Execution wave (1 = independent, 2+ = has deps) |
+| `depends_on` | YES | array | Plan IDs that must complete first. `[]` if Wave 1. |
+| `files_modified` | YES | array | All files this plan creates or modifies |
+| `autonomous` | YES | bool | `true` if no human checkpoints |
+| `discovery` | NO | int | Research level: 0=skip, 1=quick, 2=standard, 3=deep. Default: 1 |
+| `gap_closure` | NO | bool | `true` if this is a gap-closure plan. Default: false |
+| `must_haves` | YES | object | Goal-backward derivation |
+| `must_haves.truths` | YES | array | Observable truths that must be true when done |
+| `must_haves.artifacts` | YES | array | Files/modules that must exist. Append `: >N lines` for size hints. |
+| `must_haves.key_links` | YES | array | Connections between components. Append `: grep command` for verification. |
+| `provides` | NO | array | What this plan exports for other plans to consume (classes, endpoints, modules) |
+| `consumes` | NO | array | What this plan needs from prior plans. Format: `"Thing (from plan XX-YY)"` |
+| `implements` | NO (WARNING if absent) | array | REQ-IDs from REQUIREMENTS.md this plan addresses. Primary traceability field. |
+| `requirement_ids` | NO | array | DEPRECATED — use `implements:` instead. Kept for backward compat. |
+| `dependency_fingerprints` | NO | object | Hashes of dependency phase SUMMARY.md files at plan-creation time. Used to detect stale plans. |
+| `data_contracts` | NO | array | Cross-boundary parameter mappings for calls where arguments originate from external boundaries. Format: `"param: source (context) [fallback]"` |
+| `closes_issues` | NO | number[] | GitHub issue numbers to close when this plan's final commit lands. Default: `[]` |
+
+### Data Contracts
+
+When a task's `<action>` includes calls across module boundaries where arguments come from external sources (hook stdin, env vars, API params, config files), document the parameter-to-source mapping in `data_contracts` frontmatter and in the `<action>` step itself.
+
+Example frontmatter:
+
+```yaml
+data_contracts:
+  - "sessionId: data.session_id (hook stdin) [undefined in CLI context]"
+  - "config: configLoad(planningDir) (disk) [resolveConfig(undefined)]"
+```
+
+Example in `<action>`:
+
+```
+3. Call classifyArtifact(llmConfig, planningDir, content, fileType, data.session_id)
+   Data contract: sessionId ← data.session_id from hook stdin (undefined in CLI context)
+```
+
+**When to apply:** Any call where caller and callee are in different modules AND at least one argument originates from an external boundary. Internal helper calls within the same module do not need contracts.
+
+---
+
+## Summary Section
+
+Every plan file MUST end with a `## Summary` section after all XML tasks. This section provides a compact overview (~500 tokens) for injection into executor prompts, avoiding the need to inline the full plan (~1,500 tokens).
+
+Format:
+
+```
+## Summary
+
+**Plan {plan_id}**: {1-sentence description of what this plan does}
+
+**Tasks:**
+1. {task_id}: {task name} -- {files touched}
+2. {task_id}: {task name} -- {files touched}
+3. {task_id}: {task name} -- {files touched}
+
+**Key files:** {comma-separated list of all files_modified}
+
+**Must-haves:** {comma-separated list of truths from frontmatter}
+
+**Provides:** {comma-separated list from provides field}
+
+**Consumes:** {comma-separated list from consumes field, or "None"}
+```
+
+The Summary section is generated by the planner agent at plan creation time. It is a denormalized view of plan metadata -- if the plan is revised, the Summary must also be updated.
+
+---
+
+## Task Types
+
+### Standard Auto Task
+
+```xml
+<task id="02-01-T1" type="auto" complexity="medium">
+  <name>Create Discord OAuth client module</name>
+  <files>
+    src/auth/discord.ts
+    src/auth/types.ts
+  </files>
+  <action>
+    1. Create file `src/auth/types.ts`
+       - Export interface `DiscordUser` with fields: id, username, avatar, email
+       - Export interface `AuthTokens` with fields: accessToken, refreshToken, expiresAt
+
+    2. Create file `src/auth/discord.ts`
+       - Import `OAuth2Client` from `discord-oauth2`
+       - Import `DiscordUser`, `AuthTokens` from `./types`
+       - Export async function `authenticateWithDiscord(code: string): Promise<DiscordUser>`
+         - Create OAuth2Client with DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET from env
+         - Exchange authorization code for access token
+         - Fetch user profile: GET /api/users/@me
+         - Return DiscordUser object
+       - Export function `getDiscordAuthUrl(): string`
+         - Build OAuth2 URL with scopes: identify, email
+         - Include DISCORD_REDIRECT_URI from env
+
+    3. Add to `.env.example`:
+       DISCORD_CLIENT_ID=
+       DISCORD_CLIENT_SECRET=
+       DISCORD_REDIRECT_URI=http://localhost:3000/auth/callback
+  </action>
+  <verify>
+    <automated>
+      npx tsc --noEmit
+      ls src/auth/discord.ts
+      ls src/auth/types.ts
+    </automated>
+  </verify>
+  <done>Discord OAuth client module exists and compiles without errors</done>
+</task>
+```
+
+> **Verify block forms**: The `<automated>` wrapper (Option A) is preferred — it enables machine-parsing
+> for `auto_checkpoints` mode. Plain-text verify commands without the wrapper (Option B) remain valid
+> for backward compatibility. Both forms are supported by the executor.
+
+### TDD Task
+
+```xml
+<task id="02-01-T2" type="auto" tdd="true" complexity="medium">
+  <name>Implement auth middleware with TDD</name>
+  <files>
+    src/middleware/auth.ts
+    tests/middleware/auth.test.ts
+  </files>
+  <action>
+    RED:
+    1. Create `tests/middleware/auth.test.ts`
+       - Test: "rejects request without token" — expect 401
+       - Test: "rejects request with invalid token" — expect 401
+       - Test: "passes request with valid token" — expect next() called
+
+    GREEN:
+    2. Create `src/middleware/auth.ts`
+       - Export function `requireAuth(req, res, next)`
+       - Extract JWT from httpOnly cookie
+       - Verify token with jsonwebtoken
+       - If valid: attach user to req, call next()
+       - If invalid: respond 401
+
+    REFACTOR:
+    3. Extract token verification into `verifyToken()` helper
+  </action>
+  <verify>
+    npm test -- --grep "auth middleware"
+  </verify>
+  <done>Auth middleware rejects invalid tokens and passes valid tokens</done>
+</task>
+```
+
+### Feature Task (TDD Variant)
+
+Feature tasks add a `<feature>` element for structured TDD planning. The element contains two required children:
+
+- **`<behavior>`** — the observable outcome from the user's perspective. Maps directly to a `must_haves.truths` entry.
+- **`<implementation>`** — the technical approach at a high level (which files, patterns, or algorithms to use).
+
+Prose structure (illustrative — not a live task block to avoid validator false-positives):
+
+```
+task id="02-01-T3" type="auto" tdd="true" complexity="medium"
+  name: Implement rate limiter for OAuth endpoint
+  files: src/middleware/rate-limit.ts / tests/middleware/rate-limit.test.ts
+  feature:
+    behavior: OAuth endpoint rejects more than 5 requests per minute per IP with HTTP 429
+    implementation: Token-bucket algorithm; Redis-backed counter with TTL; express-rate-limit wrapper
+  action:
+    RED: Write failing tests for 429 response at >5 req/min
+    GREEN: Implement token-bucket middleware using Redis
+    REFACTOR: Extract counter logic to RateLimitStore class
+  verify:
+    automated: npm test -- --grep "rate limiter"
+  done: Rate limiter rejects excessive OAuth requests with 429
+```
+
+The `<feature>` element is optional — standard TDD tasks without it are still valid. Use `<feature>` when the planner wants to record the behavior/implementation split explicitly for traceability.
+
+### Checkpoint: Human Verify
+
+```xml
+<task id="03-02-T3" type="checkpoint:human-verify">
+  <name>Verify OAuth callback flow</name>
+  <files>
+    src/pages/auth/callback.ts
+  </files>
+  <action>
+    1. Create the OAuth callback page at `src/pages/auth/callback.ts`
+    2. Wire it to call `authenticateWithDiscord()` with the authorization code
+    3. On success: set JWT cookie and redirect to dashboard
+    4. On failure: redirect to login with error message
+  </action>
+  <verify>
+    what-built: OAuth callback page that exchanges Discord auth code for JWT
+    how-to-verify: |
+      1. Click "Login with Discord" button
+      2. Authorize the application in Discord
+      3. Verify you are redirected to the dashboard
+      4. Check browser cookies for JWT token
+    resume-signal: "User confirms OAuth flow works end-to-end"
+  </verify>
+  <done>User can complete full Discord OAuth login flow</done>
+</task>
+```
+
+### Checkpoint: Decision
+
+```xml
+<task id="04-01-T1" type="checkpoint:decision">
+  <name>Choose database migration strategy</name>
+  <files></files>
+  <action>
+    Present the user with the migration strategy options after research.
+  </action>
+  <verify>
+    decision: "Which migration strategy to use for production database?"
+    context: "We need to decide how to handle schema changes in production."
+    options: |
+      A) Prisma Migrate — automatic migrations, good for development, requires care in production
+      B) Manual SQL — full control, more work, explicit about what changes
+      C) TypeORM migrations — auto-generated from entities, reversible
+    resume-signal: "User selects option A, B, or C"
+  </verify>
+  <done>Database migration strategy decided and documented in CONTEXT.md</done>
+</task>
+```
+
+### Checkpoint: Human Action
+
+```xml
+<task id="05-03-T2" type="checkpoint:human-action">
+  <name>Configure production environment</name>
+  <files>
+    .env.production
+  </files>
+  <action>
+    1. Create `.env.production.example` with all required variables listed
+    2. Document each variable's purpose in comments
+  </action>
+  <verify>
+    what-needed: "Production environment variables must be set"
+    how-to-do: |
+      1. Copy `.env.production.example` to `.env.production`
+      2. Fill in production values for:
+         - DATABASE_URL (production database connection string)
+         - DISCORD_CLIENT_ID (production Discord app)
+         - DISCORD_CLIENT_SECRET (production Discord app)
+         - JWT_SECRET (generate with: openssl rand -base64 32)
+    resume-signal: "User confirms .env.production is configured"
+  </verify>
+  <done>Production environment is configured with real credentials</done>
+</task>
+```
+
+---
+
+## The 5 Mandatory Elements
+
+Every task MUST have ALL 5. No exceptions.
+
+| Element | Purpose | Rules |
+|---------|---------|-------|
+| `<name>` | What the task does | Imperative verb phrase. Short. |
+| `<files>` | Files touched | One per line. Actual file paths. |
+| `<action>` | How to do it | Numbered steps. Specific. Code snippets for complex work. |
+| `<verify>` | How to check | Executable shell commands (plain-text or wrapped in `<automated>`). Or checkpoint format. |
+| `<done>` | How to know it worked | Observable user/system behavior. Maps to a must-have. |
+
+> **Optional `<feature>` element**: Feature tasks (TDD variant) may add a `<feature>` element with
+> `<behavior>` and `<implementation>` children for structured TDD planning. The 5 standard elements
+> above are still required.
+
+---
+
+## Task ID Format
+
+```
+{plan_id}-T{sequential_number}
+
+Examples:
+  02-01-T1  — Phase 02, Plan 01, Task 1
+  02-01-T2  — Phase 02, Plan 01, Task 2
+  03-02-T1  — Phase 03, Plan 02, Task 1
+```
+
+Task IDs are unique within a phase. They are used for:
+- Commit message references
+- Checkpoint continuation references
+- SUMMARY.md task result tracking

package/plan-build-run/references/planning-config.md

@@ -0,0 +1,200 @@
+<planning_config>
+
+Configuration options for `.planning/` directory behavior.
+
+<config_schema>
+```json
+"planning": {
+  "commit_docs": true,
+  "search_gitignored": false
+},
+"git": {
+  "branching_strategy": "none",
+  "phase_branch_template": "pbr/phase-{phase}-{slug}",
+  "milestone_branch_template": "pbr/{milestone}-{slug}"
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `commit_docs` | `true` | Whether to commit planning artifacts to git |
+| `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
+| `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
+| `git.phase_branch_template` | `"pbr/phase-{phase}-{slug}"` | Branch template for phase strategy |
+| `git.milestone_branch_template` | `"pbr/{milestone}-{slug}"` | Branch template for milestone strategy |
+</config_schema>
+
+<commit_docs_behavior>
+
+**When `commit_docs: true` (default):**
+- Planning files committed normally
+- SUMMARY.md, STATE.md, ROADMAP.md tracked in git
+- Full history of planning decisions preserved
+
+**When `commit_docs: false`:**
+- Skip all `git add`/`git commit` for `.planning/` files
+- User must add `.planning/` to `.gitignore`
+- Useful for: OSS contributions, client projects, keeping planning private
+
+**Using pbr-tools.cjs (preferred):**
+
+```bash
+# Commit with automatic commit_docs + gitignore checks:
+node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" commit "docs: update state" --files .planning/STATE.md
+
+# Load config via state load (returns JSON):
+INIT=$(node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# commit_docs is available in the JSON output
+
+# Or use init commands which include commit_docs:
+INIT=$(node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" init execute-phase "1")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# commit_docs is included in all init command outputs
+```
+
+**Auto-detection:** If `.planning/` is gitignored, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors when users have `.planning/` in `.gitignore`.
+
+**Commit via CLI (handles checks automatically):**
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" commit "docs: update state" --files .planning/STATE.md
+```
+
+The CLI checks `commit_docs` config and gitignore status internally — no manual conditionals needed.
+
+</commit_docs_behavior>
+
+<search_behavior>
+
+**When `search_gitignored: false` (default):**
+- Standard rg behavior (respects .gitignore)
+- Direct path searches work: `rg "pattern" .planning/` finds files
+- Broad searches skip gitignored: `rg "pattern"` skips `.planning/`
+
+**When `search_gitignored: true`:**
+- Add `--no-ignore` to broad rg searches that should include `.planning/`
+- Only needed when searching entire repo and expecting `.planning/` matches
+
+**Note:** Most PBR operations use direct file reads or explicit paths, which work regardless of gitignore status.
+
+</search_behavior>
+
+<setup_uncommitted_mode>
+
+To use uncommitted mode:
+
+1. **Set config:**
+   ```json
+   "planning": {
+     "commit_docs": false,
+     "search_gitignored": true
+   }
+   ```
+
+2. **Add to .gitignore:**
+   ```
+   .planning/
+   ```
+
+3. **Existing tracked files:** If `.planning/` was previously tracked:
+   ```bash
+   git rm -r --cached .planning/
+   git commit -m "chore: stop tracking planning docs"
+   ```
+
+4. **Branch merges:** When using `branching_strategy: phase` or `milestone`, the `complete-milestone` workflow automatically strips `.planning/` files from staging before merge commits when `commit_docs: false`.
+
+</setup_uncommitted_mode>
+
+<branching_strategy_behavior>
+
+**Branching Strategies:**
+
+| Strategy | When branch created | Branch scope | Merge point |
+|----------|---------------------|--------------|-------------|
+| `none` | Never | N/A | N/A |
+| `phase` | At `execute-phase` start | Single phase | User merges after phase |
+| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `complete-milestone` |
+
+**When `git.branching_strategy: "none"` (default):**
+- All work commits to current branch
+- Standard PBR behavior
+
+**When `git.branching_strategy: "phase"`:**
+- `execute-phase` creates/switches to a branch before execution
+- Branch name from `phase_branch_template` (e.g., `pbr/phase-03-authentication`)
+- All plan commits go to that branch
+- User merges branches manually after phase completion
+- `complete-milestone` offers to merge all phase branches
+
+**When `git.branching_strategy: "milestone"`:**
+- First `execute-phase` of milestone creates the milestone branch
+- Branch name from `milestone_branch_template` (e.g., `pbr/v1.0-mvp`)
+- All phases in milestone commit to same branch
+- `complete-milestone` offers to merge milestone branch to main
+
+**Template variables:**
+
+| Variable | Available in | Description |
+|----------|--------------|-------------|
+| `{phase}` | phase_branch_template | Zero-padded phase number (e.g., "03") |
+| `{slug}` | Both | Lowercase, hyphenated name |
+| `{milestone}` | milestone_branch_template | Milestone version (e.g., "v1.0") |
+
+**Checking the config:**
+
+Use `init execute-phase` which returns all config as JSON:
+```bash
+INIT=$(node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" init execute-phase "1")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# JSON output includes: branching_strategy, phase_branch_template, milestone_branch_template
+```
+
+Or use `state load` for the config values:
+```bash
+INIT=$(node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# Parse branching_strategy, phase_branch_template, milestone_branch_template from JSON
+```
+
+**Branch creation:**
+
+```bash
+# For phase strategy
+if [ "$BRANCHING_STRATEGY" = "phase" ]; then
+  PHASE_SLUG=$(echo "$PHASE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g")
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+
+# For milestone strategy
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+```
+
+**Merge options at complete-milestone:**
+
+| Option | Git command | Result |
+|--------|-------------|--------|
+| Squash merge (recommended) | `git merge --squash` | Single clean commit per branch |
+| Merge with history | `git merge --no-ff` | Preserves all individual commits |
+| Delete without merging | `git branch -D` | Discard branch work |
+| Keep branches | (none) | Manual handling later |
+
+Squash merge is recommended — keeps main branch history clean while preserving the full development history in the branch (until deleted).
+
+**Use cases:**
+
+| Strategy | Best for |
+|----------|----------|
+| `none` | Solo development, simple projects |
+| `phase` | Code review per phase, granular rollback, team collaboration |
+| `milestone` | Release branches, staging environments, PR per version |
+
+</branching_strategy_behavior>
+
+</planning_config>