@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/cursor-pbr/skills/scan/SKILL.md

@@ -3,19 +3,21 @@ name: scan
 description: "Analyze an existing codebase. Maps structure, architecture, conventions, and concerns."
 ---
 
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**
+
 ## Step 0 — Immediate Output
 
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SCANNING CODEBASE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SCANNING CODEBASE                          ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
 
-# /pbr:scan — Codebase Analysis
+# /pbr:map-codebase — Codebase Analysis
 
 You are running the **scan** skill. Your job is to analyze an existing codebase and produce a comprehensive map of its structure, architecture, conventions, and concerns. This is the entry point for brownfield projects — codebases that already have code before Plan-Build-Run is introduced.
 
@@ -28,9 +30,9 @@ This skill **spawns 4 parallel Task(subagent_type: "pbr:codebase-mapper")** agen
 Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
 
 Additionally for this skill:
-- **Never** analyze the codebase yourself — delegate ALL analysis to the 4 parallel codebase-mapper subagents
+- **Never** analyze the codebase yourself — delegate ALL analysis to the 4 parallel codebase-mapper agents
 - **Minimize** reading mapper outputs — read only frontmatter or first 20 lines of each output document
-- **Delegate** all file reading, pattern analysis, and architecture mapping to the codebase-mapper subagents
+- **Delegate** all file reading, pattern analysis, and architecture mapping to the codebase-mapper agents
 
 ---
 
@@ -50,7 +52,7 @@ Check if `.planning/codebase/` directory exists:
 
 First, resolve the depth profile so you know which areas are available:
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
 ```
 Read `profile["scan.mapper_areas"]` to determine available areas (quick: tech, arch; standard/comprehensive: tech, arch, quality, concerns).
 
@@ -87,13 +89,13 @@ Before spawning agents, do a quick scan to identify what we're working with. Thi
 4. **Read existing docs** — README.md, architecture docs, .env.example
 5. **Write `.planning/codebase/RECON.md`** with project type, scale, key directories, entry points, and quick stats
 
-Refer to the "Reconnaissance Detection Reference" section of `skills/scan/templates/mapper-prompt.md.tmpl` for the full detection checklists.
+Refer to the "Reconnaissance Detection Reference" section of `${CLAUDE_SKILL_DIR}/templates/mapper-prompt.md.tmpl` for the full detection checklists.
 
 ### Step 3: Spawn Analysis Agents
 
 **Resolve mapper configuration:** Before spawning, resolve the depth profile:
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
 ```
 
 Read `profile["scan.mapper_count"]` and `profile["scan.mapper_areas"]` to determine how many mappers to spawn and which focus areas to cover.
@@ -116,13 +118,21 @@ Display to the user:
 
 Spawn `{mapper_count}` parallel `Task(subagent_type: "pbr:codebase-mapper")` agents, one for each area in `scan.mapper_areas`. All should be spawned in a single response for maximum parallelism.
 
-For each agent, read `skills/scan/templates/mapper-prompt.md.tmpl` and fill in the placeholders:
+For each agent, read `${CLAUDE_SKILL_DIR}/templates/mapper-prompt.md.tmpl` and fill in the placeholders:
 - `{focus_area}`: one of `tech`, `arch`, `quality`, `concerns`
 - `{project_path}`: the working directory
 - `{recon_data}`: contents of RECON.md
 - `{scale}`: detected scale from Step 2
 - `{output_path}`: `.planning/codebase/`
 
+**Prepend this block to each mapper prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/codebase/RECON.md — baseline reconnaissance data (if exists)
+</files_to_read>
+```
+
 | Agent | Focus | Output Files | When |
 |-------|-------|-------------|------|
 | 1 | tech | STACK.md, INTEGRATIONS.md | Always |
@@ -142,6 +152,18 @@ All agents run in parallel. As each completes, display:
 
 (Only display lines for the focus areas that were actually spawned.)
 
+### Step 4b: Check Completion Markers
+
+After each codebase-mapper Task() completes, check the Task() output for the `## MAPPING COMPLETE` marker:
+
+- If `## MAPPING COMPLETE` is present: the mapper finished successfully, proceed normally
+- If the marker is missing: warn the user that the mapper may not have completed successfully:
+  ```
+  ⚠ Codebase mapper ({focus_area}) did not report MAPPING COMPLETE.
+  Output may be incomplete — check .planning/codebase/ for partial results.
+  ```
+  Continue to Step 5 verification regardless (the file existence checks will catch truly missing output).
+
 ### Step 5: Verify Output
 
 After all agents complete, verify the expected files exist:
@@ -169,17 +191,17 @@ For any missing files, display:
 Missing analysis output: {filename}
 Agent that failed: {focus_area} mapper
 
-**To fix:** Re-run with `/pbr:scan` and select "Refresh a specific area" → {focus_area}.
+**To fix:** Re-run with `/pbr:map-codebase` and select "Refresh a specific area" → {focus_area}.
 ```
 
 ### Step 6: Present Summary
 
-Read key findings from each file (frontmatter or first section) and display using the branded stage banner from `references/ui-formatting.md`:
+Read key findings from each file (frontmatter or first section) and display using the branded stage banner from `references/ui-brand.md`:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SCAN COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SCAN COMPLETE ✓                            ║
+╚══════════════════════════════════════════════════════════════╝
 
 Project: {type} ({scale})
 Stack: {primary language} + {framework}
@@ -206,23 +228,25 @@ Top concerns:
 
 Then use the "Next Up" routing block:
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Start a project** — use the scan results to plan your work
 
-`/pbr:begin`
+`/pbr:new-project`
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
-- `/pbr:milestone new` — create a milestone to address concerns
-- `/pbr:status` — see project status
+- `/pbr:new-milestone` — create a milestone to address concerns
+- `/pbr:progress` — see project status
+
 
-───────────────────────────────────────────────────────────────
 ```
 
 ### Step 7: Git Integration
@@ -275,7 +299,7 @@ If no config exists yet (scan before begin), use AskUserQuestion (pattern: yes-n
 - Note their existence in STRUCTURE.md
 - Flag large committed binaries as a concern
 
-### Scan before /pbr:begin
+### Scan before /pbr:new-project
 - This is a valid and encouraged workflow
 - Scan results become input for the begin skill
 - Create `.planning/` and `.planning/codebase/` if needed

package/plugins/cursor-pbr/skills/setup/SKILL.md

@@ -1,177 +1,66 @@
 ---
 name: setup
-description: "Onboarding wizard. Initialize project, select models, verify setup."
+description: "Reconfigure an existing Plan-Build-Run project (models, features, CLAUDE.md)."
 ---
 
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes tokens. Begin executing Step 1 immediately.**
+
 ## Step 0 — Immediate Output
 
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SETUP
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► RECONFIGURE                                ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
 
-# /pbr:setup — Plan-Build-Run Setup Wizard
+# /pbr:setup — Plan-Build-Run Reconfigure
 
-You are running the **setup** skill. This is an interactive onboarding wizard that guides users through Plan-Build-Run project setup. Use AskUserQuestion at each step for clear choices.
+You are running the **setup** skill in **reconfigure mode**. This wizard lets existing Plan-Build-Run projects change model profiles, workflow features, and CLAUDE.md integration. It does NOT re-initialize or overwrite project state.
 
 ---
 
 ## Step 1: Detect Project State
 
-Check if `.planning/` directory exists in the current working directory.
-
-**If `.planning/` exists**:
-- Read `.planning/config.json` to check current settings
-- Tell the user: "Existing Plan-Build-Run project detected. This wizard will review your configuration."
-- Skip to Step 3 (model selection)
-
-**If `.planning/` does NOT exist**:
-- Ask the user:
-
-```
-AskUserQuestion:
-  question: "No Plan-Build-Run project found. Would you like to initialize one?"
-  header: "Initialize"
-  options:
-    - label: "Yes, initialize here"
-      description: "Creates .planning/ directory with default config, STATE.md, and ROADMAP.md"
-    - label: "No, just exploring"
-      description: "Exit the wizard — you can run /pbr:begin later for full project setup"
-```
-
-If "No", display: "Run `/pbr:begin` when you're ready to start a project. It includes deep requirements gathering and roadmap creation." Then stop.
-
-If "Yes", create the minimal `.planning/` structure:
+Check if `.planning/config.json` exists.
 
-```bash
-mkdir -p .planning/phases .planning/todos/pending .planning/todos/done .planning/logs .planning/research
+**If `.planning/config.json` does NOT exist:**
+Display:
 ```
+No Plan-Build-Run project found in this directory.
 
-Create `.planning/config.json` with defaults:
-```json
-{
-  "version": 2,
-  "context_strategy": "aggressive",
-  "mode": "interactive",
-  "depth": "standard",
-  "features": {
-    "structured_planning": true,
-    "goal_verification": true,
-    "integration_verification": true,
-    "context_isolation": true,
-    "atomic_commits": true,
-    "session_persistence": true,
-    "research_phase": true,
-    "plan_checking": true,
-    "tdd_mode": false,
-    "status_line": true,
-    "auto_continue": false,
-    "auto_advance": false,
-    "team_discussions": false,
-    "inline_verify": false
-  },
-  "models": {
-    "researcher": "sonnet",
-    "planner": "inherit",
-    "executor": "inherit",
-    "verifier": "sonnet",
-    "integration_checker": "sonnet",
-    "debugger": "inherit",
-    "mapper": "sonnet",
-    "synthesizer": "sonnet"
-  },
-  "parallelization": {
-    "enabled": true,
-    "plan_level": true,
-    "task_level": false,
-    "max_concurrent_agents": 3,
-    "min_plans_for_parallel": 2,
-    "use_teams": false
-  },
-  "planning": {
-    "commit_docs": true,
-    "max_tasks_per_plan": 3,
-    "search_gitignored": false
-  },
-  "git": {
-    "branching": "none",
-    "commit_format": "{type}({phase}-{plan}): {description}",
-    "phase_branch_template": "plan-build-run/phase-{phase}-{slug}",
-    "milestone_branch_template": "plan-build-run/{milestone}-{slug}",
-    "mode": "enabled"
-  },
-  "gates": {
-    "confirm_project": true,
-    "confirm_roadmap": true,
-    "confirm_plan": true,
-    "confirm_execute": false,
-    "confirm_transition": true,
-    "issues_review": true
-  },
-  "safety": {
-    "always_confirm_destructive": true,
-    "always_confirm_external_services": true
-  }
-}
-```
+/pbr:setup is for reconfiguring existing projects.
+To start a new project, run: /pbr:new-project
 
-Create `.planning/STATE.md`:
-```markdown
----
-version: 2
-current_phase: 0
-total_phases: 0
-status: "initialized"
-progress_percent: 0
-last_activity: "{today's date}"
-last_command: "/pbr:setup"
-blockers: []
----
-# Project State
-
-## Current Position
-Phase: 0 of 0
-Status: initialized
-
-Plan-Build-Run project initialized via /pbr:setup. Run /pbr:begin to start requirements gathering and roadmap creation.
+/pbr:new-project includes everything /pbr:setup used to do, plus deep requirements gathering and roadmap creation.
 ```
+Stop. Do not proceed further.
+
+**If `.planning/config.json` exists:**
+- Read `.planning/config.json`
+- Display the current settings summary:
+  ```
+  Current configuration:
+  - Model profile: {derived from models block — balanced/quality/budget or custom}
+  - Depth: {depth}
+  - Mode: {mode}
+  - Auto-continue: {features.auto_continue}
+  - TDD mode: {features.tdd_mode}
+  - Git branching: {git.branching}
+  ```
+- Proceed to Step 2.
 
 ---
 
-## Step 2: Project Type (new projects only)
-
-```
-AskUserQuestion:
-  question: "What kind of project is this?"
-  header: "Project type"
-  options:
-    - label: "Greenfield"
-      description: "Starting from scratch — full planning cycle recommended"
-    - label: "Existing codebase"
-      description: "Adding Plan-Build-Run to an existing project — run /pbr:scan first"
-    - label: "Prototype/experiment"
-      description: "Quick iteration — lighter workflow with fewer gates"
-```
-
-Based on selection:
-- **Greenfield**: Keep defaults (full gates, structured planning)
-- **Existing codebase**: Suggest running `/pbr:scan` after setup to map the codebase
-- **Prototype**: Set `depth: "quick"`, disable `gates.verification`, disable `gates.review`, set `features.research_phase: false`
+## Step 2: Model Selection
 
-Update config.json with any changes.
-
----
+Note: These profiles control agent models, not the orchestrator. The orchestrator uses your Claude Code session model. For cost optimization, consider running your session on Sonnet -- agents with `inherit` will follow. See `references/model-profiles.md` for details.
 
-## Step 3: Model Selection
-
-```
-AskUserQuestion:
-  question: "Which model profile should Plan-Build-Run use for agents?"
+Use AskUserQuestion:
+  question: "Which model profile should agents use?"
   header: "Models"
   options:
     - label: "Balanced (Recommended)"
@@ -180,19 +69,20 @@ AskUserQuestion:
       description: "Opus for executor and planner, Sonnet for others. Best results, highest cost."
     - label: "Budget"
       description: "Haiku for most agents. Fastest and cheapest, but lower quality."
-```
+    - label: "Keep current"
+      description: "Leave model settings unchanged."
 
-Apply the selected profile to `config.json`:
+Apply the selected profile to the models block in config.json:
 - **Balanced**: executor=sonnet, researcher=sonnet, planner=sonnet, verifier=sonnet, synthesizer=haiku
 - **Quality**: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet
 - **Budget**: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku
+- **Keep current**: no change to models block
 
 ---
 
-## Step 4: Workflow Preferences
+## Step 3: Workflow Features
 
-```
-AskUserQuestion:
+Use AskUserQuestion:
   question: "Which workflow features do you want enabled?"
   header: "Features"
   multiSelect: true
@@ -205,9 +95,8 @@ AskUserQuestion:
       description: "Require verification AND review to pass before advancing phases"
     - label: "Git branching"
       description: "Create a branch per phase for cleaner PR history"
-```
 
-Apply selections:
+Apply selections (others unchanged):
 - **Auto-continue**: Set `features.auto_continue: true`
 - **TDD mode**: Set `features.tdd_mode: true`
 - **Strict gates**: Set `gates.verification: true`, `gates.review: true`, `gates.plan_approval: true`
@@ -215,36 +104,132 @@ Apply selections:
 
 ---
 
-## Step 5: Verification
+## Step 4: CLAUDE.md Integration
+
+Check if a `CLAUDE.md` file exists in the project root.
 
-Run a quick health check:
+**If it exists**: Read it. If it does NOT already contain a "Plan-Build-Run" section, offer to append the integration block.
+**If it does NOT exist**: Offer to create `CLAUDE.md` with the integration block.
 
-1. Verify `.planning/config.json` is valid JSON
-2. Verify `.planning/STATE.md` exists and is parseable
-3. Verify hook scripts are accessible: `node ${CLAUDE_PLUGIN_ROOT}/scripts/progress-tracker.js` from the project directory
-4. Check that `npm test` works (if package.json exists)
+Use AskUserQuestion:
+  question: "Update CLAUDE.md with Plan-Build-Run integration notes?"
+  header: "CLAUDE.md"
+  options:
+    - label: "Yes"
+      description: "Add or update the Plan-Build-Run section in CLAUDE.md"
+    - label: "No"
+      description: "Skip — leave CLAUDE.md as-is"
+
+If "Yes", append/create:
+```markdown
+## Plan-Build-Run
 
-Display results:
+This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run) for structured development.
 
+- Project state: `.planning/STATE.md` (source of truth for current phase and progress)
+- Configuration: `.planning/config.json`
+- Run `/pbr:progress` to see current project state and suggested next action.
+
+**After compaction or context recovery**: Read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
 ```
-Setup Complete!
-
-Project: {cwd basename}
-Model profile: {balanced/quality/budget}
-Depth: {quick/standard/comprehensive}
-Features: {list of enabled non-default features}
-
-Next steps:
-  /pbr:begin  — Full project setup with requirements and roadmap
-  /pbr:scan   — Analyze existing codebase (if adding to existing project)
-  /pbr:help   — Command reference
-  /pbr:config — Fine-tune individual settings
+
+---
+
+## Step 5: Platform Settings
+
+Manage Claude Code platform settings that PBR recommends for optimal token usage.
+
+**Read `.planning/config.json`** (already loaded in Step 1). Check for a `platform_settings` block:
+- If absent, treat it as `{}` (no managed settings).
+
+**Check for existing `.claude/settings.json`**:
+- If it exists, read its contents. Parse as JSON (or `{}` if empty/missing).
+- If it does not exist, start from `{}`.
+
+**Compute the merge**:
+- Start with the existing `.claude/settings.json` content.
+- Apply each key from `platform_settings` in config.json on top.
+- If `platform_settings` is absent or empty, skip the write entirely.
+
+**Report drift** (compare before/after):
+- List keys being ADDED (were absent in .claude/settings.json)
+- List keys being CHANGED (differ from existing .claude/settings.json value)
+- List keys that MATCH (already correct — no change needed)
+
+Display the report:
+
+```
+Platform Settings:
+  Keys added:   includeGitInstructions → false
+  Keys matched: (none)
+  Keys changed: (none)
+
+Writing .claude/settings.json...
+```
+
+If all keys already match, display:
+
+```
+Platform Settings: .claude/settings.json is already in sync — no changes needed.
+```
+
+**Conflict detection**: If an existing `.claude/settings.json` has a key from `platform_settings` set to the OPPOSITE value (e.g., `"includeGitInstructions": true` when PBR wants `false`), display a WARNING before overwriting:
+
+```
+WARNING: .claude/settings.json has includeGitInstructions: true
+         PBR recommends false (removes redundant built-in git instructions).
+         Overwriting with PBR recommended value.
+```
+
+**Write the merged settings.json**:
+- Write to `.claude/settings.json` in the project root (alongside `.planning/`).
+- Ensure the directory `.claude/` exists (create it if needed with Bash `mkdir -p .claude`).
+- Write with 2-space indentation. Include a `$schema` key at the top:
+  ```json
+  {
+    "$schema": "https://json.schemastore.org/claude-code-settings.json",
+    "includeGitInstructions": false
+  }
+  ```
+  (Merge in any pre-existing keys from .claude/settings.json that are NOT managed by PBR — pass them through unchanged at the bottom of the object.)
+
+**Drift detection note**: On subsequent /pbr:setup runs, if `.claude/settings.json` has drifted from `platform_settings` (e.g., user manually changed it), this step will detect and re-apply the PBR values with a drift warning. This is by design — platform_settings in config.json is the source of truth.
+
+---
+
+## Step 6: Write Updated Config
+
+**CRITICAL: Write `.planning/config.json` NOW with all changes from Steps 2-3. Do NOT skip this step.**
+
+Write the updated config.json to disk with all applied changes.
+
+---
+
+## Step 7: Verification
+
+Run a quick check:
+1. Verify `.planning/config.json` is valid JSON (read it back)
+2. Display updated settings summary
+
+Display:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► RECONFIGURE COMPLETE ✓                     ║
+╚══════════════════════════════════════════════════════════════╝
+
+Updated:
+- Model profile: {new profile}
+- Features changed: {list or "none"}
+- CLAUDE.md: {updated/skipped}
+- Platform settings: {".claude/settings.json updated" or "already in sync" or "no managed settings"}
+
+Run /pbr:progress to see current project state.
 ```
 
 ---
 
 ## Error Handling
 
-- If `.planning/` creation fails (permissions): Tell user to create it manually and retry
+- If config.json parse fails: Display the raw content and ask user to fix it manually, then retry
 - If config.json write fails: Display the JSON content and ask user to save it manually
-- If health check fails: Display specific failure and suggest `/pbr:health` for diagnostics

package/plugins/cursor-pbr/skills/shared/commit-planning-docs.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../../pbr/skills/shared/commit-planning-docs.md -->
 # Commit Planning Docs Pattern
 
 Standard pattern for committing planning artifacts to git. Reference this fragment in skills that create or modify `.planning/` files.
@@ -17,6 +16,14 @@ If `planning.commit_docs: false` or config.json missing:
 - Skip the commit step
 ```
 
+**Note:** CLI state commands (`state advance-plan`, `phase complete`, `state update-progress`) automatically update STATE.md and ROADMAP.md. The commit step here covers planning artifacts (PLAN.md, SUMMARY.md, VERIFICATION.md), not state files -- those are updated atomically by CLI commands.
+
+## Session Affinity
+
+When a session ID is available (from `.planning/.session.json`), append `[session:{short_id}]` to the commit description, where `short_id` is the first 8 characters of the session_id. This enables conflict tracing when multiple sessions modify planning docs concurrently.
+
+Example: `docs(planning): capture phase 3 discussion decisions [session:a1b2c3d4]`
+
 ## Commit Messages by Skill
 
 | Skill | Commit message format |

package/plugins/cursor-pbr/skills/shared/config-loading.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../../pbr/skills/shared/config-loading.md -->
 # Config Loading Pattern
 
 Standard pattern for loading `.planning/config.json` fields at the start of a skill invocation.
@@ -11,7 +10,7 @@ Standard pattern for loading `.planning/config.json` fields at the start of a sk
 
 Instead of reading and parsing STATE.md, ROADMAP.md, and config.json manually, run:
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js state load
 ```
 This returns a JSON object with `config`, `state`, `roadmap`, `current_phase`, and `progress`. Falls back gracefully if the script is missing -- parse files manually in that case.