@sienklogic/plan-build-run 2.51.0 → 2.53.0

package/plugins/pbr/skills/build/SKILL.md

@@ -65,7 +65,7 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut and config
 1. Parse `$ARGUMENTS` for phase number and flags
 2. Read `.planning/config.json` for parallelization, model, and gate settings (see config-loading.md for field reference)
 3. Resolve depth profile: run `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get the effective feature/gate settings for the current depth. Store the result for use in later gating decisions.
-4. **CRITICAL: Write .active-skill NOW.** Write `.planning/.active-skill` with the content `build` (registers with workflow enforcement hook)
+4. **CRITICAL (hook-enforced): Write .active-skill NOW.** Write `.planning/.active-skill` with the content `build` (registers with workflow enforcement hook)
 5. Validate:
    - Phase directory exists at `.planning/phases/{NN}-{slug}/`
    - PLAN.md files exist in the directory
@@ -190,7 +190,7 @@ Validate wave consistency:
 
 ### Step 5b: Write Checkpoint Manifest (inline)
 
-**CRITICAL: Initialize checkpoint manifest NOW before entering the wave loop.**
+**CRITICAL (hook-enforced): Initialize checkpoint manifest NOW before entering the wave loop.**
 
 ```bash
 node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js checkpoint init {phase-slug} --plans "{comma-separated plan IDs}"
@@ -338,7 +338,7 @@ For each completed executor:
 
 **Spot-check executor claims:**
 
-CRITICAL: Before reading results or advancing to the next wave, run the spot-check CLI for each completed plan.
+CRITICAL (no hook): Before reading results or advancing to the next wave, run the spot-check CLI for each completed plan.
 
 For each completed plan in this wave:
 
@@ -560,6 +560,12 @@ node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update last_activity now
 
 **STATE.md size limit:** Follow the size limit enforcement rules in `skills/shared/state-update.md` (150 lines max — collapse completed phases, remove duplicated decisions, trim old sessions).
 
+**Completion check:** Before proceeding to next wave, confirm ALL of:
+- [ ] SUMMARY gate passed for every plan in this wave
+- [ ] STATE.md frontmatter `plans_complete` updated
+- [ ] STATE.md body progress bar updated
+- [ ] `last_activity` timestamp refreshed
+
 ---
 
 ### Step 7: Phase Verification (delegated, conditional)
@@ -604,7 +610,7 @@ Use the same verifier prompt template as defined in `/pbr:review`: read `skills/
 **Prepend this block to the verifier prompt before sending:**
 ```
 <files_to_read>
-CRITICAL: Read these files BEFORE any other action:
+CRITICAL (no hook): Read these files BEFORE any other action:
 1. .planning/phases/{NN}-{slug}/PLAN-*.md — must-haves to verify against
 2. .planning/phases/{NN}-{slug}/SUMMARY-*.md — executor build summaries
 3. .planning/phases/{NN}-{slug}/VERIFICATION.md — prior verification results (if exists)
@@ -662,7 +668,7 @@ If triggered:
    ```
 4. Do NOT block on this — use `run_in_background: true` and continue to Step 8a. Report completion in Step 8f if it finishes in time.
 
-**CRITICAL: Update ROADMAP.md progress table NOW. Do NOT skip this step.**
+**CRITICAL (no hook): Update ROADMAP.md progress table NOW. Do NOT skip this step. (roadmap-sync warns)**
 
 **8a. Update ROADMAP.md Progress table** (REQUIRED — do this BEFORE updating STATE.md):
 
@@ -680,13 +686,18 @@ These return `{ success, old_status, new_status }` or `{ success, old_plans, new
 5. Update the `Status` column to the final_status determined in Step 8-pre
 6. Save the file — do NOT skip this step
 
-**CRITICAL: Update STATE.md NOW with phase completion status. Do NOT skip this step.**
+**CRITICAL (no hook): Update STATE.md NOW with phase completion status. Do NOT skip this step. (state-sync warns)**
 
-**8b. Update STATE.md (CRITICAL — update BOTH frontmatter AND body):**
+**8b. Update STATE.md (CRITICAL (no hook) — update BOTH frontmatter AND body):**
 - Frontmatter: `status`, `plans_complete`, `last_activity`, `progress_percent`, `last_command`
 - Body `## Current Position`: `Phase:` line, `Plan:` line, `Status:` line, `Last activity:` line, `Progress:` bar
 - These MUST stay in sync — the status line reads frontmatter, humans read the body
 
+**Completion check:** Before proceeding to 8c, confirm ALL of:
+- [ ] STATE.md frontmatter fields set: status, plans_complete, last_activity, progress_percent, last_command
+- [ ] STATE.md body ## Current Position updated: Phase, Status, Last activity, Progress bar
+- [ ] Frontmatter and body are consistent (same status value in both)
+
 **8c. Commit planning docs (if configured):**
 Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
 If `planning.commit_docs` is `true`:
@@ -750,6 +761,12 @@ After invoking the chained skill, it runs within the same session. When it compl
 Write `.planning/.auto-next` containing the next logical command (e.g., `/pbr:plan {N+1}` or `/pbr:review {N}`)
 - This file signals to the user or to wrapper scripts that the next step is ready
 
+**Completion check:** Before proceeding to 8f, confirm ALL of:
+- [ ] auto_advance OR auto_continue evaluated (one path taken)
+- [ ] If auto_continue: `.auto-next` file written with correct next command
+- [ ] Pending todos evaluated (Step 8e-ii)
+- [ ] Clearly-satisfied todos auto-closed via `pbr-tools.js todo done`
+
 **8e-ii. Check Pending Todos:**
 
 **CRITICAL (no hook): Check pending todos after build. Do NOT skip this step.**

package/plugins/pbr/skills/milestone/SKILL.md

@@ -151,7 +151,7 @@ Start a new milestone cycle with new phases.
    - **Status:** In progress
    ```
 
-**CRITICAL -- DO NOT SKIP: Update STATE.md frontmatter AND body with new milestone info.**
+**CRITICAL (no hook) -- DO NOT SKIP: Update STATE.md frontmatter AND body with new milestone info.**
 
 8. **Update STATE.md:**
    - Set current phase to the first new phase
@@ -221,7 +221,7 @@ Dry-run of milestone completion — shows what would happen without making any c
    Ready to complete? Run: /pbr:milestone complete v{version}
    ```
 
-**CRITICAL**: This subcommand is READ-ONLY. Do not create directories, move files, modify STATE.md, modify ROADMAP.md, or create git tags. Only read and display.
+**CRITICAL (no hook)**: This subcommand is READ-ONLY. Do not create directories, move files, modify STATE.md, modify ROADMAP.md, or create git tags. Only read and display.
 
 ---
 
@@ -297,7 +297,7 @@ Archive a completed milestone and prepare for the next one.
 
 5. **Archive milestone documents:**
 
-   **CRITICAL: Pre-flight safety checks BEFORE archiving. Do NOT skip this step.**
+   **CRITICAL (no hook): Pre-flight safety checks BEFORE archiving. Do NOT skip this step.**
 
    Before creating or moving anything, verify the destination is safe:
    - Check if `.planning/milestones/{version}/` already exists
@@ -317,19 +317,19 @@ Archive a completed milestone and prepare for the next one.
    - Verify each source phase directory exists before attempting to move it
    - If any source phase directory is missing, warn but continue with the phases that do exist
 
-   **CRITICAL: Create the archive directory .planning/milestones/{version}/ NOW. Do NOT skip this step.**
+   **CRITICAL (no hook): Create the archive directory .planning/milestones/{version}/ NOW. Do NOT skip this step.**
 
    Create a versioned archive directory and move phase directories into it:
    - `.planning/milestones/{version}/ROADMAP.md` — snapshot of ROADMAP.md at completion
-   - `.planning/milestones/{version}/REQUIREMENTS.md` — **CRITICAL: Copy REQUIREMENTS.md to archive NOW. Do NOT skip this step.** Snapshot of REQUIREMENTS.md
+   - `.planning/milestones/{version}/REQUIREMENTS.md` — **CRITICAL (no hook): Copy REQUIREMENTS.md to archive NOW. Do NOT skip this step.** Snapshot of REQUIREMENTS.md
    - `.planning/milestones/{version}/STATS.md` — milestone statistics
    - `.planning/milestones/{version}/phases/{NN}-{slug}/` — move each milestone phase directory from `.planning/phases/` into the archive
 
-   **CRITICAL: Move phase directories from .planning/phases/ to archive NOW. Do NOT skip this step.**
+   **CRITICAL (no hook): Move phase directories from .planning/phases/ to archive NOW. Do NOT skip this step.**
 
    **Move phases:** For each phase belonging to this milestone, move (not copy) its directory from `.planning/phases/{NN}-{slug}/` to `.planning/milestones/{version}/phases/{NN}-{slug}/`. This keeps the active phases directory clean for the next milestone.
 
-   **CRITICAL: Write STATS.md to .planning/milestones/{version}/STATS.md NOW. Do NOT skip this step.**
+   **CRITICAL (no hook): Write STATS.md to .planning/milestones/{version}/STATS.md NOW. Do NOT skip this step.**
 
    **Stats file content:**
 
@@ -350,7 +350,7 @@ Archive a completed milestone and prepare for the next one.
 
    - Move validated requirements from active to completed section
 
-**CRITICAL: Update ROADMAP.md with collapsed milestone section NOW. Do NOT skip this step.**
+**CRITICAL (no hook): Update ROADMAP.md with collapsed milestone section NOW. Do NOT skip this step.**
 
 7. **Collapse completed phases in ROADMAP.md:**
    Replace detailed phase entries with collapsed summaries:
@@ -366,7 +366,7 @@ Archive a completed milestone and prepare for the next one.
    | {N+1}. {name} | Completed |
    ```
 
-**CRITICAL: Update STATE.md to mark milestone as complete NOW. Do NOT skip this step.**
+**CRITICAL (no hook): Update STATE.md to mark milestone as complete NOW. Do NOT skip this step.**
 
 7b. **Update STATE.md:**
    - Update `.planning/STATE.md` to mark the milestone as complete
@@ -387,7 +387,7 @@ Archive a completed milestone and prepare for the next one.
 
 7d. **Aggregate learnings from milestone phases:**
 
-**CRITICAL: Run learnings aggregation NOW. Do NOT skip this step.**
+**CRITICAL (no hook): Run learnings aggregation NOW. Do NOT skip this step.**
 
 ```bash
 node ${CLAUDE_PLUGIN_ROOT}/scripts/milestone-learnings.js .planning/milestones/{version} --project {project-name-from-STATE.md}

package/plugins/pbr/skills/plan/SKILL.md

@@ -116,7 +116,7 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut (`state lo
 
 1. Parse `$ARGUMENTS` for phase number and flags
 2. Read `.planning/config.json` for settings (see config-loading.md for field reference)
-   **CRITICAL: Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
+   **CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
 3. Resolve depth profile: run `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get the effective feature/gate settings for the current depth. Store the result for use in later gating decisions.
 4. Validate:
    - Phase exists in ROADMAP.md
@@ -210,7 +210,7 @@ Read `skills/plan/templates/researcher-prompt.md.tmpl` and use it as the prompt
 **Prepend this block to the researcher prompt before sending:**
 ```
 <files_to_read>
-CRITICAL: Read these files BEFORE any other action:
+CRITICAL (no hook): Read these files BEFORE any other action:
 1. .planning/ROADMAP.md — phase goals, dependencies, and structure
 2. .planning/REQUIREMENTS.md — scoped requirements for this phase (if exists)
 </files_to_read>
@@ -333,7 +333,7 @@ Read `skills/plan/templates/planner-prompt.md.tmpl` and use it as the prompt tem
 
 ```
 <files_to_read>
-CRITICAL: Read these files BEFORE any other action:
+CRITICAL (no hook): Read these files BEFORE any other action:
 1. .planning/CONTEXT.md — locked decisions and constraints (if exists)
 2. .planning/ROADMAP.md — phase goals, dependencies, and structure
 3. .planning/phases/{NN}-{slug}/RESEARCH.md — research findings (if exists)
@@ -355,7 +355,7 @@ Where `{N}` is the number of PLAN.md files written and `{M}` is the number of di
 
 ### Step 5b: Spot-Check Planner Output
 
-CRITICAL: Verify planner output before proceeding.
+CRITICAL (no hook): Verify planner output before proceeding.
 
 1. **PLAN files exist**: Check `.planning/phases/{NN}-{slug}/PLAN-*.md` files exist on disk
 2. **Valid frontmatter**: Read first 20 lines of each PLAN file — verify `depends_on`, `files_modified`, `must_haves` fields present
@@ -400,7 +400,7 @@ Read `skills/plan/templates/checker-prompt.md.tmpl` and use it as the prompt tem
 **Prepend this block to the checker prompt before sending:**
 ```
 <files_to_read>
-CRITICAL: Read these files BEFORE any other action:
+CRITICAL (no hook): Read these files BEFORE any other action:
 1. .planning/phases/{NN}-{slug}/PLAN-*.md — plan files to validate
 2. .planning/CONTEXT.md — locked decisions to check against (if exists)
 </files_to_read>
@@ -470,7 +470,7 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
   4. Update the `Plans Complete` column to `0/{N}` where N = number of plan files just created
   5. Update the `Status` column to `planned`
   6. Save the file — do NOT skip this step
-- Update STATE.md via CLI **(CRITICAL — update BOTH frontmatter AND body)**: set `status: "planned"`, `plans_total`, `last_command` in frontmatter AND update `Status:`, `Plan:` lines in body `## Current Position`
+- Update STATE.md via CLI **(CRITICAL (no hook) — update BOTH frontmatter AND body)**: set `status: "planned"`, `plans_total`, `last_command` in frontmatter AND update `Status:`, `Plan:` lines in body `## Current Position`
 
 **Tooling shortcut**: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state patch '{"status":"planned","last_command":"/pbr:plan {N}"}'`
 - **If `features.auto_advance` is `true` AND `mode` is `autonomous`:** Chain directly to build: `Skill({ skill: "pbr:build", args: "{N}" })`. This continues the build→review→plan→build cycle automatically.
@@ -482,7 +482,7 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
 
 ### Subcommand: `add`
 
-**CRITICAL: Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
+**CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
 
 1. Read `.planning/ROADMAP.md`
 2. Calculate next phase number (last phase + 1)
@@ -499,7 +499,7 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
 
 Reference: `skills/plan/decimal-phase-calc.md` for decimal numbering rules.
 
-**CRITICAL: Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
+**CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
 
 1. Read `.planning/ROADMAP.md`
 2. Calculate decimal phase number:
@@ -520,7 +520,7 @@ Reference: `skills/plan/decimal-phase-calc.md` for decimal numbering rules.
    - Phase must exist
    - Phase must be in `pending` or `not started` status (cannot remove completed/in-progress phases)
    - No other phases depend on this phase (or user confirms breaking dependencies)
-3. **CRITICAL: Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
+3. **CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
 4. Confirm with user: "Remove Phase {N}: {name}? This will delete the phase directory and renumber subsequent phases."
 5. If confirmed:
    - Delete `.planning/phases/{NN}-{slug}/` directory

package/plugins/pbr/skills/quick/SKILL.md

@@ -94,7 +94,7 @@ If user types something else (freeform): interpret their response and proceed ac
 
 ### Step 4: Generate Slug and Task Number
 
-**CRITICAL: You MUST complete Steps 4, 5, and 6 before any executor is spawned. If you skip these steps, the quick task will have no tracking artifacts and no PLAN.md for the executor to follow. This is the #1 failure mode of this skill.**
+**CRITICAL (no hook): You MUST complete Steps 4, 5, and 6 before any executor is spawned. If you skip these steps, the quick task will have no tracking artifacts and no PLAN.md for the executor to follow. This is the #1 failure mode of this skill.**
 
 **Generate slug:**
 - Take the first 4-5 meaningful words from the description
@@ -176,7 +176,7 @@ Spawn a `Task(subagent_type: "pbr:executor")` with the following prompt:
 You are executor. Execute the following quick task plan.
 
 <files_to_read>
-CRITICAL: Read these files BEFORE any other action:
+CRITICAL (no hook): Read these files BEFORE any other action:
 1. .planning/quick/{NNN}-{slug}/PLAN.md — the quick task plan with task details
 2. .planning/STATE.md — current project state and progress (if exists)
 </files_to_read>
@@ -205,7 +205,7 @@ After the executor completes:
 
 ### Step 8b: Spot-Check Executor Output
 
-CRITICAL: Verify executor output before proceeding.
+CRITICAL (no hook): Verify executor output before proceeding.
 
 1. **SUMMARY.md exists**: Check `.planning/quick/{NNN}-{slug}/SUMMARY.md` exists
 2. **Key files exist**: Verify first 2 files from SUMMARY.md `key_files` frontmatter exist on disk

package/plugins/pbr/skills/review/SKILL.md

@@ -68,7 +68,7 @@ Execute these steps in order.
 
 1. Parse `$ARGUMENTS` for phase number and `--auto-fix` flag
 2. Read `.planning/config.json`
-   **CRITICAL: Write .active-skill NOW.** Write the text "review" to `.planning/.active-skill` using the Write tool.
+   **CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "review" to `.planning/.active-skill` using the Write tool.
 3. Resolve depth profile: run `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get the effective feature/gate settings for the current depth. Store the result for use in later gating decisions.
 4. Validate:
    - Phase directory exists at `.planning/phases/{NN}-{slug}/`
@@ -180,7 +180,7 @@ Read `skills/review/templates/verifier-prompt.md.tmpl` and use its content as th
 **Prepend this block to the verifier prompt before sending:**
 ```
 <files_to_read>
-CRITICAL: Read these files BEFORE any other action:
+CRITICAL (no hook): Read these files BEFORE any other action:
 1. .planning/phases/{NN}-{slug}/PLAN-*.md — must-haves to verify against
 2. .planning/phases/{NN}-{slug}/SUMMARY-*.md — executor build summaries
 3. .planning/phases/{NN}-{slug}/VERIFICATION.md — prior verification results (if exists)
@@ -215,7 +215,7 @@ Then display the overall verdict (`PASSED`, `GAPS FOUND`, or `HUMAN NEEDED`) bef
 
 ### Step 3a: Spot-Check Verifier Output
 
-CRITICAL: Verify verifier output before proceeding.
+CRITICAL (no hook): Verify verifier output before proceeding.
 
 1. **VERIFICATION.md exists**: Check `.planning/phases/{NN}-{slug}/VERIFICATION.md` exists on disk
 2. **Status field present**: Read VERIFICATION.md frontmatter — verify `status` field is present and is one of: pass, fail, partial
@@ -369,7 +369,7 @@ If all automated checks and UAT items passed:
    4. Update the `Status` column to `verified`
    5. Update the `Completed` column to the current date (YYYY-MM-DD)
    6. Save the file — do NOT skip this step
-2. Update `.planning/STATE.md` **(CRITICAL — update BOTH frontmatter AND body):**
+2. Update `.planning/STATE.md` **(CRITICAL (no hook) — update BOTH frontmatter AND body):**
    - Frontmatter: `status: "verified"`, `progress_percent`, `last_activity`, `last_command`
    - Body `## Current Position`: `Status:` line, `Last activity:` line, `Progress:` bar
    - These MUST stay in sync — see `skills/shared/state-update.md`
@@ -422,7 +422,7 @@ Read `skills/review/templates/debugger-prompt.md.tmpl` and use its content as th
 **Prepend this block to the debugger prompt before sending:**
 ```
 <files_to_read>
-CRITICAL: Read these files BEFORE any other action:
+CRITICAL (no hook): Read these files BEFORE any other action:
 1. .planning/phases/{NN}-{slug}/VERIFICATION.md — gaps and failure details
 2. .planning/phases/{NN}-{slug}/SUMMARY-*.md — what was built
 3. .planning/phases/{NN}-{slug}/PLAN-*.md — original plan must-haves
@@ -454,7 +454,7 @@ Read `skills/review/templates/gap-planner-prompt.md.tmpl` and use its content as
 **Prepend this block to the gap planner prompt before sending:**
 ```
 <files_to_read>
-CRITICAL: Read these files BEFORE any other action:
+CRITICAL (no hook): Read these files BEFORE any other action:
 1. .planning/phases/{NN}-{slug}/VERIFICATION.md — gaps to close
 2. .planning/phases/{NN}-{slug}/PLAN-*.md — existing plans for context
 3. .planning/CONTEXT.md — locked decisions and constraints (if exists)