@accelerationguy/accel 1.0.0

package/modules/drive/src/workflows/transition-phase.md

@@ -0,0 +1,368 @@
+<purpose>
+Handle phase-level transition after all plans in a phase are complete. Evolves PROJECT.md, verifies phase completion, cleans up, and routes to next phase or milestone completion.
+
+**Invoked by:** unify-phase.md when it detects "last plan in phase"
+**Scope:** Phase N → Phase N+1 (or milestone completion)
+</purpose>
+
+<when_to_use>
+- All plans in current phase have SUMMARY.md files
+- Phase is ready to close
+- Moving to next phase or completing milestone
+</when_to_use>
+
+<required_reading>
+@.drive/STATE.md
+@.drive/PROJECT.md
+@.drive/ROADMAP.md
+@.drive/phases/{current-phase}/*-SUMMARY.md
+</required_reading>
+
+<process>
+
+<step name="verify_phase_completion" priority="first">
+1. Count PLAN.md files in current phase directory
+2. Count SUMMARY.md files in current phase directory
+3. **Verification:**
+   - If counts match: Phase complete
+   - If counts don't match: Phase incomplete
+
+**If incomplete:**
+```
+════════════════════════════════════════
+PHASE INCOMPLETE
+════════════════════════════════════════
+
+Phase {N} has incomplete plans:
+- {phase}-01-SUMMARY.md ✓
+- {phase}-02-SUMMARY.md ✗ Missing
+- {phase}-03-SUMMARY.md ✗ Missing
+
+Options:
+[1] Continue current phase (execute remaining plans)
+[2] Mark complete anyway (skip remaining plans)
+[3] Review what's left
+════════════════════════════════════════
+```
+
+Wait for user decision before proceeding.
+
+**If complete:** Continue to next step.
+</step>
+
+<step name="cleanup_handoffs">
+1. Check for stale handoffs in phase directory:
+   ```bash
+   ls .drive/phases/{current-phase}/HANDOFF*.md 2>/dev/null
+   ```
+2. If found, delete them — phase is complete, handoffs are stale
+3. Note: Active handoffs at `.drive/` root are preserved
+</step>
+
+<step name="evolve_project">
+**Read phase summaries:**
+```bash
+cat .drive/phases/{current-phase}/*-SUMMARY.md
+```
+
+**Assess and update PROJECT.md:**
+
+1. **Requirements validated?**
+   - Any requirements shipped in this phase?
+   - Move to Validated section: `- ✓ [Requirement] — Phase X`
+
+2. **Requirements invalidated?**
+   - Any requirements discovered unnecessary or wrong?
+   - Move to Out of Scope: `- [Requirement] — [reason]`
+
+3. **Requirements emerged?**
+   - New requirements discovered during building?
+   - Add to Active: `- [ ] [New requirement]`
+
+4. **Key Decisions to log?**
+   - Extract decisions from SUMMARY.md files
+   - Add to Key Decisions table
+
+5. **Core value still accurate?**
+   - If product meaningfully changed, update description
+   - Keep it current
+
+**Update footer:**
+```markdown
+---
+*Last updated: [date] after Phase [X]*
+```
+</step>
+
+<step name="review_accumulated_context">
+Update STATE.md Accumulated Context section:
+
+**Decisions:**
+- Note 3-5 recent decisions from this phase
+- Full log lives in PROJECT.md
+
+**Blockers/Concerns:**
+- Resolved blockers: Remove from list
+- Unresolved: Keep with "Phase X" prefix
+- New concerns from summaries: Add
+
+**Deferred Issues:**
+- Update count if issues were logged
+- Note if many accumulated
+</step>
+
+<step name="update_state_for_transition">
+Update STATE.md Current Position:
+
+```markdown
+## Current Position
+
+Phase: [N+1] of [total] ([Next phase name])
+Plan: Not started
+Status: Ready to plan
+Last activity: [today] — Phase [N] complete, transitioned to Phase [N+1]
+
+Progress: [updated bar based on completed plans]
+```
+
+Update Session Continuity:
+```markdown
+## Session Continuity
+
+Last session: [today]
+Stopped at: Phase [N] complete, ready to plan Phase [N+1]
+Next action: /drive:plan for Phase [N+1]
+Resume file: .drive/ROADMAP.md
+```
+</step>
+
+<step name="update_roadmap_completion">
+Update ROADMAP.md:
+
+1. Mark current phase complete:
+   - Status: ✅ Complete
+   - Completed: [date]
+   - Plan count: X/X
+
+2. Update progress summary:
+   - Phases: Y of Z complete
+   - Calculate percentage
+</step>
+
+<step name="commit_phase">
+**Git commit for completed phase:**
+
+**1. Check for feature branches from this phase:**
+```bash
+git branch --list "feature/{phase}*"
+```
+
+**2. If feature branch exists:**
+```
+────────────────────────────────────────
+Feature branch detected: feature/{phase-name}
+
+Checking for conflicts with main...
+────────────────────────────────────────
+```
+
+Check for conflicts:
+```bash
+git fetch origin main 2>/dev/null || true
+git diff main...feature/{phase-name} --stat
+```
+
+**If no conflicts:**
+```
+No conflicts detected.
+
+Merge feature/{phase-name} to main? [yes/no]
+```
+
+If yes:
+```bash
+git checkout main
+git merge feature/{phase-name} --no-ff -m "Merge feature/{phase-name} into main"
+git branch -d feature/{phase-name}
+```
+
+**If conflicts exist:**
+```
+⚠️ Conflicts detected between feature/{phase-name} and main.
+
+Cannot auto-merge. Options:
+[1] Resolve conflicts manually, then re-run transition
+[2] Keep on feature branch (do not merge)
+[3] Force merge anyway (not recommended)
+```
+
+**3. Stage phase files:**
+```bash
+git add .drive/phases/{phase}/ .drive/STATE.md .drive/PROJECT.md .drive/ROADMAP.md
+git add src/  # If source files were modified
+```
+
+**4. Create phase commit:**
+```bash
+git commit -m "$(cat <<'EOF'
+feat({phase}): {phase-description}
+
+Phase {N} complete:
+- {plan-01 summary}
+- {plan-02 summary}
+- {plan-03 summary}
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+**5. Record git state for complete-milestone:**
+Update STATE.md Accumulated Context:
+```markdown
+### Git State
+Last commit: {short-hash}
+Branch: main
+Feature branches merged: {list or "none"}
+```
+
+Display:
+```
+Git commit created: {short-hash}
+  feat({phase}): {phase-description}
+```
+</step>
+
+<step name="verify_state_consistency" priority="critical">
+**CRITICAL: Verify state files are aligned before declaring transition complete.**
+
+State consistency is foundational to Drive. If STATE.md, PROJECT.md, or ROADMAP.md are misaligned, all downstream work breaks — resume fails, progress tracking is wrong, context is lost.
+
+**1. Re-read all three files completely:**
+```bash
+cat .drive/STATE.md
+cat .drive/PROJECT.md
+cat .drive/ROADMAP.md
+```
+
+**2. Verify alignment across these fields:**
+
+| Field | STATE.md | PROJECT.md | ROADMAP.md |
+|-------|----------|------------|------------|
+| Version | `Version:` field | Current State table | Version Overview |
+| Phase | `Phase:` field | (implicit in Active) | Phase Structure table |
+| Status | `Status:` field | `Status:` in table | Phase status column |
+| Focus | `Current focus:` header | (matches Active) | Current Milestone |
+
+**3. Check for stale references:**
+- No "blocked on X" if X is complete
+- No "IN PROGRESS" for completed phases
+- Current focus matches current phase, not previous
+- Progress bars match actual plan counts
+
+**4. If ANY misalignment found:**
+```
+════════════════════════════════════════
+⚠️ STATE CONSISTENCY ERROR
+════════════════════════════════════════
+
+Misalignment detected:
+| Field | STATE.md | PROJECT.md | ROADMAP.md |
+|-------|----------|------------|------------|
+| {field} | {value} | {value} | {value} |
+
+Fix ALL misalignments before proceeding.
+This is a blocking error — do not route to next phase.
+════════════════════════════════════════
+```
+
+**Fix the issues, then re-verify.**
+
+**5. If aligned:**
+```
+State consistency: ✓
+  STATE.md    — Phase {N+1}, v{version}, ready to plan
+  PROJECT.md  — v{version}, {active_count} active requirements
+  ROADMAP.md  — Phase {N} ✅, Phase {N+1} 🔵
+```
+
+**Only proceed to route_next after verification passes.**
+</step>
+
+<step name="route_next">
+**Check if milestone complete:**
+
+1. Read ROADMAP.md
+2. Find all phases in current milestone
+3. If current phase is LAST in milestone → Route B (milestone complete)
+4. If more phases remain → Route A (next phase)
+
+---
+
+**Route A: More phases remain**
+
+```
+════════════════════════════════════════
+PHASE {N} COMPLETE
+════════════════════════════════════════
+
+✓ All {X} plans complete
+✓ PROJECT.md evolved
+✓ Ready for next phase
+
+---
+Next: Phase {N+1} — {Name}
+
+[1] Yes, plan Phase {N+1} | [2] Pause here
+════════════════════════════════════════
+```
+
+**Accept:** "1", "yes", "continue" → run `/drive:plan` for Phase N+1
+
+---
+
+**Route B: Milestone complete**
+
+```
+════════════════════════════════════════
+MILESTONE COMPLETE
+════════════════════════════════════════
+
+🎉 {version} is 100% complete — all {N} phases finished!
+
+✓ All phases unified
+✓ PROJECT.md evolved
+✓ Ready for next milestone or release
+
+---
+What's next?
+
+[1] Start next milestone | [2] Review accomplishments | [3] Pause here
+════════════════════════════════════════
+```
+
+</step>
+
+</process>
+
+<output>
+- PROJECT.md evolved with validated/invalidated requirements
+- STATE.md updated for new phase
+- ROADMAP.md marked complete
+- Stale handoffs cleaned
+- Git commit created for phase: feat({phase}): {description}
+- Feature branches merged if applicable
+- User routed to next phase or milestone
+</output>
+
+<success_criteria>
+- [ ] Phase PLAN/SUMMARY count verified
+- [ ] Stale handoffs cleaned
+- [ ] PROJECT.md evolved (requirements, decisions)
+- [ ] STATE.md updated (position, context, session)
+- [ ] ROADMAP.md marked complete
+- [ ] Feature branches merged (if any)
+- [ ] Git commit created for phase
+- [ ] **STATE CONSISTENCY VERIFIED** (all three files aligned - BLOCKING)
+- [ ] User knows next steps with quick continuation
+</success_criteria>

package/modules/drive/src/workflows/unify-phase.md

@@ -0,0 +1,290 @@
+<purpose>
+Reconcile what was planned vs. what was built. Create SUMMARY.md documenting results, update STATE.md with new position, and close the loop to prepare for next PLAN.
+</purpose>
+
+<when_to_use>
+- APPLY phase complete (all tasks executed or documented)
+- Ready to close the current loop
+- Need to record what was built for future reference
+</when_to_use>
+
+<loop_context>
+Expected phase: UNIFY
+Prior phase: APPLY (execution complete)
+Next phase: PLAN (next plan or next phase)
+</loop_context>
+
+<required_reading>
+@.drive/STATE.md
+@.drive/phases/{phase}/{plan}-PLAN.md
+</required_reading>
+
+<references>
+@~/.claude/drive-framework/references/loop-phases.md
+@~/.claude/drive-framework/templates/SUMMARY.md
+@~/.claude/drive-framework/workflows/transition-phase.md (loaded when last plan in phase)
+</references>
+
+<process>
+
+<step name="gather_results" priority="first">
+1. Read PLAN.md to refresh:
+   - Original acceptance criteria
+   - Expected outputs
+   - Task definitions
+2. **Detect plan track:**
+   - If PLAN.md has no `<boundaries>` section AND has a single task → `is_quick_fix = true`
+   - Otherwise → `is_quick_fix = false`
+3. Recall execution from APPLY phase:
+   - Which tasks completed successfully (with qualify results if E/Q was active)
+   - Which tasks failed (if any)
+   - Which checkpoints were resolved and how
+   - Any deviations from the plan
+   - Escalation statuses used (DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED)
+</step>
+
+<step name="compare_plan_vs_actual">
+1. For each acceptance criterion:
+   - Was it satisfied? (PASS/FAIL)
+   - Evidence of satisfaction
+2. For each task:
+   - Did it complete as specified?
+   - Any modifications to approach?
+3. Note deviations:
+   - What differed from plan
+   - Why it differed
+   - Impact on outcomes
+</step>
+
+<step name="audit_skill_invocations">
+**Check specialized workflow usage (if configured):**
+
+1. Check if .drive/SPECIAL-FLOWS.md exists:
+   ```bash
+   ls .drive/SPECIAL-FLOWS.md 2>/dev/null
+   ```
+
+2. If not exists: Skip this step entirely
+
+3. If exists:
+   a. Read SPECIAL-FLOWS.md
+   b. For each skill with priority "required":
+      - Check if skill was invoked during this APPLY phase
+      - Mark as ✓ (invoked) or ○ (gap)
+   c. If any gaps found:
+      - Add to STATE.md Deviations section:
+        ```markdown
+        ### Skill Audit (Phase [N])
+        | Expected | Invoked | Notes |
+        |----------|---------|-------|
+        | /skill-name | ○ | [reason if known] |
+        ```
+      - Warn user: "Skill gap(s) documented in STATE.md. Review before next phase."
+   d. Do NOT block UNIFY for skill gaps (warn only)
+
+4. If all required skills invoked:
+   - Note in SUMMARY.md: "Skill audit: All required skills invoked ✓"
+
+**Reference:** @references/specialized-workflow-integration.md
+</step>
+
+<step name="create_summary">
+Create SUMMARY.md at `.drive/phases/{phase}/{plan}-SUMMARY.md`
+
+**If `is_quick_fix = true` — compressed SUMMARY:**
+
+```markdown
+---
+phase: NN-name
+plan: NN
+completed: ISO timestamp
+duration: Xmin
+---
+
+# Phase [X] Plan [Y]: [Name] Summary
+
+**[One-liner: what changed]**
+
+## AC Result
+
+| Criterion | Status |
+|-----------|--------|
+| AC-1: [Name] | Pass / Fail |
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+| [path] | [Created/Modified — brief] |
+
+---
+*Completed: [date]*
+```
+
+Skip: detailed deviations, decisions, next-phase-readiness, issues, performance metrics, task commits. The quick-fix loop is lightweight end-to-end.
+
+**If `is_quick_fix = false` — full SUMMARY:**
+
+Include all standard sections:
+
+   **Frontmatter:**
+   ```yaml
+   ---
+   phase: NN-name
+   plan: NN
+   completed: ISO timestamp
+   duration: approximate time
+   ---
+   ```
+
+   **Sections:**
+   - Objective (brief restatement)
+   - What Was Built (table: file, purpose, lines)
+   - Acceptance Criteria Results (table: AC, description, status)
+   - Verification Results (command outputs)
+   - Deviations (if any, with explanations)
+   - Key Patterns/Decisions (if any emerged)
+   - Next Phase (what comes next)
+</step>
+
+<step name="update_state">
+1. Update STATE.md:
+
+   **Current Position:**
+   - Phase: N of M - Complete (or In Progress if more plans)
+   - Plan: complete
+   - Status: Ready for next PLAN
+   - Last activity: timestamp
+
+   **Progress:**
+   - Update milestone percentage
+   - Update phase percentage (100% if complete)
+
+   **Loop Position:**
+   ```
+   PLAN ──▶ APPLY ──▶ UNIFY
+     ✓        ✓        ✓     [Loop complete - ready for next PLAN]
+   ```
+
+   **Session Continuity:**
+   - Update stopped at
+   - Update next action
+   - Update resume file (point to SUMMARY)
+</step>
+
+<step name="sync_paul_json">
+**Sync satellite manifest (drive.json):**
+
+1. Check if `.drive/drive.json` exists:
+   ```bash
+   ls .drive/drive.json 2>/dev/null
+   ```
+2. If not found: skip silently (pre-v1.1 project)
+3. If found: read current drive.json and update:
+   - `phase.number` → current phase number from STATE.md
+   - `phase.name` → current phase name from STATE.md
+   - `phase.status` → "complete" if phase done, "in_progress" if more plans remain
+   - `loop.plan` → null (loop just closed)
+   - `loop.position` → "IDLE"
+   - `timestamps.updated_at` → current ISO timestamp
+4. Write updated drive.json back
+</step>
+
+<step name="check_phase_completion">
+**Determine if this is the last plan in the phase:**
+
+1. Count PLAN.md files in current phase directory
+2. Count SUMMARY.md files (including the one just created)
+3. Compare counts:
+   - If PLAN count = SUMMARY count → Last plan, trigger transition
+   - If PLAN count > SUMMARY count → More plans remain in phase
+</step>
+
+<step name="route_based_on_completion">
+**If more plans remain in phase:**
+
+Report with quick continuation:
+```
+════════════════════════════════════════
+LOOP COMPLETE
+════════════════════════════════════════
+
+Plan: {NN}-{plan} — [description]
+[summary of what was built]
+[deviations if any]
+
+Phase {N} progress: {X}/{Y} plans complete
+
+---
+Continue to next plan?
+
+[1] Yes, plan {NN+1} | [2] Pause here
+════════════════════════════════════════
+```
+
+**Accept:** "1", "yes", "continue" → run `/drive:plan` for next plan in same phase
+</step>
+
+<step name="execute_transition" priority="required" gate="blocking">
+**If last plan in phase — TRANSITION IS MANDATORY:**
+
+⚠️ **NEVER skip this step. This is what makes Drive a system, not random loops.**
+
+1. Announce clearly:
+   ```
+   ════════════════════════════════════════
+   PHASE {N} COMPLETE — TRANSITION REQUIRED
+   ════════════════════════════════════════
+   ```
+
+2. **MUST read and execute:** @~/.claude/drive-framework/workflows/transition-phase.md
+
+3. Transition handles (do not skip any):
+   - Evolve PROJECT.md (requirements validated → shipped)
+   - Update ROADMAP.md (phase status → complete)
+   - Git commit for phase: `feat({phase}): {description}`
+   - Clean stale handoffs
+   - Route to next phase or milestone completion
+
+4. **Only after transition completes** → offer next phase routing
+
+**Anti-pattern:** Closing UNIFY and immediately offering `/drive:plan` for next phase WITHOUT running transition. This breaks system cohesion and skips git commits.
+</step>
+
+</process>
+
+<output>
+- SUMMARY.md at `.drive/phases/{phase}/{plan}-SUMMARY.md`
+- Updated STATE.md
+- Updated ROADMAP.md (if phase complete)
+</output>
+
+<error_handling>
+**APPLY not complete:**
+- Check STATE.md for actual position
+- If APPLY incomplete, cannot UNIFY
+- Return to APPLY to complete or document blockers
+
+**Missing execution context:**
+- If no memory of execution results, read any logs
+- Ask user to confirm what was completed
+- Document uncertainty in SUMMARY.md
+
+**PLAN.md missing:**
+- Cannot reconcile without original plan
+- Ask user to locate or reconstruct
+</error_handling>
+
+<anti_patterns>
+**Skipping SUMMARY:**
+Every completed plan MUST have a SUMMARY.md. No exceptions.
+
+**Partial state updates:**
+Update ALL of: SUMMARY, STATE, ROADMAP (if phase done). Don't leave partial.
+
+**Vague summaries:**
+"It worked" is not a summary. Document files, AC results, deviations specifically.
+
+**Forgetting loop position:**
+Always show the visual loop position in STATE.md.
+</anti_patterns>