@sienklogic/plan-build-run 2.9.1 → 2.11.0

package/plugins/pbr/references/agent-contracts.md

@@ -0,0 +1,297 @@
+# Agent Contracts
+
+Input/output schemas for agent-to-agent handoffs in Plan-Build-Run.
+
+Each contract defines: the file exchanged, required frontmatter fields, body structure, and special handling notes. Agents MUST produce output matching these schemas — consumers depend on them.
+
+---
+
+## Contract: Researcher -> Synthesizer
+
+**File**: `.planning/research/{topic-slug}.md` (project) or `.planning/phases/{NN}-{slug}/RESEARCH.md` (phase)
+**Direction**: Researcher writes, Synthesizer reads 2-4 of these
+
+### Required Frontmatter
+
+```yaml
+---
+confidence: high|medium|low
+sources_checked: N        # integer count of sources consulted
+coverage: "complete|partial|minimal"
+---
+```
+
+### Required Body Sections
+
+- `## Key Findings` — each finding tagged with source level (`[S1]`..`[S6]`) and confidence
+- `## Gaps` — areas not covered and why
+- `## Sources` — source list with what each provided
+
+### Special Handling
+
+- Every factual claim must have a source attribution tag
+- Version-sensitive info (API signatures, config syntax) must come from S1-S3 sources
+- `[SPECULATIVE]` tag marks unverified reasoning — synthesizer must not upgrade confidence
+
+---
+
+## Contract: Synthesizer -> Planner
+
+**File**: `.planning/research/SUMMARY.md` (or specified path)
+**Direction**: Synthesizer writes, Planner reads
+
+### Required Frontmatter
+
+```yaml
+---
+confidence: high|medium|low
+sources: N                # integer count of input documents
+conflicts: N              # integer count of contradictions found
+---
+```
+
+### Required Body Sections
+
+- `## Resolved Decisions` — table with Topic, Decision, Confidence, Sources columns
+- `## Open Questions` — items marked `[NEEDS DECISION]` for planner to handle
+- `## Deferred Ideas` — items out of scope
+
+### Special Handling
+
+- `[NEEDS DECISION]` flags: planner creates `checkpoint:decision` tasks OR decides within discretion scope
+- Confidence levels never upgraded beyond what input documents support
+- Contradictions always documented, never silently dropped
+
+---
+
+## Contract: Planner -> Executor
+
+**File**: `.planning/phases/{NN}-{slug}/PLAN-{NN}.md`
+**Direction**: Planner writes, Executor reads and executes sequentially
+
+### Required Frontmatter
+
+```yaml
+---
+phase: "{phase-slug}"
+plan: "{NN-MM}"
+wave: N
+depends_on: []
+files_modified: ["{path}"]
+must_haves:
+  truths: ["{observable condition}"]
+  artifacts: ["{file: description}"]
+  key_links: ["{connection description}"]
+provides: ["{exported item}"]
+consumes: ["{required item}"]
+requirement_ids: []
+---
+```
+
+### Required Body: XML Tasks (each task needs all 5 elements)
+
+```xml
+<task id="{plan}-T{n}" type="{type}" tdd="{bool}" complexity="{simple|medium|complex}">
+<name>{imperative verb phrase}</name>
+<files>{file paths, one per line}</files>
+<action>{numbered steps}</action>
+<verify>{executable shell command}</verify>
+<done>{observable outcome}</done>
+</task>
+```
+
+### Special Handling
+
+- Task types: `auto`, `tdd`, `checkpoint:human-verify`, `checkpoint:decision`, `checkpoint:human-action`
+- Complexity drives model selection: simple=haiku, medium=sonnet, complex=inherit
+- Executor stages ONLY files listed in `<files>` per task
+- Plans end with a `## Summary` section (plan ID, task list, key files, must-haves, provides/consumes)
+
+---
+
+## Contract: Planner -> Plan-Checker
+
+**File**: Same `PLAN-{NN}.md` files (read-only)
+**Direction**: Planner writes, Plan-Checker reads and returns text assessment
+**Returns**: Inline text report (no file output)
+
+### Expected Input
+
+Plan-Checker reads plan frontmatter + XML tasks and evaluates across 9 dimensions (D1-D9). Optionally receives CONTEXT.md path.
+
+### Output Format
+
+```
+VERIFICATION PASSED | ISSUES FOUND
+Plans: N | Tasks: N | Blockers: N | Warnings: N | Info: N
+
+## Blockers
+- [{plan_id}] D{N} {severity}: {description} -> Fix: {hint}
+```
+
+### Special Handling
+
+- Blockers must be fixed before execution; warnings are advisory
+- Plan-Checker never modifies plans — only reports issues
+- Planner enters Revision Mode to address feedback
+
+---
+
+## Contract: Executor -> Verifier
+
+**File**: `.planning/phases/{NN}-{slug}/SUMMARY-{plan_id}.md`
+**Direction**: Executor writes after completing plan tasks, Verifier reads
+
+### Required Frontmatter
+
+```yaml
+---
+plan: "{plan_id}"
+status: complete|partial|checkpoint
+commits: ["{sha1}", "{sha2}"]
+provides: ["{exported item}"]
+must_haves:
+  - "{must-have description}: DONE|PARTIAL|SKIPPED"
+---
+```
+
+### Required Body Sections
+
+- `## Task Results` — table with Task, Status, Notes columns
+- `## Deviations` — list of deviations from plan, or "None"
+
+### Special Handling
+
+- Verifier does NOT trust SUMMARY.md claims — verifies against actual codebase
+- Verifier checks must-haves from PLAN.md frontmatter, not SUMMARY.md self-reports
+- One SUMMARY per plan execution; status reflects final state
+
+---
+
+## Contract: Verifier -> Planner (Gap Closure)
+
+**File**: `.planning/phases/{NN}-{slug}/VERIFICATION.md`
+**Direction**: Verifier writes, Planner reads to create gap-closure plans
+
+### Required Frontmatter
+
+```yaml
+---
+status: passed|gaps_found|human_needed
+attempt: N
+must_haves_total: N
+must_haves_passed: M
+gaps: ["gap description"]
+overrides: []
+---
+```
+
+### Required Body Sections
+
+- `## Must-Have Verification` — table with #, Must-Have, Status, Evidence columns
+- `## Gaps` — per-gap detail with Evidence and Suggested fix
+
+### Special Handling
+
+- `gaps_found` triggers Planner Gap Closure Mode — planner creates targeted fix plans
+- `overrides` list: must-haves marked as override by user, counted as passed
+- Re-verification increments `attempt` counter; checks regressions on previously-passed items
+- Verifier has Write access ONLY for VERIFICATION.md — cannot fix source code
+
+---
+
+## Contract: Integration-Checker -> Planner
+
+**File**: `.planning/phases/{NN}-{slug}/INTEGRATION-REPORT.md`
+**Direction**: Integration-Checker writes, Planner reads for cross-phase fixes
+
+### Required Frontmatter
+
+```yaml
+---
+status: passed|issues_found
+checks_total: N
+checks_passed: M
+critical_issues: K
+---
+```
+
+### Required Body Sections
+
+- `## Integration Checks` — table with Check, Status, Evidence columns
+- `## E2E Flows` — table with Flow, Status, Broken Link columns
+- `## Critical Issues` — detailed issue descriptions
+
+### Special Handling
+
+- Checks ACROSS phases (unlike Verifier which checks single phase)
+- 5 check categories: Export/Import Wiring, API Route Coverage, Auth Protection, E2E Flows, Cross-Phase Dependencies
+- Integration-Checker has Write access ONLY for INTEGRATION-REPORT.md — cannot fix source code
+
+---
+
+## Contract: Debugger (Self-Contained)
+
+**File**: `.planning/debug/{slug}.md`
+**Direction**: Debugger creates, updates, and resolves within a single session
+
+### Required Frontmatter
+
+```yaml
+---
+slug: "{slug}"
+status: "gathering|investigating|fixing|verifying|resolved"
+created: "{ISO-8601}"
+updated: "{ISO-8601}"
+mode: "find_and_fix|find_root_cause_only"
+---
+```
+
+### Required Body Sections
+
+- `## Current Focus` — Hypothesis, Test, Expecting, Disconfirm, Next action
+- `## Symptoms` — IMMUTABLE after gathering phase
+- `## Hypotheses` — Active (unchecked) and Eliminated (checked, append-only)
+- `## Evidence Log` — append-only timestamped entries
+- `## Resolution` — root cause, mechanism, fix, commit hash (when resolved)
+
+### Special Handling
+
+- Status transitions: `gathering -> investigating -> fixing -> verifying -> resolved`
+- Symptoms and Evidence Log are append-only / immutable — prevents mutation bias
+- Fix commits use format: `fix({scope}): {description}` with root cause in body
+- May emit checkpoints (`HUMAN-VERIFY`, `HUMAN-ACTION`, `DECISION`) for user input
+
+---
+
+## Contract: Codebase-Mapper (Self-Contained)
+
+**Files**: `.planning/codebase/{STACK,ARCHITECTURE,CONVENTIONS,CONCERNS}.md` (varies by focus)
+**Direction**: Codebase-Mapper writes, consumed by Researcher (as S0 local prior) and Planner
+
+### Focus Areas and Outputs
+
+| Focus | Output Files |
+|-------|-------------|
+| `tech` | STACK.md, INTEGRATIONS.md |
+| `arch` | ARCHITECTURE.md, STRUCTURE.md |
+| `quality` | CONVENTIONS.md, TESTING.md |
+| `concerns` | CONCERNS.md |
+
+### Fallback Frontmatter (per file)
+
+No YAML frontmatter required — these are reference documents with markdown tables.
+
+### Required Body Structure (minimum per file)
+
+- **STACK.md**: `## Tech Stack` table (Category, Technology, Version, Config File) + `## Package Manager`
+- **ARCHITECTURE.md**: `## Architecture Overview` (pattern name) + `## Key Components` table + `## Data Flow`
+- **CONVENTIONS.md**: `## Code Conventions` table (Convention, Pattern, Example File) + `## Naming Patterns`
+- **CONCERNS.md**: `## Concerns` table (Severity, Area, Description, File) + `## Security Considerations`
+
+### Special Handling
+
+- Every claim must reference actual file paths — no vague references
+- Codebase-Mapper does NOT commit — the orchestrator handles commits
+- Researcher treats these as S0 (highest confidence) local prior research
+- One focus area per invocation

package/plugins/pbr/references/pbr-rules.md

@@ -27,6 +27,7 @@ Condensed from the 3,100-line `docs/DEVELOPMENT-GUIDE.md`. When in doubt, these
 13. Read STATE.md and config.json fully. Read ROADMAP.md by section. Read PLAN.md/SUMMARY.md/VERIFICATION.md frontmatter only.
 14. Use the `limit` parameter on Read to restrict line counts.
 15. Proactively suggest `/pbr:pause` when context gets heavy — before compaction, not after.
+15b. **After compaction or context recovery**, always read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
 
 ---
 

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

@@ -0,0 +1,285 @@
+# 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:build",
+    "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" }`
+
+---
+
+## 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>" }`.