@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/pbr/references/archive/pbr-tools-cli.md

@@ -0,0 +1,415 @@
+# pbr-tools.js CLI Reference
+
+Command-line interface for structured JSON operations on `.planning/` state.
+Skills and agents call this via Bash to avoid token-expensive text parsing.
+
+```
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js <command> [args]
+```
+
+All commands output JSON to stdout. Errors output JSON with an `error` field to stderr (exit code 1).
+
+---
+
+## State Commands
+
+### `state load`
+
+Returns full project state as a single JSON object.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load
+```
+
+**Output:**
+```json
+{
+  "exists": true,
+  "config": { ... },        // config.json contents
+  "state": {                 // STATE.md frontmatter + parsed body
+    "version": 2,
+    "current_phase": "1",
+    "status": "building",
+    "progress_percent": 45,
+    "last_activity": "2025-01-15",
+    "last_command": "/pbr:execute-phase",
+    "blockers": []
+  },
+  "roadmap": {               // Parsed ROADMAP.md
+    "phases": [{ "number": "01", "name": "...", "status": "planned", ... }]
+  },
+  "phase_count": 3,
+  "current_phase": "1",
+  "progress": { "phases": [...], "total_plans": 5, "completed_plans": 2, "percentage": 40 }
+}
+```
+
+### `state check-progress`
+
+Recalculates progress from filesystem (plan files, summaries, verification).
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state check-progress
+```
+
+**Output:**
+```json
+{
+  "phases": [
+    { "directory": "01-setup", "plans": 2, "summaries": 2, "completed": 2, "has_verification": true, "status": "verified" }
+  ],
+  "total_plans": 5,
+  "completed_plans": 3,
+  "percentage": 60
+}
+```
+
+### `state update <field> <value>`
+
+Atomically updates a single field in STATE.md. Uses file locking.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update current_phase 2
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update status building
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update last_activity now   # auto-timestamps
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update plans_complete 3
+```
+
+**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`
+
+**Output:** `{ "success": true, "field": "status", "value": "building" }`
+
+---
+
+## Config Commands
+
+### `config validate`
+
+Validates `config.json` against the JSON schema. Detects both schema violations and semantic conflicts.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config validate
+```
+
+**Output:**
+```json
+{
+  "valid": true,
+  "errors": [],
+  "warnings": ["features.auto_continue=true with mode=interactive: auto_continue only fires in autonomous mode"]
+}
+```
+
+### `config resolve-depth [dir]`
+
+Resolves the effective depth profile by merging base profile with user overrides.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth /path/to/.planning
+```
+
+**Output:** Full depth profile object with all resolved values (research rounds, plan detail level, verification depth, etc.)
+
+---
+
+## Plan & Phase Commands
+
+### `plan-index <phase>`
+
+Returns plan inventory for a phase, grouped by wave.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js plan-index 1
+```
+
+**Output:**
+```json
+{
+  "phase": "01-setup",
+  "total_plans": 3,
+  "plans": [
+    {
+      "file": "PLAN-01.md",
+      "plan_id": "01",
+      "wave": 1,
+      "type": "feature",
+      "autonomous": true,
+      "depends_on": [],
+      "gap_closure": false,
+      "has_summary": true,
+      "must_haves_count": 4
+    }
+  ],
+  "waves": { "wave_1": ["01", "02"], "wave_2": ["03"] }
+}
+```
+
+### `phase-info <phase>`
+
+Comprehensive single-phase status combining roadmap, filesystem, and plan data.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js phase-info 1
+```
+
+**Output:**
+```json
+{
+  "phase": "01-setup",
+  "name": "setup",
+  "goal": "Initialize project infrastructure",
+  "roadmap_status": "building",
+  "filesystem_status": "partial",
+  "plans": [...],
+  "plan_count": 3,
+  "summaries": [{ "file": "SUMMARY-01.md", "plan": "01", "status": "complete" }],
+  "completed": 1,
+  "verification": null,
+  "has_context": false
+}
+```
+
+### `must-haves <phase>`
+
+Collects all must-haves from phase plans — truths, artifacts, and key links.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js must-haves 1
+```
+
+**Output:**
+```json
+{
+  "phase": "01-setup",
+  "plans": {
+    "01": { "truths": ["..."], "artifacts": ["..."], "key_links": ["..."] }
+  },
+  "all": { "truths": [...], "artifacts": [...], "key_links": [...] },
+  "total": 12
+}
+```
+
+---
+
+## Frontmatter Command
+
+### `frontmatter <filepath>`
+
+Parses a markdown file's YAML frontmatter and returns as JSON.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js frontmatter .planning/phases/01-setup/PLAN-01.md
+```
+
+**Output:** The frontmatter fields as a JSON object. Returns `{ "error": "File not found: ..." }` if the file doesn't exist.
+
+---
+
+## Roadmap Commands
+
+### `roadmap update-status <phase> <status>`
+
+Updates the Status column for a phase in ROADMAP.md's Phase Overview table. Uses file locking. Warns on invalid status transitions but does not block them.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js roadmap update-status 1 building
+```
+
+**Valid statuses:** `pending`, `planned`, `building`, `built`, `partial`, `needs_fixes`, `verified`, `skipped`
+
+**Output:** `{ "success": true, "old_status": "planned", "new_status": "building" }`
+
+### `roadmap update-plans <phase> <complete> <total>`
+
+Updates the Plans column (e.g., "2/5") for a phase in ROADMAP.md.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js roadmap update-plans 1 2 5
+```
+
+**Output:** `{ "success": true, "old_plans": "1/5", "new_plans": "2/5" }`
+
+### Roadmap Format Notes
+
+**Phase sections** in ROADMAP.md include these fields (parsed by the dashboard and plan skill):
+- `**Goal:**` — phase objective
+- `**Requirements:**` — mapped REQ-IDs (e.g., `REQ-F-001, REQ-F-002`)
+- `**Success Criteria:**` — verifiable conditions for phase completion
+- `**Provides:**` — exported capabilities (bulleted list)
+- `**Depends on:**` — prerequisite phases
+- `**Implements:**` — REQ-IDs implemented
+
+**Milestone collapse format** (created by `/pbr:milestone complete`):
+- **New format:** `<details><summary>## Milestone: {name} ({version}) — SHIPPED {date}</summary>` wrapping phase table and archive link
+- **Legacy format:** `## Milestone: {name} ({version}) -- COMPLETED` (still recognized for backward compat)
+- **Milestone index:** `## Milestones` section near top of ROADMAP.md with version/name/status/date table
+
+---
+
+## History Commands
+
+### `history append <type> <title> [body]`
+
+Appends a record to HISTORY.md. Creates the file if it doesn't exist.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append milestone "v1.0 Release" "Initial release with core features"
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append phase "01-setup Complete" "3 plans executed, all verified"
+```
+
+**Types:** `milestone`, `phase`
+
+**Output:** `{ "success": true }`
+
+### `history load`
+
+Loads all HISTORY.md records as structured JSON.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history load
+```
+
+**Output:**
+```json
+{
+  "records": [
+    { "type": "milestone", "title": "v1.0 Release", "date": "2025-01-15", "body": "..." }
+  ],
+  "line_count": 42
+}
+```
+
+Returns `null` if HISTORY.md doesn't exist.
+
+---
+
+## Event Command
+
+### `event <category> <event> [JSON-details]`
+
+Logs a structured event to `.planning/logs/events.jsonl`.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event build plan-complete '{"plan":"01","phase":"01-setup"}'
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event error hook-failure '{"script":"validate-task.js"}'
+```
+
+**Output:** `{ "logged": true, "category": "build", "event": "plan-complete" }`
+
+If the JSON-details argument is not valid JSON, it's stored as `{ "raw": "<the string>" }`.
+
+---
+
+## Compound Init Commands
+
+Compound commands that compose multiple data sources into a single JSON response.
+Replace multi-step context loading in skills with a single CLI call.
+
+### `init execute-phase <phase>`
+
+Everything an executor needs to start building a phase.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init execute-phase 3
+```
+
+**Output:**
+```json
+{
+  "executor_model": "sonnet",
+  "verifier_model": "sonnet",
+  "config": { "depth": "standard", "mode": "interactive", "parallelization": {}, "planning": {}, "gates": {}, "features": {} },
+  "phase": { "num": "3", "dir": "03-auth", "name": "auth", "goal": "...", "has_context": false, "status": "planned", "plan_count": 2, "completed": 0 },
+  "plans": [{ "file": "PLAN-01.md", "plan_id": "01", "wave": 1, "autonomous": true, "has_summary": false, "must_haves_count": 4, "depends_on": [] }],
+  "waves": { "wave_1": ["01", "02"] },
+  "branch_name": "main",
+  "git_clean": true
+}
+```
+
+### `init plan-phase <phase>`
+
+Everything a planner needs to start phase planning.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init plan-phase 3
+```
+
+**Output:** `researcher_model`, `planner_model`, `checker_model`, `config` (depth profile, features, planning settings), `phase` (num, dir, goal, depends_on), `existing_artifacts`, `workflow` flags.
+
+### `init quick <description>`
+
+Everything the quick skill needs: next task number, slug, directory path.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init quick "add search feature"
+```
+
+**Output:** `next_task_number`, `slug`, `dir`, `dir_name`, `timestamp`, `config` subset.
+
+### `init verify-work <phase>`
+
+Everything a verifier needs to start verification.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init verify-work 3
+```
+
+**Output:** `verifier_model`, `phase` info, `has_verification`, `prior_attempts`, `prior_status`, `summaries`.
+
+### `init resume`
+
+Detect interrupted state and suggest continuation.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init resume
+```
+
+**Output:** `state`, `auto_next`, `continue_here`, `active_skill`, `current_phase`, `progress`.
+
+### `init progress`
+
+All phases with status and completion data.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init progress
+```
+
+**Output:** `current_phase`, `phase_count`, `status`, `phases` array, `total_plans`, `completed_plans`, `percentage`.
+
+---
+
+## State Mutation Extensions
+
+### `state patch <JSON>`
+
+Multi-field atomic STATE.md update. Updates all fields in a single pass.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state patch '{"status":"executing","last_activity":"now"}'
+```
+
+**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`, `progress_percent`, `phase_slug`, `last_command`, `blockers`
+
+**Output:** `{ "success": true, "updated": ["status", "last_activity"] }`
+
+### `state advance-plan`
+
+Increment current plan number in STATE.md and update progress percentage.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state advance-plan
+```
+
+**Output:** `{ "success": true, "previous_plan": 1, "current_plan": 2, "total_plans": 5, "progress_percent": 40 }`
+
+### `state record-metric [--duration Nm] [--plans-completed N]`
+
+Record session/execution metrics. Appends to HISTORY.md and updates last_activity.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state record-metric --duration 15m --plans-completed 3
+```
+
+**Output:** `{ "success": true, "duration_minutes": 15, "plans_completed": 3 }`

package/plugins/pbr/references/archive/pretooluse-jsonl-behavior.md

@@ -0,0 +1,58 @@
+---
+description: Documents why PreToolUse hook decisions appear in PBR hook logs but not Claude Code session JSONL
+---
+
+# PreToolUse JSONL Behavior
+
+## Behavior
+
+PreToolUse hooks log decisions to PBR's hook logs but **NOT** to Claude Code's session JSONL.
+
+- **PBR hook logs**: `.planning/logs/hooks-YYYY-MM-DD.jsonl` — contains all PreToolUse decisions (allow, block, warn)
+- **Session JSONL**: `~/.claude/projects/{path}/*.jsonl` — does NOT contain PreToolUse hook decisions
+
+## Why
+
+Claude Code session JSONL records conversations, tool calls, and tool results. PreToolUse hooks are middleware that runs *before* the tool executes:
+
+- If the hook **allows** the tool: the tool runs and its result appears in session JSONL normally
+- If the hook **blocks** the tool: the tool never executes, so there is no tool result to record
+
+In either case, the hook's own decision is not surfaced as a separate entry in session JSONL. This is by-design behavior in Claude Code's hook architecture.
+
+## Where to Find PreToolUse Logs
+
+Filter PBR hook logs for PreToolUse events:
+
+```bash
+grep '"event":"PreToolUse"' .planning/logs/hooks-$(date +%Y-%m-%d).jsonl
+```
+
+Each entry includes:
+
+- `hook`: the hook script name (e.g., `validate-task`)
+- `event`: `PreToolUse`
+- `decision`: `allow`, `block`, or `warn`
+- `source`: the originating hook script
+- `details`: tool name, input parameters, block reason (if blocked)
+
+## Hook Scripts That Log PreToolUse Events
+
+| Script | Purpose |
+|--------|---------|
+| `validate-commit.js` | Validates commit message format |
+| `validate-task.js` | Gates executor/planner/verifier spawns |
+| `check-dangerous-commands.js` | Blocks destructive shell commands |
+| `check-doc-sprawl.js` | Blocks excessive documentation creation |
+| `check-skill-workflow.js` | Enforces skill workflow ordering |
+| `check-summary-gate.js` | Validates SUMMARY.md before state updates |
+| `pre-bash-dispatch.js` | Dispatch for Bash PreToolUse checks |
+| `pre-write-dispatch.js` | Dispatch for Write/Edit PreToolUse checks |
+| `block-skill-self-read.js` | Prevents skills from reading their own SKILL.md |
+| `enforce-pbr-workflow.js` | Advisory PBR workflow compliance |
+| `intercept-plan-mode.js` | Intercepts plan mode entry |
+| `validate-skill-args.js` | Validates skill argument format |
+
+## Audit Implications
+
+The `/pbr:audit` agent must check PBR hook logs (`.planning/logs/hooks-*.jsonl`), not session JSONL, for PreToolUse evidence. Session JSONL cannot confirm whether PreToolUse hooks fired or what decisions they made.

package/plugins/pbr/references/archive/signal-files.md

@@ -0,0 +1,41 @@
+# Signal Files Reference
+
+Signal files are ephemeral files in `.planning/` that coordinate state between hook scripts
+and skills. They are scoped to either the current session or the current phase/plan.
+
+## Session-Scoped Files
+
+All 5 session signals are consolidated in `.planning/.session.json`. Scripts must read and write
+`.session.json` via `pbr-tools session get|set|clear` — never read the raw `.session.json` file directly.
+The `.session.json` schema is an object with the keys documented below.
+
+| JSON Key | Former File | Written By | Read By | Semantics |
+|----------|-------------|------------|---------|-----------|
+| `activeSkill` | `.active-skill` | Skills (Write tool) | check-skill-workflow, enforce-pbr-workflow, check-subagent-output, log-subagent, block-skill-self-read | Which skill is active. Written at skill start, cleared at skill end (session-cleanup). |
+| `compactCounter` | `.compact-counter` | suggest-compact.js | suggest-compact.js | Write count since last /compact. Resets on SessionStart. |
+| `sessionStart` | `.session-start` | progress-tracker.js | local-llm metrics | ISO timestamp of session start. Used for LLM metrics correlation. |
+| `activeOperation` | `.active-operation` | context-budget-check.js | context-budget-check.js | Current named operation for budget display. |
+| `activePlan` | `.active-plan` | context-budget-check.js | context-budget-check.js | Current plan ID for budget display. |
+
+**Atomic access**: Use `pbr-tools session get|set|clear` for safe reads/writes from hook scripts.
+
+**Lifecycle**: Written during SessionStart (progress-tracker), cleared during SessionEnd (session-cleanup).
+Stale sessions (> 60 min) are auto-cleaned by progress-tracker.js on next SessionStart.
+
+## One-Shot Files
+
+These files are NOT consolidated — they use write-once, delete-on-read semantics.
+
+| File | Written By | Read By | Semantics |
+|------|------------|---------|-----------|
+| `.planning/.auto-next` | auto-continue.js | auto-continue.js (Stop hook) | Next command to run after session stops. Deleted after read. |
+| `.planning/.auto-verify` | event-handler.js | event-handler.js (SubagentStop hook) | Trigger auto-verification after agent completes. Deleted after read. |
+
+## Phase-Scoped Files
+
+These files persist across sessions, scoped to a specific phase or plan.
+
+| File Pattern | Written By | Read By | Semantics |
+|-------------|------------|---------|-----------|
+| `.planning/phases/{id}/.checkpoint-manifest.json` | build skill | validate-task.js, session-cleanup.js | Checkpoint state for a plan in progress. Cleaned up after 24h. |
+| `.planning/phases/{id}/.PROGRESS-{taskId}` | executor agent | validate-task.js | Task progress marker for crash recovery. Orphaned files warn on SessionStart. |