@sienklogic/plan-build-run 2.10.0 → 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/ui-formatting.md

@@ -7,9 +7,9 @@ Consistent output formatting for all Plan-Build-Run skills. Every skill that pro
 Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► {STAGE NAME}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► {STAGE NAME}                              ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 **Stage names (uppercase):**
@@ -21,7 +21,7 @@ Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
 - `EXECUTING WAVE {N}`
 - `VERIFYING`
 - `PHASE {N} COMPLETE ✓`
-- `MILESTONE COMPLETE 🎉`
+- `MILESTONE COMPLETE`
 - `SCANNING CODEBASE`
 - `DEBUGGING`
 
@@ -33,9 +33,9 @@ Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
 
 Format:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► {SKILL NAME}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► {SKILL NAME}                              ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 **Skill names (uppercase):**
@@ -155,7 +155,7 @@ For research agents:
 
 ## Checkpoint Boxes
 
-User action required. Use double-line box drawing, 62-character width.
+User action required. Use double-line box drawing, 62-character inner width.
 
 ```
 ╔══════════════════════════════════════════════════════════════╗
@@ -164,9 +164,7 @@ User action required. Use double-line box drawing, 62-character width.
 
 {Content}
 
-──────────────────────────────────────────────────────────────
 → {ACTION PROMPT}
-──────────────────────────────────────────────────────────────
 ```
 
 **Types:**
@@ -260,25 +258,21 @@ Use plain conversational prompts for these cases instead.
 Always present at end of major completions (phase complete, milestone complete, project init).
 
 ```
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{Identifier}: {Name}** — {one-line description}
 
 `{copy-paste command}`
 
 <sub>`/clear` first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
+```
 
 **Also available:**
 - `/pbr:alternative-1` — description
 - `/pbr:alternative-2` — description
 
-───────────────────────────────────────────────────────────────
-```
-
 **Shorter routing (for minor completions):**
 ```
 What's next?
@@ -333,18 +327,18 @@ Use tables for structured data:
 ### Phase Complete
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {Name}**
 
 {X} plans executed
 Goal verified ✓
 
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
 
@@ -352,30 +346,26 @@ Goal verified ✓
 
 <sub>/clear first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
 - /pbr:plan {N+1} — skip discussion, plan directly
 - /pbr:review {N} — manual acceptance testing before continuing
-
-───────────────────────────────────────────────────────────────
 ```
 
 ### Milestone Complete
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MILESTONE COMPLETE                         ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{version}**
 
 {N} phases completed
 All phase goals verified ✓
 
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Audit milestone** — verify requirements, cross-phase integration, E2E flows
 
@@ -383,21 +373,17 @@ All phase goals verified ✓
 
 <sub>/clear first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
 - /pbr:review — manual acceptance testing
 - /pbr:milestone complete — archive milestone after audit passes
-
-───────────────────────────────────────────────────────────────
 ```
 
 ### Gaps Found
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠                    ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {Name}**
 
@@ -408,9 +394,9 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
 
 {Extract gap summaries from VERIFICATION.md}
 
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Plan gap closure** — create additional plans to complete the phase
 
@@ -418,13 +404,9 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
 
 <sub>/clear first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
 - cat .planning/phases/{phase_dir}/VERIFICATION.md — see full report
 - /pbr:review {N} — manual testing before planning
-
-───────────────────────────────────────────────────────────────
 ```
 
 ---
@@ -434,9 +416,9 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
 Use for session lifecycle transitions (pause/resume):
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SESSION RESTORED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SESSION RESTORED ✓                         ║
+╚══════════════════════════════════════════════════════════════╝
 
 Position: Phase {N} — {phase name}, Plan {M}
 Paused: {ISO datetime}
@@ -452,10 +434,11 @@ Other session banners: `SESSION SAVED ✓` (pause), `RESUMING SESSION` (resume s
 ## Anti-Patterns
 
 Do NOT:
-- Use varying box/banner widths
-- Mix banner styles (`===`, `---`, `***`) with `━━━` banners
+- Use varying box/banner widths — always 62-character inner width
+- Use `━━━` heavy bars or `───` thin dividers for banners/sections — use `╔═╗║╚═╝` boxes
+- Mix banner styles (`===`, `---`, `***`) with double-line boxes
 - Skip `PLAN-BUILD-RUN ►` prefix in stage banners
-- Use random emoji (only `🎉` for milestone complete, `✓` for phase complete)
+- Use random emoji (only for milestone complete, `✓` for phase complete)
 - Skip the "Next Up" block after major completions
 - Reference non-Plan-Build-Run commands (always use `/pbr:*` commands)
 - Use non-Plan-Build-Run branding in banners

package/plugins/pbr/scripts/check-skill-workflow.js

@@ -113,6 +113,7 @@ function checkSkillRules(skill, filePath, planningDir) {
 
   switch (skill) {
   case 'quick':
+  case 'do':
     return checkQuickRules(filePath, isInPlanning, planningDir);
   case 'build':
     return checkBuildRules(filePath, isInPlanning, planningDir);
@@ -126,6 +127,16 @@ function checkSkillRules(skill, filePath, planningDir) {
   case 'explore':
   case 'import':
   case 'scan':
+  case 'note':
+  case 'todo':
+  case 'health':
+  case 'help':
+  case 'config':
+  case 'continue':
+  case 'resume':
+  case 'pause':
+  case 'status':
+  case 'dashboard':
     return checkReadOnlySkillRules(skill, filePath, isInPlanning);
   default:
     return null;

package/plugins/pbr/scripts/check-state-sync.js

@@ -161,6 +161,10 @@ function updateStatePosition(content, updates) {
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
 
+    if (updates.phaseLine !== undefined && /^Phase:\s/.test(line)) {
+      lines[i] = `Phase: ${updates.phaseLine}`;
+    }
+
     if (updates.planLine !== undefined && /^Plan:\s/.test(line)) {
       lines[i] = `Plan: ${updates.planLine}`;
     }
@@ -185,6 +189,18 @@ function updateStatePosition(content, updates) {
       let fm = content.substring(0, fmEnd + 3);
       const body = content.substring(fmEnd + 3);
 
+      if (updates.fmCurrentPhase !== undefined) {
+        fm = fm.replace(/^(current_phase:\s*).*/m, `$1${updates.fmCurrentPhase}`);
+      }
+      if (updates.fmTotalPhases !== undefined) {
+        fm = fm.replace(/^(total_phases:\s*).*/m, `$1${updates.fmTotalPhases}`);
+      }
+      if (updates.fmPhaseSlug !== undefined) {
+        fm = fm.replace(/^(phase_slug:\s*).*/m, `$1"${updates.fmPhaseSlug}"`);
+      }
+      if (updates.fmPhaseName !== undefined) {
+        fm = fm.replace(/^(phase_name:\s*).*/m, `$1"${updates.fmPhaseName}"`);
+      }
       if (updates.fmPlansComplete !== undefined) {
         fm = fm.replace(/^(plans_complete:\s*).*/m, `$1${updates.fmPlansComplete}`);
       }
@@ -216,6 +232,9 @@ function updateStatePositionBody(body, updates) {
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
 
+    if (updates.phaseLine !== undefined && /^Phase:\s/.test(line)) {
+      lines[i] = `Phase: ${updates.phaseLine}`;
+    }
     if (updates.planLine !== undefined && /^Plan:\s/.test(line)) {
       lines[i] = `Plan: ${updates.planLine}`;
     }
@@ -323,6 +342,17 @@ function checkStateSync(data) {
   const today = new Date().toISOString().slice(0, 10);
   const messages = [];
 
+  // Derive phase metadata for potential phase-line sync
+  const phaseNumInt = parseInt(phaseNum, 10);
+  const phaseSlug = phaseDirName.replace(/^\d+-/, '');
+  const phaseName = phaseSlug.replace(/-/g, ' ')
+    .replace(/\b\w/g, c => c.toUpperCase());
+  let totalPhases = 0;
+  try {
+    totalPhases = fs.readdirSync(phasesDir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && /^\d+-/.test(e.name)).length;
+  } catch (_e) { /* leave as 0 */ }
+
   if (isSummary) {
     const plansComplete = `${artifacts.completeSummaries}/${artifacts.plans}`;
     const allComplete = artifacts.completeSummaries >= artifacts.plans;
@@ -358,6 +388,20 @@ function checkStateSync(data) {
           fmLastActivity: today,
           fmProgressPct: overallPct
         };
+
+        // Detect phase mismatch and add phase updates
+        const currentPhaseMatch = stateContent.match(/^current_phase:\s*(\d+)/m)
+          || stateContent.match(/^Phase:\s*(\d+)\s/m);
+        const currentPhase = currentPhaseMatch ? parseInt(currentPhaseMatch[1], 10) : null;
+        if (currentPhase !== null && currentPhase !== phaseNumInt) {
+          stateUpdates.phaseLine = `${phaseNumInt} of ${totalPhases} (${phaseName})`;
+          stateUpdates.fmCurrentPhase = phaseNumInt;
+          stateUpdates.fmTotalPhases = totalPhases;
+          stateUpdates.fmPhaseSlug = phaseSlug;
+          stateUpdates.fmPhaseName = phaseName;
+          messages.push(`STATE.md: Phase ${currentPhase} → ${phaseNumInt}`);
+        }
+
         const updatedState = updateStatePosition(stateContent, stateUpdates);
         if (updatedState !== stateContent) {
           atomicWrite(statePath, updatedState);
@@ -422,6 +466,20 @@ function checkStateSync(data) {
           fmLastActivity: today,
           fmProgressPct: overallPct
         };
+
+        // Detect phase mismatch and add phase updates
+        const currentPhaseMatch = stateContent.match(/^current_phase:\s*(\d+)/m)
+          || stateContent.match(/^Phase:\s*(\d+)\s/m);
+        const currentPhase = currentPhaseMatch ? parseInt(currentPhaseMatch[1], 10) : null;
+        if (currentPhase !== null && currentPhase !== phaseNumInt) {
+          stateUpdates.phaseLine = `${phaseNumInt} of ${totalPhases} (${phaseName})`;
+          stateUpdates.fmCurrentPhase = phaseNumInt;
+          stateUpdates.fmTotalPhases = totalPhases;
+          stateUpdates.fmPhaseSlug = phaseSlug;
+          stateUpdates.fmPhaseName = phaseName;
+          messages.push(`STATE.md: Phase ${currentPhase} → ${phaseNumInt}`);
+        }
+
         const updatedState = updateStatePosition(stateContent, stateUpdates);
         if (updatedState !== stateContent) {
           atomicWrite(statePath, updatedState);