@sienklogic/plan-build-run 2.21.0 → 2.22.0

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

@@ -331,10 +331,10 @@ 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`:
-   - Phase status: "verified"
-   - Progress updated
-   - Last activity timestamp
+2. Update `.planning/STATE.md` **(CRITICAL — 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`
    - **STATE.md size limit:** Follow size limit enforcement rules in `skills/shared/state-update.md` (150 lines max).
 3. Update VERIFICATION.md with UAT results (append UAT section)
 3. Present completion:

package/plugins/pbr/skills/shared/state-update.md

@@ -4,12 +4,17 @@ Standard pattern for updating `.planning/STATE.md`. Include this fragment in ski
 
 ---
 
+**CRITICAL: STATE.md has TWO representations — YAML frontmatter AND markdown body. You MUST update BOTH when changing state. The status line reads frontmatter; humans and hooks read the body. If you only update frontmatter, the body goes stale and the status line shows wrong data. Do NOT skip body updates under any circumstances.**
+
+---
+
 ## When to Update STATE.md
 
 | Event | What to Update |
 |-------|---------------|
-| Phase status changes (planned, building, verified) | Current Position section |
-| Plan completes or fails | Plan counter, status, last activity |
+| Phase status changes (planned, building, verified) | Frontmatter fields AND Current Position section |
+| Plan completes or fails | Frontmatter fields AND Plan counter, status, last activity |
+| Phase advances to next phase | Frontmatter fields AND Phase line, Status, Last activity, Progress bar |
 | New decision made | Accumulated Context > Decisions |
 | Blocker discovered or resolved | Accumulated Context > Blockers/Concerns |
 | Session starts or ends | Session Continuity section |
@@ -31,6 +36,9 @@ See: .planning/PROJECT.md (updated {date})
 Update `Current focus` when phase changes.
 
 ### 2. Current Position (lines 9-14)
+
+**CRITICAL: This section MUST match the frontmatter fields above it. When you update `current_phase` or `status` in frontmatter, you MUST also update the corresponding lines below. A hook will auto-fix drift, but do not rely on it.**
+
 ```
 ## Current Position
 Phase: {N} of {total} ({Phase name})

package/plugins/pbr/templates/ROADMAP.md.tmpl

@@ -28,6 +28,8 @@ Phase 01 ──→ Phase 02 ──→ Phase 04
 **Goal:** {overall project goal from requirements}
 **Phases:** 1 - {n}
 
+## Phase Details
+
 ### Phase 01: Project Setup
 
 **Goal**: {goal statement}