agileflow 2.94.1 → 2.95.1

package/src/core/commands/retro.md

@@ -710,6 +710,82 @@ OUTPUT
 
 ---
 
+## Expected Output
+
+### Success - Retrospective Report
+
+```
+🔄 Sprint 12 Retrospective
+══════════════════════════════════════════════════════════════
+Period: 2026-01-15 to 2026-01-29
+
+📊 SPRINT METRICS
+┌────────────────────────────────────────────────────────────┐
+│ Planned: 15 stories (42 points)                            │
+│ Completed: 13 stories (38 points)                          │
+│ Carry-over: 2 stories (4 points)                           │
+│ Velocity: 90% of commitment                                │
+└────────────────────────────────────────────────────────────┘
+
+🟢 START (What should we start doing?)
+- [ ] Daily async standups in bus
+- [ ] Earlier blocker escalation
+- [ ] Pair programming for complex stories
+
+🔴 STOP (What should we stop doing?)
+- [ ] Skipping AC verification before done
+- [ ] Starting stories without clear requirements
+
+🟡 CONTINUE (What's working well?)
+- [x] Test-first development (reduced bugs 40%)
+- [x] Using /babysit for mentored workflows
+- [x] Clear acceptance criteria format
+
+🎉 WINS
+- Shipped OAuth integration ahead of schedule
+- Zero production bugs this sprint
+- Team collaboration improved significantly
+
+📈 PREDICTIONS
+- Next sprint velocity: ~40 points
+- Risk: US-0055 may need external help
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ Retrospective saved to docs/08-project/retrospectives/
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Success - Quick Retro
+
+```
+🔄 Quick Retrospective
+══════════════════════════════════════════════════════════════
+
+Based on sprint data:
+🟢 Win: 90% velocity achieved
+🟡 Watch: 2 stories carried over
+🔴 Risk: Blocker detection was slow
+
+Top action item:
+→ Add daily blocker check to routine
+
+Full retro? /agileflow:retro DEPTH=full
+```
+
+### Error - No Sprint Data
+
+```
+❌ Error: No sprint data available
+
+No completed stories found in the last 14 days.
+
+Options:
+1. Start tracking: /agileflow:sprint ACTION=start
+2. Specify range: /agileflow:retro RANGE="2026-01-01..2026-01-15"
+```
+
+---
+
 ## Related Commands
 
 - `/agileflow:sprint` - Sprint planning

package/src/core/commands/review.md

@@ -588,6 +588,78 @@ OUTPUT
 
 ---
 
+## Expected Output
+
+### Success - Code Review
+
+```
+🔍 Code Review: src/api/auth.js
+══════════════════════════════════════════════════════════════
+
+Analyzing 127 lines changed across 3 files...
+
+📊 Quality Score: 85/100 🟢
+
+🔴 CRITICAL (1)
+┌──────────────────────────────────────────────────────────────┐
+│ Line 45: SQL injection vulnerability                         │
+│ `query("SELECT * FROM users WHERE id = " + userId)`         │
+│                                                              │
+│ Fix: Use parameterized query                                 │
+│ `query("SELECT * FROM users WHERE id = $1", [userId])`      │
+└──────────────────────────────────────────────────────────────┘
+
+🟡 WARNINGS (3)
+│ Line 23: Missing error handling for async operation          │
+│ Line 67: Magic number - consider named constant              │
+│ Line 89: Duplicate logic - extract to helper                 │
+
+🟢 GOOD PRACTICES
+│ ✓ Consistent naming conventions                              │
+│ ✓ Good test coverage (87%)                                   │
+│ ✓ Clear function documentation                               │
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Summary: 1 critical, 3 warnings, 3 good
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Apply auto-fixes for non-critical issues? [Y/n]
+```
+
+### Success - Clean Review
+
+```
+🔍 Code Review: src/utils/format.js
+══════════════════════════════════════════════════════════════
+
+📊 Quality Score: 98/100 🟢
+
+✅ No issues found!
+
+Good practices detected:
+- Clean function signatures
+- Comprehensive error handling
+- Well-documented edge cases
+- 95% test coverage
+
+LGTM! Ready for merge.
+```
+
+### Error - File Not Found
+
+```
+❌ Error: Cannot review - file not found
+
+Path: src/api/authh.js
+
+Did you mean: src/api/auth.js?
+
+Or review all changed files:
+/agileflow:review SCOPE=staged
+```
+
+---
+
 ## Related Commands
 
 - `/agileflow:pr` - Generate pull request description

package/src/core/commands/rlm.md

@@ -347,6 +347,89 @@ For smaller research notes, `/agileflow:research:view` may be sufficient.
 
 ---
 
+## Expected Output
+
+### Success - Document Analysis
+
+```
+📄 RLM Document Analysis
+══════════════════════════════════════════════════════════════
+
+Document: docs/research/api-design-guide.pdf (156 pages)
+Question: What authentication methods are recommended?
+
+Launching RLM sub-agent...
+✓ Document loaded (2.3 MB)
+✓ Virtualized as 47 chunks
+✓ Cost estimate: $0.12
+
+Iteration 1/5: Searching for authentication...
+  Found: Chapter 4 "Security", pages 45-62
+
+Iteration 2/5: Extracting relevant sections...
+  Found: 3 authentication patterns described
+
+Iteration 3/5: Synthesizing answer...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📖 Answer
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+The guide recommends three authentication methods:
+
+1. **JWT Tokens** (Primary)
+   - For API-to-API communication
+   - 15-minute expiry with refresh tokens
+
+2. **OAuth 2.0** (External Users)
+   - For third-party integrations
+   - Support Google and GitHub providers
+
+3. **API Keys** (Internal Services)
+   - For trusted internal services
+   - Rotate every 90 days
+
+Source: Pages 47-52, Chapter 4 "Security"
+Confidence: High (direct quotes available)
+Cost: $0.08 (3 iterations)
+```
+
+### Success - Multi-Document Synthesis
+
+```
+📄 RLM Cross-Document Analysis
+══════════════════════════════════════════════════════════════
+
+Documents: 3 research papers
+Question: Compare approaches to rate limiting
+
+Processing...
+[============================] 100%
+
+Synthesis:
+All three papers recommend token bucket algorithm.
+Key difference: Paper A suggests per-user limits,
+Paper B recommends per-endpoint limits.
+
+See full comparison: .agileflow/research/synthesis-001.md
+```
+
+### Error - Document Too Large
+
+```
+⚠️ Document exceeds RLM budget
+
+File: enterprise-guide.pdf (500 pages)
+Estimated cost: $2.50
+
+Options:
+1. Increase budget: BUDGET=3.00
+2. Analyze specific pages: PAGES=1-50
+3. Use summary mode: MODE=summary
+```
+
+---
+
 ## Related Commands
 
 - `/agileflow:research:analyze` - Analyze research notes (uses RLM for large docs)

package/src/core/commands/rpi.md

@@ -502,6 +502,96 @@ Human review should focus on highest leverage points:
 
 ---
 
+## Expected Output
+
+### Success - RPI Workflow
+
+```
+🔄 RPI Workflow: User Authentication Feature
+══════════════════════════════════════════════════════════════
+
+Phase 1: RESEARCH (Current)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Gathering context...
+✓ Read existing auth code (src/api/auth.js)
+✓ Analyzed 3 related components
+✓ Reviewed security requirements
+✓ Checked team patterns (JWT preferred)
+
+Research Summary:
+- Current: Basic session auth
+- Target: JWT with refresh tokens
+- Patterns: Use existing middleware structure
+- Risks: Token storage, refresh logic
+
+Ready for planning phase? [Y/n]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Phase 2: PLAN
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Proposed Implementation:
+1. Add JWT generation in auth.js
+2. Create refresh token middleware
+3. Update login endpoint
+4. Add token validation
+5. Write tests (unit + integration)
+
+Files to modify: 4
+New files: 2
+Estimated complexity: Medium
+
+Approve plan and proceed to implement? [Y/n]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Phase 3: IMPLEMENT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Implementing...
+✓ Updated src/api/auth.js
+✓ Created src/middleware/jwt.js
+✓ Created src/utils/tokens.js
+✓ Added 12 tests (all passing)
+
+🎉 Implementation complete!
+```
+
+### Success - Phase Transition
+
+```
+🔄 RPI Phase Transition
+══════════════════════════════════════════════════════════════
+
+Current: RESEARCH → Next: PLAN
+
+⚠️ Context Health: 65% (approaching threshold)
+
+Before transitioning:
+1. Document key findings
+2. Save research notes
+3. Plan is LEVERAGE - quality > speed now
+
+Proceed with transition? [Y/n]
+```
+
+### Error - Wrong Phase
+
+```
+❌ Error: Cannot implement without planning
+
+Current phase: RESEARCH
+
+Complete the workflow in order:
+1. RESEARCH ✅ (current)
+2. PLAN ⏳
+3. IMPLEMENT ⏳
+
+Skip to plan: /agileflow:rpi PHASE=plan
+```
+
+---
+
 ## Related Documentation
 
 - [Context Engineering RPI Practice](../../docs/02-practices/context-engineering-rpi.md)

package/src/core/commands/session/cleanup.md

@@ -7,14 +7,20 @@ compact_context:
     - "ACTIVE COMMAND: /agileflow:session:cleanup - Review and clean up sessions"
     - "Walk through EACH session with issues one-by-one"
     - "Show file changes with AI assessment (SAFE/IMPORTANT)"
+    - "Check merge eligibility with: node .agileflow/scripts/session-manager.js check-merge {id}"
+    - "Merge options: canMerge (mergeable or hasConflicts), uncommittedInSession (cannot merge)"
     - "Use AskUserQuestion for EACH session with recommended action"
-    - "Recommended action based on allTrivial flag from health --detailed"
-    - "Track: deleted count, kept count, skipped count"
+    - "If SAFE+mergeable: Delete(Rec) / Merge&Delete / Keep / Stop"
+    - "If IMPORTANT+mergeable: Merge&Delete(Rec) / Keep / Delete anyway / Stop"
+    - "If cannot merge: show warning, offer Switch to session option"
+    - "Merge execution: session-manager.js integrate {id} --strategy=squash --deleteBranch=true --deleteWorktree=true"
+    - "Track: deleted count, merged count, kept count, skipped count"
   state_fields:
     - health_report
     - current_session_index
     - total_sessions
     - deleted_count
+    - merged_count
     - kept_count
 ---
 
@@ -29,8 +35,9 @@ Interactive session cleanup - review each session with health issues and decide
 When you have forgotten sessions with uncommitted changes, stale entries, or orphaned worktrees, this command:
 - Shows you what changed in each session
 - Analyzes whether changes are important or trivial
+- Checks if changes can be merged to main before deletion
 - Provides AI recommendation for each session
-- Lets you decide one-by-one what to clean up
+- Lets you decide one-by-one what to clean up (including merge-and-delete option)
 
 ---
 
@@ -87,6 +94,19 @@ For each file in `fileDetails`:
 - `??` status: `   ?? {file}` and if `existsInMain: true` add `(exists in main)`
 - Other: `   {status} {file}`
 
+#### Step 3b2: Check Merge Eligibility
+
+```bash
+node .agileflow/scripts/session-manager.js check-merge {session_id}
+```
+
+Parse the JSON response and set flags:
+- `canMerge`: true if `mergeable: true` OR `hasConflicts: true` (can attempt merge)
+- `hasConflicts`: true if response contains `hasConflicts: true`
+- `uncommittedInSession`: true if `reason === "uncommitted_changes"`
+- `noChanges`: true if `reason === "no_changes"`
+- `commitsAhead`: number of commits to merge (from response)
+
 #### Step 3c: Display AI Assessment
 
 If `allTrivial` is true:
@@ -101,9 +121,35 @@ If `allTrivial` is false:
    This session has unique changes that may be valuable.
 ```
 
+**Add merge status line based on flags from Step 3b2:**
+
+If `canMerge` and NOT `hasConflicts`:
+```
+   ✓ Can be merged to main cleanly ({commitsAhead} commit(s))
+```
+
+If `hasConflicts`:
+```
+   ⚠️ Has merge conflicts (auto-resolve available)
+```
+
+If `uncommittedInSession`:
+```
+   ❌ Cannot merge - has uncommitted changes in session
+```
+
+If `noChanges`:
+```
+   ○ Nothing to merge - no committed changes different from main
+```
+
 #### Step 3d: Ask User with AskUserQuestion
 
-**If SAFE (allTrivial: true):**
+Choose option set based on assessment (allTrivial) and merge eligibility:
+
+---
+
+**Option Set A: SAFE + Mergeable (allTrivial: true AND canMerge: true)**
 ```
 AskUserQuestion:
   question: "Session {id} - What would you like to do?"
@@ -112,21 +158,87 @@ AskUserQuestion:
   options:
     - label: "Delete session (Recommended)"
       description: "Remove session and worktree - no unique work"
+    - label: "Merge and delete"
+      description: "Merge {commitsAhead} commit(s) to main, then delete session"
     - label: "Keep this session"
       description: "Leave it as-is"
     - label: "Stop cleanup"
       description: "Exit and show summary"
 ```
 
-**If IMPORTANT (allTrivial: false):**
+---
+
+**Option Set B: IMPORTANT + Mergeable (allTrivial: false AND canMerge: true)**
 ```
 AskUserQuestion:
   question: "Session {id} - What would you like to do?"
   header: "Cleanup"
   multiSelect: false
   options:
-    - label: "Keep this session (Recommended)"
-      description: "Preserve unique work"
+    - label: "Merge and delete (Recommended)"
+      description: "Preserve {commitsAhead} commit(s) to main, then clean up session"
+    - label: "Keep this session"
+      description: "Leave session for continued work"
+    - label: "Delete anyway"
+      description: "Remove session and lose changes"
+    - label: "Stop cleanup"
+      description: "Exit and show summary"
+```
+
+---
+
+**Option Set C: Cannot Merge - Uncommitted in Session (uncommittedInSession: true)**
+```
+⚠️ Session has uncommitted changes that prevent merging.
+   Commit or discard changes first to enable merge option.
+
+AskUserQuestion:
+  question: "Session {id} cannot be merged. What would you like to do?"
+  header: "Cleanup"
+  multiSelect: false
+  options:
+    - label: "Switch to session to commit"
+      description: "Open this session so you can commit changes"
+    - label: "Keep this session"
+      description: "Leave it as-is for later"
+    - label: "Delete anyway"
+      description: "Remove session and lose all changes"
+    - label: "Stop cleanup"
+      description: "Exit and show summary"
+```
+
+---
+
+**Option Set D: SAFE + No Merge Needed (allTrivial: true AND noChanges: true)**
+```
+AskUserQuestion:
+  question: "Session {id} - What would you like to do?"
+  header: "Cleanup"
+  multiSelect: false
+  options:
+    - label: "Delete session (Recommended)"
+      description: "Remove session and worktree - nothing to preserve"
+    - label: "Keep this session"
+      description: "Leave it as-is"
+    - label: "Stop cleanup"
+      description: "Exit and show summary"
+```
+
+---
+
+**Option Set E: Has Conflicts (hasConflicts: true)**
+```
+⚠️ Merge has conflicts with main branch.
+
+AskUserQuestion:
+  question: "Session {id} has merge conflicts. What would you like to do?"
+  header: "Cleanup"
+  multiSelect: false
+  options:
+    - label: "Auto-resolve and merge"
+      description: "Attempt smart conflict resolution, then merge and delete"
+    - label: "Keep for manual merge"
+      description: "Leave session to resolve conflicts yourself"
     - label: "Delete anyway"
       description: "Remove session and lose changes"
     - label: "Stop cleanup"
@@ -135,7 +247,7 @@ AskUserQuestion:
 
 #### Step 3e: Execute User Choice
 
-**If "Delete" chosen:**
+**If "Delete session" or "Delete anyway" chosen:**
 ```bash
 node .agileflow/scripts/session-manager.js delete {session_id} --remove-worktree
 ```
@@ -143,10 +255,83 @@ node .agileflow/scripts/session-manager.js delete {session_id} --remove-worktree
 Display: `✓ Session {id} deleted`
 Increment deleted_count.
 
-**If "Keep" chosen:**
+---
+
+**If "Merge and delete" chosen:**
+
+1. Run integrate with cleanup flags:
+```bash
+node .agileflow/scripts/session-manager.js integrate {session_id} --strategy=squash --deleteBranch=true --deleteWorktree=true
+```
+
+2. Parse the response to get merge result.
+
+3. Display result:
+```
+✓ Session {id} merged to main and deleted
+  Commits: {originalCount} → 1 (squashed)
+  Branch: {branch} (deleted)
+```
+
+Increment merged_count.
+
+---
+
+**If "Auto-resolve and merge" chosen (for conflict cases):**
+
+1. First run smart-merge to resolve conflicts:
+```bash
+node .agileflow/scripts/session-manager.js smart-merge {session_id} --strategy=squash
+```
+
+2. Check result - if conflicts remain, display error and keep session:
+```
+❌ Could not auto-resolve conflicts for session {id}
+   Consider manual merge or delete.
+```
+Increment kept_count and continue to next session.
+
+3. If smart-merge succeeds, run integrate:
+```bash
+node .agileflow/scripts/session-manager.js integrate {session_id} --strategy=squash --deleteBranch=true --deleteWorktree=true
+```
+
+4. Display result:
+```
+✓ Session {id} conflicts resolved, merged to main, and deleted
+  Commits: {originalCount} → 1 (squashed)
+  Branch: {branch} (deleted)
+```
+
+Increment merged_count.
+
+---
+
+**If "Switch to session to commit" chosen:**
+
+1. Display instructions:
+```
+Switching to session {id}...
+
+After committing your changes, run /agileflow:session:cleanup again
+to continue cleanup with merge option available.
+```
+
+2. Switch to the session:
+```bash
+node .agileflow/scripts/session-manager.js switch {session_id}
+```
+
+3. Exit cleanup (do NOT continue to next session - user needs to work in session).
+
+---
+
+**If "Keep this session" or "Keep for manual merge" chosen:**
 Display: `→ Session {id} kept`
 Increment kept_count.
 
+---
+
 **If "Stop cleanup" chosen:**
 Go to Step 6 (Final Summary).
 
@@ -219,13 +404,16 @@ git worktree remove --force "{path}"
 Session Cleanup Complete
 ═══════════════════════════════════════════════════════════════
 
-   ✓ Deleted: {deleted_count} session(s)
-   → Kept:    {kept_count} session(s)
-   ○ Skipped: {skipped_count} item(s)
+   ✓ Deleted:    {deleted_count} session(s)
+   ✓ Merged:     {merged_count} session(s) → changes preserved in main
+   → Kept:       {kept_count} session(s)
+   ○ Skipped:    {skipped_count} item(s)
 
 Run /agileflow:session:status to see remaining sessions.
 ```
 
+Note: Only display "Merged" line if merged_count > 0.
+
 ---
 
 ## Edge Cases
@@ -241,6 +429,20 @@ Show partial summary with what was processed.
 ### Main Session Protection
 The health check already excludes main session, so it won't appear in cleanup list.
 
+### Merge Fails
+If integrate command fails (e.g., unexpected error), display:
+```
+❌ Merge failed for session {id}: {error}
+   Session preserved. Try manual merge with /agileflow:session:end
+```
+Keep the session and continue to next.
+
+### check-merge Command Not Available
+If the `check-merge` command is not available (older session-manager.js), fall back to original behavior without merge options. Set `canMerge: false` for all sessions.
+
+### Switched to Session Mid-Cleanup
+When user selects "Switch to session to commit", cleanup exits immediately. The summary shows partial progress. User can run `/agileflow:session:cleanup` again after committing.
+
 ---
 
 ## Related Commands