agileflow 2.84.2 → 2.86.0

package/scripts/test-session-boundary.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * test-session-boundary.js - Test session boundary hook logic
+ *
+ * Usage:
+ *   node test-session-boundary.js --active=/path/to/session --file=/path/to/file
+ *
+ * Examples:
+ *   node test-session-boundary.js --active=/home/coder/project-bugfix --file=/home/coder/project-bugfix/src/App.tsx
+ *   → ALLOWED (file is inside active session)
+ *
+ *   node test-session-boundary.js --active=/home/coder/project-bugfix --file=/home/coder/project/src/App.tsx
+ *   → BLOCKED (file is outside active session)
+ */
+
+const path = require('path');
+
+// Parse arguments
+const args = process.argv.slice(2);
+let activeSessionPath = null;
+let filePath = null;
+
+for (const arg of args) {
+  if (arg.startsWith('--active=')) {
+    activeSessionPath = arg.slice('--active='.length);
+  } else if (arg.startsWith('--file=')) {
+    filePath = arg.slice('--file='.length);
+  }
+}
+
+// Show usage if missing args
+if (!activeSessionPath || !filePath) {
+  console.log(`
+Session Boundary Hook Tester
+
+Usage:
+  node test-session-boundary.js --active=<session_path> --file=<file_path>
+
+Examples:
+  # File INSIDE active session (should be ALLOWED)
+  node test-session-boundary.js \\
+    --active=/home/coder/project-bugfix \\
+    --file=/home/coder/project-bugfix/src/App.tsx
+
+  # File OUTSIDE active session (should be BLOCKED)
+  node test-session-boundary.js \\
+    --active=/home/coder/project-bugfix \\
+    --file=/home/coder/project/src/App.tsx
+`);
+  process.exit(0);
+}
+
+// Normalize paths
+const normalizedActive = path.resolve(activeSessionPath);
+const normalizedFile = path.resolve(filePath);
+
+console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+console.log('Session Boundary Check');
+console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+
+console.log(`Active Session Path: ${normalizedActive}`);
+console.log(`File Being Edited:   ${normalizedFile}`);
+console.log('');
+
+// Check if file is within active session path
+const isInsideSession = normalizedFile.startsWith(normalizedActive + path.sep) ||
+                        normalizedFile === normalizedActive;
+
+if (isInsideSession) {
+  console.log('✅ ALLOWED - File is inside the active session directory');
+  console.log('');
+  console.log('The hook would exit(0) and allow this edit.');
+} else {
+  console.log('❌ BLOCKED - File is OUTSIDE the active session directory!');
+  console.log('');
+  console.log('The hook would exit(2) and block this edit with message:');
+  console.log(`  "Edit blocked: ${normalizedFile} is outside active session ${normalizedActive}"`);
+}
+
+console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');

package/src/core/agents/mentor.md

@@ -447,8 +447,46 @@ Before implementing, evaluate task complexity:
 3. Design implementation approach
 4. Present plan with file paths and steps
 5. Clarify decisions with user
-6. Get approval → `ExitPlanMode`
-7. Implement the approved plan
+6. **PLAN REVIEW CHECKPOINT** (see below)
+7. Get approval → `ExitPlanMode`
+8. Implement the approved plan
+
+### Plan Review Checkpoint (CRITICAL)
+
+**Before transitioning from plan → implement, ALWAYS display:**
+
+```markdown
+---
+
+## Plan Review Checkpoint
+
+**Leverage Reminder:**
+```
+Bad line of code        = 1 bad line
+Bad part of plan        = 100+ bad lines
+Bad line of research    = entire direction is hosed
+```
+
+Take time to review this plan. A few minutes now saves hours later.
+
+**Review Checklist:**
+- [ ] Does this approach make sense for the codebase?
+- [ ] Are there simpler alternatives?
+- [ ] Will this cause breaking changes?
+- [ ] Are edge cases covered?
+
+**Approve plan and proceed to implementation?**
+```
+
+**Why this matters:**
+- Plans are the highest-leverage checkpoint for human review
+- Catching a bad approach before coding saves 100s of lines of rework
+- This is where to invest review time (not code review)
+
+**Options to present:**
+1. **Approve** - Proceed to implementation
+2. **Iterate** - Modify the plan first
+3. **Research** - Need more context before deciding
 
 **Plan Quality Checklist**:
 - [ ] Explored relevant codebase

package/src/core/agents/orchestrator.md

@@ -106,7 +106,7 @@ RULE #4: SYNTHESIS REQUIREMENTS
 3. Collect ALL results before synthesizing
 4. Always flag conflicts in final answer
 5. Provide recommendation with rationale
-6. 🧪 EXPERIMENTAL: For quality gates (coverage ≥ X%, tests pass), use nested loops - see "NESTED LOOP MODE" section
+6. For quality gates (coverage ≥ X%, tests pass), use nested loops - see "NESTED LOOP MODE" section
 
 <!-- COMPACT_SUMMARY_END -->
 
@@ -459,10 +459,12 @@ Proceed with integration?
 
 ---
 
-## NESTED LOOP MODE (Experimental)
+## NESTED LOOP MODE
 
 When agents need to iterate until quality gates pass, use **nested loops**. Each agent runs its own isolated loop with quality verification.
 
+> **Status**: Stable (v2.85+). Thread type: `big` (B-thread). See [Thread-Based Engineering](../../02-practices/thread-based-engineering.md).
+
 ### When to Use
 
 | Scenario | Use Nested Loops? |
@@ -621,3 +623,34 @@ If an agent loop fails:
 - Consider if 80% is achievable
 - May need to reduce threshold or add more test cases
 ```
+
+### Troubleshooting Nested Loops
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Agent never starts loop | Loop ID not passed in prompt | Ensure `--loop-id=xyz` is included in prompt instructions |
+| Gate always fails | Wrong threshold | Check `--threshold` matches realistic target |
+| Timeout exceeded | Complex work | Increase timeout or split into smaller loops |
+| Regression abort | Flaky tests | Fix test flakiness before using coverage gate |
+| Max iterations reached | Insufficient changes | Review agent's iteration logs for patterns |
+| "Loop not found" error | --init not run | Agent must run `--init` before `--check` |
+
+**Debugging commands:**
+```bash
+# View all active loops
+cat .agileflow/state/loops.json
+
+# View loop history for specific ID
+node .agileflow/scripts/agent-loop.js --history --loop-id=abc12345
+
+# Force abort a stuck loop
+node .agileflow/scripts/agent-loop.js --abort --loop-id=abc12345
+
+# Clear all loops (reset)
+rm .agileflow/state/loops.json
+```
+
+**Common patterns:**
+- **Coverage stalls at 70%**: Usually means edge cases aren't tested. Agent needs clearer guidance on what to cover.
+- **Visual verification loops forever**: Ensure screenshots use `verified-` prefix convention.
+- **Type gate fails repeatedly**: Check for implicit `any` types or missing declarations.