@sienklogic/plan-build-run 2.11.0 → 2.12.1

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

@@ -0,0 +1,249 @@
+# Continuation Format
+
+Standard format for presenting next steps after completing a command or workflow.
+
+## Core Structure
+
+```
+---
+
+## ▶ Next Up
+
+**{identifier}: {name}** — {one-line description}
+
+`{command to copy-paste}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `{alternative option 1}` — description
+- `{alternative option 2}` — description
+
+---
+```
+
+## Format Rules
+
+1. **Always show what it is** — name + description, never just a command path
+2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
+3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
+4. **`/clear` explanation** — always include, keeps it concise but explains why
+5. **"Also available" not "Other options"** — sounds more app-like
+6. **Visual separators** — `---` above and below to make it stand out
+
+## Variants
+
+### Execute Next Plan
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+
+`/pbr:execute-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review plan before executing
+- `/pbr:list-phase-assumptions 2` — check assumptions
+
+---
+```
+
+### Execute Final Plan in Phase
+
+Add note that this is the last plan and what comes after:
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+<sub>Final plan in Phase 2</sub>
+
+`/pbr:execute-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**After this completes:**
+- Phase 2 → Phase 3 transition
+- Next: **Phase 3: Core Features** — User dashboard and settings
+
+---
+```
+
+### Plan a Phase
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 2: Authentication** — JWT login flow with refresh tokens
+
+`/pbr:plan-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/pbr:discuss-phase 2` — gather context first
+- `/pbr:research-phase 2` — investigate unknowns
+- Review roadmap
+
+---
+```
+
+### Phase Complete, Ready for Next
+
+Show completion status before next action:
+
+```
+---
+
+## ✓ Phase 2 Complete
+
+3/3 plans executed
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+`/pbr:plan-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/pbr:discuss-phase 3` — gather context first
+- `/pbr:research-phase 3` — investigate unknowns
+- Review what Phase 2 built
+
+---
+```
+
+### Multiple Equal Options
+
+When there's no clear primary action:
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+**To plan directly:** `/pbr:plan-phase 3`
+
+**To discuss context first:** `/pbr:discuss-phase 3`
+
+**To research unknowns:** `/pbr:research-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+### Milestone Complete
+
+```
+---
+
+## 🎉 Milestone v1.0 Complete
+
+All 4 phases shipped
+
+## ▶ Next Up
+
+**Start v1.1** — questioning → research → requirements → roadmap
+
+`/pbr:new-milestone`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+## Pulling Context
+
+### For phases (from ROADMAP.md):
+
+```markdown
+### Phase 2: Authentication
+**Goal**: JWT login flow with refresh tokens
+```
+
+Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
+
+### For plans (from ROADMAP.md):
+
+```markdown
+Plans:
+- [ ] 02-03: Add refresh token rotation
+```
+
+Or from PLAN.md `<objective>`:
+
+```xml
+<objective>
+Add refresh token rotation with sliding expiry window.
+
+Purpose: Extend session lifetime without compromising security.
+</objective>
+```
+
+Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry`
+
+## Anti-Patterns
+
+### Don't: Command-only (no context)
+
+```
+## To Continue
+
+Run `/clear`, then paste:
+/pbr:execute-phase 2
+```
+
+User has no idea what 02-03 is about.
+
+### Don't: Missing /clear explanation
+
+```
+`/pbr:plan-phase 3`
+
+Run /clear first.
+```
+
+Doesn't explain why. User might skip it.
+
+### Don't: "Other options" language
+
+```
+Other options:
+- Review roadmap
+```
+
+Sounds like an afterthought. Use "Also available:" instead.
+
+### Don't: Fenced code blocks for commands
+
+```
+```
+/pbr:plan-phase 3
+```
+```
+
+Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.

package/plan-build-run/references/debugging/CLAUDE.md

@@ -0,0 +1,7 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+*No recent activity*
+</claude-mem-context>

package/plan-build-run/references/decimal-phase-calculation.md

@@ -0,0 +1,65 @@
+# Decimal Phase Calculation
+
+Calculate the next decimal phase number for urgent insertions.
+
+## Using pbr-tools
+
+```bash
+# Get next decimal phase after phase 6
+node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" phase next-decimal 6
+```
+
+Output:
+```json
+{
+  "found": true,
+  "base_phase": "06",
+  "next": "06.1",
+  "existing": []
+}
+```
+
+With existing decimals:
+```json
+{
+  "found": true,
+  "base_phase": "06",
+  "next": "06.3",
+  "existing": ["06.1", "06.2"]
+}
+```
+
+## Extract Values
+
+```bash
+DECIMAL_INFO=$(node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" phase next-decimal "${AFTER_PHASE}")
+DECIMAL_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.next')
+BASE_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.base_phase')
+```
+
+Or with --raw flag:
+```bash
+DECIMAL_PHASE=$(node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" phase next-decimal "${AFTER_PHASE}" --raw)
+# Returns just: 06.1
+```
+
+## Examples
+
+| Existing Phases | Next Phase |
+|-----------------|------------|
+| 06 only | 06.1 |
+| 06, 06.1 | 06.2 |
+| 06, 06.1, 06.2 | 06.3 |
+| 06, 06.1, 06.3 (gap) | 06.4 |
+
+## Directory Naming
+
+Decimal phase directories use the full decimal number:
+
+```bash
+SLUG=$(node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" generate-slug "$DESCRIPTION" --raw)
+PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
+mkdir -p "$PHASE_DIR"
+```
+
+Example: `.planning/phases/06.1-fix-critical-auth-bug/`

package/plan-build-run/references/git-integration.md

@@ -0,0 +1,309 @@
+# Git Integration Reference
+
+Plan-Build-Run's commit conventions, commit points, branching strategy, and hook scripts.
+
+---
+
+## Commit Message Format
+
+```
+{type}({scope}): {description}
+```
+
+### Components
+
+| Part | Description | Example |
+|------|-------------|---------|
+| `{type}` | Conventional commit type | `feat`, `fix`, `chore` |
+| `{scope}` | Component name for the area of change | `hooks`, `skills`, `agents` |
+| `{description}` | Imperative, lowercase description | `add drift detection to state sync` |
+
+The format is configurable via `config.json` at `git.commit_format`. The default is `{type}({scope}): {description}`.
+
+### Component Scopes
+
+Use these scopes to indicate which part of PBR the change affects. git-cliff uses these to group changelog entries by component.
+
+| Scope | What It Covers | Example |
+|-------|---------------|---------|
+| `hooks` | Hook scripts in `hooks/` and `plugins/pbr/scripts/` | `feat(hooks): add drift detection to state sync` |
+| `skills` | SKILL.md files and skill logic | `feat(skills): add velocity metrics to status` |
+| `agents` | Agent definitions in `agents/` | `fix(agents): scale executor budget for 1M context` |
+| `cli` | `pbr-tools.cjs` and `bin/lib/` modules | `feat(cli): implement stateRederive command` |
+| `dashboard` | Dashboard UI and server | `fix(dashboard): handle missing phases in chart` |
+| `templates` | `.tmpl` template files | `feat(templates): add XML sections to CONTEXT.md` |
+| `plugin` | Plugin manifests, CLAUDE.md, commands | `chore(plugin): bump version to 2.9.0` |
+| `config` | Config schema, validation, defaults | `feat(config): add node_repair_budget setting` |
+| `ci` | GitHub Actions, lint, coverage | `fix(ci): lower branch coverage threshold` |
+| `tests` | Test files and fixtures | `test(tests): add resolve-root macOS symlink test` |
+| `refs` | Reference docs in `references/` | `docs(refs): document hook ordering expectations` |
+| `commands` | Command registration files | `feat(commands): add autonomous command` |
+
+### Full Example
+
+```
+feat(hooks): implement stateRederive with drift detection
+```
+
+---
+
+## Commit Types
+
+| Type | When to Use | Example |
+|------|------------|---------|
+| `feat` | New feature or functionality | `feat(skills): add velocity metrics to status` |
+| `fix` | Bug fix (including during execution) | `fix(hooks): resolve MSYS path bridging on Windows` |
+| `refactor` | Code restructuring, no behavior change | `refactor(cli): extract state mutations to lib/state.cjs` |
+| `test` | Adding or modifying tests | `test(hooks): add resolve-root tests for walk-up discovery` |
+| `docs` | Documentation changes | `docs(refs): document hook ordering expectations` |
+| `chore` | Build config, dependencies, tooling | `chore(plugin): bump version to 2.9.0` |
+| `wip` | Work in progress (use sparingly) | `wip(skills): partial checkpoint routing` |
+| `revert` | Reverting a previous commit | `revert(hooks): revert auto-continue signal file change` |
+| `perf` | Performance improvement | `perf(cli): cache resolveProjectRoot result` |
+| `ci` | CI/CD changes | `ci(ci): add markdownlint job to test workflow` |
+| `build` | Build system changes | `build(plugin): update hooks.json paths` |
+
+---
+
+## Commit Type Discipline
+
+| Type | Use For | Appears in Changelog |
+|------|---------|---------------------|
+| `feat` | User-visible features ONLY (new commands, new config options, changed behavior users notice) | YES |
+| `fix` | Bug fixes users would notice | YES |
+| `refactor` | Internal restructuring, TDD GREEN commits, code cleanup | No |
+| `test` | Test additions including TDD RED commits | No |
+| `docs` | Documentation (hidden — mostly planning artifacts) | No |
+| `chore` | Build config, deps, tooling, internal scaffolding | No |
+| `wip` | Work in progress (use sparingly) | No |
+| `revert` | Reverting a previous commit | YES |
+
+**TDD commits**: RED phase → `test({scope}): RED - ...`, GREEN phase → `refactor({scope}): GREEN - ...`, REFACTOR phase → `refactor({scope}): REFACTOR - ...`
+
+---
+
+## Special Commit Patterns
+
+Beyond component scopes, Plan-Build-Run recognizes these additional patterns:
+
+| Pattern | When Used | Example |
+|---------|-----------|---------|
+| `{type}(quick-{NNN})` | Quick-task commits via `/pbr:quick` | `feat(quick-001): add health endpoint` |
+| `docs(planning)` | Planning document commits | `docs(planning): add phase 3 plans` |
+| `wip: {desc}` or `wip({area}): {desc}` | Work-in-progress (use sparingly) | `wip(skills): partial checkpoint routing` |
+| Merge commits | Git merge operations | `Merge branch 'feature/auth-rework'` |
+
+---
+
+## Session Affinity Metadata
+
+When a session ID is available, append a `[session:{short_id}]` suffix to the commit description. The `short_id` is the first 8 characters of the session_id. This enables conflict tracing across concurrent sessions.
+
+Example:
+```
+feat(auth): implement discord oauth client [session:a1b2c3d4]
+```
+
+When no session ID is available (e.g., manual commits), omit the suffix.
+
+---
+
+## Commit Body (Optional)
+
+For commits that need explanation, add a body after a blank line:
+
+```
+feat(02-01): implement discord oauth client [session:a1b2c3d4]
+
+- Uses discord-oauth2 library for token exchange
+- Stores tokens in httpOnly cookies for security
+- Supports identify and email OAuth scopes
+
+Deviation: Added null check for user.email (Rule 3 -- critical gap)
+```
+
+---
+
+## Commit Points
+
+Plan-Build-Run defines strict rules about WHEN commits happen:
+
+### One Task = One Commit
+
+Each successfully completed plan task gets exactly one atomic commit. No more, no less.
+
+### TDD Tasks = Three Commits
+
+TDD tasks (`tdd="true"`) produce exactly 3 commits following Red-Green-Refactor:
+
+```
+test(auth): RED - add failing tests for auth middleware
+refactor(auth): GREEN - implement auth middleware to pass tests
+refactor(auth): REFACTOR - extract token verification helper
+```
+
+### Commit Preconditions
+
+A commit is created only when:
+1. All `<action>` steps in the task are complete
+2. All `<verify>` commands pass with exit code 0
+3. Only files listed in the task's `<files>` element are staged (plus deviation-required files)
+
+### Deviation Commits
+
+When an executor applies a deviation rule during a task, the deviation is included in the same task commit (not a separate commit):
+
+```
+# Rule 1 auto-fix: rolled into the task's commit
+# Rule 2 auto-install: package.json/lock added to same commit
+# Rule 3 critical gap: null check added in same commit
+```
+
+---
+
+## Atomic Commit Rules
+
+1. **One task = one commit** (TDD tasks get 3)
+2. **Commit only after verify passes** -- never commit broken code
+3. **Stage only files listed in `<files>`** plus any deviation-required files
+4. **Never use `git add .` or `git add -A`** -- stage specific files
+5. **Include all files from the task** -- do not leave modified files unstaged
+6. **Commit message must describe what was done** -- not just the task name
+7. **Use the configured commit format** -- from `config.json` `git.commit_format`
+
+---
+
+## Staging Examples
+
+```bash
+# Standard task
+git add src/auth/discord.ts src/auth/types.ts
+git commit -m "feat(auth): implement Discord OAuth client with token exchange"
+
+# Task that also installed a dependency (Rule 2)
+git add src/auth/discord.ts src/auth/types.ts package.json package-lock.json
+git commit -m "feat(auth): implement Discord OAuth client with token exchange"
+
+# TDD RED
+git add tests/auth/discord.test.ts
+git commit -m "test(auth): add failing tests for Discord OAuth flow"
+```
+
+---
+
+## Git Retry Logic
+
+If `git commit` fails with a lock error (`fatal: Unable to create ... .git/index.lock`):
+1. Wait 2 seconds
+2. Retry the commit
+3. Maximum 3 attempts
+4. If still failing after 3 attempts, report the error and stop
+
+This commonly occurs when parallel executors compete for the git index lock.
+
+---
+
+## Branching Strategy
+
+Configured via `config.json` at `git.branching`:
+
+| Strategy | Behavior |
+|----------|----------|
+| `none` | All commits go directly to the current branch (default) |
+| `phase` | Each phase gets its own branch: `plan-build-run/phase-{NN}-{slug}`. Squash-merged to main on completion. |
+| `milestone` | Each milestone gets a branch: `plan-build-run/{milestone}-{slug}`. Merged on milestone completion. |
+| `disabled` | No git operations at all. No commits, no branching. Useful for prototyping or non-git projects. |
+
+### Phase Branching Flow
+
+When `git.branching` is `phase`:
+1. Build orchestrator creates branch: `git checkout -b plan-build-run/phase-{NN}-{slug}`
+2. All executor commits go to the phase branch
+3. After all plans complete and verification passes, orchestrator asks user to confirm squash merge
+4. If confirmed: `git checkout main && git merge --squash plan-build-run/phase-{NN}-{slug}`
+5. Phase branch is deleted after merge
+
+Branch name templates are configured in `config.json`:
+- `git.phase_branch_template`: Default `plan-build-run/phase-{phase}-{slug}`
+- `git.milestone_branch_template`: Default `plan-build-run/{milestone}-{slug}`
+
+### PR Creation
+
+When `git.auto_pr: true` and `git.branching` is `phase` or `milestone`, the build skill creates a GitHub PR after verification passes:
+
+1. Push the phase branch to the remote
+2. Create a PR via `gh pr create` with structured title and body
+3. PR title follows the commit convention: `feat(phase-{N}): {phase slug}`
+4. PR body includes phase goal, key files changed, and must-have verification results
+
+When `git.auto_pr: false` (default), the build skill offers the user a choice after verification:
+- Create PR now
+- Skip PR creation
+- Push branch only (create PR later)
+
+PR creation requires `gh` CLI authenticated with repo write access.
+
+### CI Integration
+
+When `ci.gate_enabled: true`, the build skill checks GitHub Actions status after each wave completes:
+
+1. Run: `gh run list --branch $(git branch --show-current) --limit 1 --json status,conclusion,url`
+2. If `status == completed` and `conclusion == success`: proceed to next wave
+3. If `status == in_progress`: wait up to `ci.wait_timeout_seconds`, re-check
+4. If `conclusion != success` or timeout: surface warning with run URL and offer:
+   - **Wait**: continue polling
+   - **Continue anyway**: proceed despite CI failure (logged as deviation)
+   - **Abort**: stop the build
+
+CI gate requires `gh` CLI and GitHub Actions configured on the repository. The gate only activates when there are commits pushed to a remote branch (branching must be enabled).
+
+### Git Mode
+
+The `git.mode` field controls whether git integration is active:
+
+| Mode | Behavior |
+|------|----------|
+| `enabled` | Normal operation -- commits, branching, hooks all active (default) |
+| `disabled` | No git commands are run. No commits, no branching. Useful for non-git projects. |
+
+---
+
+## Hook Scripts
+
+Plan-Build-Run uses Claude Code hooks (defined in `hooks/hooks.json`) to enforce conventions and track progress during execution. All hooks log via `hook-logger.js` to `.planning/.hook-log` (JSONL format, max 200 entries).
+
+### Hook Summary
+
+| Hook Event | Script | Purpose |
+|------------|--------|---------|
+| `SessionStart` | `progress-tracker.js` | Displays current project progress on session start |
+| `PostToolUse` (Write/Edit) | `check-plan-format.js` | Validates plan file YAML frontmatter after writes |
+| `PostToolUse` (Write/Edit) | `check-roadmap-sync.js` | Ensures ROADMAP.md stays in sync with phase changes |
+| `PreToolUse` (Bash) | `validate-commit.js` | Validates commit message format before `git commit` runs |
+| `PreCompact` | `context-budget-check.js` | Warns about context budget before compaction |
+| `Stop` | `auto-continue.js` | Handles auto-continuation signal when session ends |
+| `SubagentStart` | `log-subagent.js start` | Logs subagent spawn events |
+| `SubagentStop` | `log-subagent.js stop` | Logs subagent completion events |
+| `SessionEnd` | `session-cleanup.js` | Cleans up temporary state on session end |
+
+### validate-commit.js Details
+
+The commit validation hook (`PreToolUse` on Bash commands) enforces the commit format:
+- Checks that `git commit -m "..."` messages match the pattern: `{type}({scope}): {description}`
+- Valid types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `wip`, `revert`
+- Allows merge commits (starting with "Merge")
+- Allows quick-task, planning, and WIP scope patterns
+- Blocks commits with sensitive file patterns (`.env`, `.key`, `.pem`, credentials) unless they match safe patterns (`.example`, `.template`, `.sample`, test directories)
+- Exit code 2 blocks the commit; exit code 0 allows it
+
+---
+
+## Planning Doc Commits
+
+When `config.json` has `planning.commit_docs: true`, the build orchestrator commits planning artifacts (SUMMARY.md, VERIFICATION.md) after all plans in a phase complete:
+
+```
+docs({phase}): add build summaries and verification
+```
+
+This keeps the planning trail in version control alongside the code it describes.

package/plan-build-run/references/git-planning-commit.md

@@ -0,0 +1,38 @@
+# Git Planning Commit
+
+Commit planning artifacts using the pbr-tools CLI, which automatically checks `commit_docs` config and gitignore status.
+
+## Commit via CLI
+
+Always use `pbr-tools.cjs commit` for `.planning/` files — it handles `commit_docs` and gitignore checks automatically:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
+```
+
+The CLI will return `skipped` (with reason) if `commit_docs` is `false` or `.planning/` is gitignored. No manual conditional checks needed.
+
+## Amend previous commit
+
+To fold `.planning/` file changes into the previous commit:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" commit "" --files .planning/codebase/*.md --amend
+```
+
+## Commit Message Patterns
+
+| Command | Scope | Example |
+|---------|-------|---------|
+| plan-phase | phase | `docs(phase-03): create authentication plans` |
+| execute-phase | phase | `docs(phase-03): complete authentication phase` |
+| new-milestone | milestone | `docs: start milestone v1.1` |
+| remove-phase | chore | `chore: remove phase 17 (dashboard)` |
+| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |
+| add-phase | phase | `docs: add phase 07 (settings page)` |
+
+## When to Skip
+
+- `commit_docs: false` in config
+- `.planning/` is gitignored
+- No changes to commit (check with `git status --porcelain .planning/`)

package/plan-build-run/references/model-profile-resolution.md

@@ -0,0 +1,34 @@
+# Model Profile Resolution
+
+Resolve model profile once at the start of orchestration, then use it for all Task spawns.
+
+## Resolution Pattern
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default: `balanced` if not set or config missing.
+
+## Lookup Table
+
+@~/.claude/plan-build-run/references/model-profiles.md
+
+Look up the agent in the table for the resolved profile. Pass the model parameter to Task calls:
+
+```
+Task(
+  prompt="...",
+  subagent_type="pbr-planner",
+  model="{resolved_model}"  # "inherit", "sonnet", or "haiku"
+)
+```
+
+**Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions.
+
+## Usage
+
+1. Resolve once at orchestration start
+2. Store the profile value
+3. Look up each agent's model from the table when spawning
+4. Pass model parameter to each Task call (values: `"inherit"`, `"sonnet"`, `"haiku"`)