agileflow 2.85.0 → 2.87.0

package/scripts/obtain-context.js

@@ -26,8 +26,67 @@ const { isValidCommandName } = require('../lib/validate');
 // Summary table should be the LAST thing visible before truncation.
 const DISPLAY_LIMIT = 29200;
 
-// Optional: Register command for PreCompact context preservation
+// =============================================================================
+// Progressive Disclosure: Section Activation
+// =============================================================================
+
+/**
+ * Parse command-line arguments and determine which sections to activate.
+ * Sections are conditionally loaded based on parameters like MODE=loop.
+ *
+ * Section mapping:
+ *   - MODE=loop          → activates: loop-mode
+ *   - Multi-session env  → activates: multi-session
+ *   - (Other triggers detected at runtime by the agent)
+ *
+ * @param {string[]} args - Command-line arguments after command name
+ * @returns {Object} { activeSections: string[], params: Object }
+ */
+function parseCommandArgs(args) {
+  const activeSections = [];
+  const params = {};
+
+  for (const arg of args) {
+    // Parse KEY=VALUE arguments
+    const match = arg.match(/^([A-Z_]+)=(.+)$/i);
+    if (match) {
+      const [, key, value] = match;
+      params[key.toUpperCase()] = value;
+    }
+  }
+
+  // Activate sections based on parameters
+  if (params.MODE === 'loop') {
+    activeSections.push('loop-mode');
+  }
+
+  if (params.VISUAL === 'true') {
+    activeSections.push('visual-e2e');
+  }
+
+  // Check for multi-session environment
+  const registryPath = '.agileflow/sessions/registry.json';
+  if (fs.existsSync(registryPath)) {
+    try {
+      const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+      const sessionCount = Object.keys(registry.sessions || {}).length;
+      if (sessionCount > 1) {
+        activeSections.push('multi-session');
+      }
+    } catch {
+      // Silently ignore registry read errors
+    }
+  }
+
+  return { activeSections, params };
+}
+
+// Parse arguments
 const commandName = process.argv[2];
+const commandArgs = process.argv.slice(3);
+const { activeSections, params: commandParams } = parseCommandArgs(commandArgs);
+
+// Register command for PreCompact context preservation
 if (commandName && isValidCommandName(commandName)) {
   const sessionStatePath = 'docs/09-agents/session-state.json';
   if (fs.existsSync(sessionStatePath)) {
@@ -42,11 +101,13 @@ if (commandName && isValidCommandName(commandName)) {
       // Remove any existing entry for this command (avoid duplicates)
       state.active_commands = state.active_commands.filter(c => c.name !== commandName);
 
-      // Add the new command
+      // Add the new command with active sections for progressive disclosure
       state.active_commands.push({
         name: commandName,
         activated_at: new Date().toISOString(),
         state: {},
+        active_sections: activeSections,
+        params: commandParams,
       });
 
       // Remove legacy active_command field (only use active_commands array now)
@@ -262,6 +323,13 @@ function generateSummary() {
     summary += row('⭐ Up Next', readyStories.slice(0, 3).join(', '), C.skyBlue, C.skyBlue);
   }
 
+  // Progressive disclosure: Show active sections
+  if (activeSections.length > 0) {
+    summary += divider();
+    const sectionList = activeSections.join(', ');
+    summary += row('📖 Sections', sectionList, C.cyan, C.mintGreen);
+  }
+
   summary += divider();
 
   // Key files (using vibrant 256-color palette)
@@ -318,6 +386,96 @@ function generateFullContent() {
   content += `${C.lavender}${C.bold}${title}${C.reset}\n`;
   content += `${C.dim}Generated: ${new Date().toISOString()}${C.reset}\n`;
 
+  // 0.5 SESSION CONTEXT BANNER (FIRST - before everything else)
+  // This is critical for multi-session awareness - agents need to know which session they're in
+  const sessionManagerPath = path.join(__dirname, 'session-manager.js');
+  const altSessionManagerPath = '.agileflow/scripts/session-manager.js';
+
+  if (fs.existsSync(sessionManagerPath) || fs.existsSync(altSessionManagerPath)) {
+    const managerPath = fs.existsSync(sessionManagerPath)
+      ? sessionManagerPath
+      : altSessionManagerPath;
+    const sessionStatus = safeExec(`node "${managerPath}" status`);
+
+    if (sessionStatus) {
+      try {
+        const statusData = JSON.parse(sessionStatus);
+        if (statusData.current) {
+          const session = statusData.current;
+          const isMain = session.is_main === true;
+          const sessionName = session.nickname
+            ? `Session ${session.id} "${session.nickname}"`
+            : `Session ${session.id}`;
+
+          content += `\n${C.teal}${C.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}\n`;
+          content += `${C.teal}${C.bold}📍 SESSION CONTEXT${C.reset}\n`;
+          content += `${C.teal}${C.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}\n`;
+
+          if (isMain) {
+            content += `${C.mintGreen}${C.bold}${sessionName}${C.reset} ${C.dim}(main project)${C.reset}\n`;
+          } else {
+            content += `${C.peach}${C.bold}🔀 ${sessionName}${C.reset} ${C.dim}(worktree)${C.reset}\n`;
+            content += `Branch: ${C.skyBlue}${session.branch || 'unknown'}${C.reset}\n`;
+            content += `${C.dim}Path: ${session.path || process.cwd()}${C.reset}\n`;
+          }
+
+          // Show other active sessions prominently
+          if (statusData.otherActive > 0) {
+            content += `${C.amber}⚠️ ${statusData.otherActive} other active session(s)${C.reset} - check story claims below\n`;
+          }
+
+          content += `${C.teal}${C.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}\n\n`;
+        }
+      } catch (e) {
+        // Silently ignore session parse errors - will still show detailed session context later
+      }
+    }
+  }
+
+  // 0.7 INTERACTION MODE (AskUserQuestion) - EARLY for visibility
+  // This MUST appear before other content to ensure Claude sees it
+  const earlyMetadata = safeReadJSON('docs/00-meta/agileflow-metadata.json');
+  const askUserQuestionConfig = earlyMetadata?.features?.askUserQuestion;
+
+  if (askUserQuestionConfig?.enabled) {
+    content += `${C.coral}${C.bold}┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓${C.reset}\n`;
+    content += `${C.coral}${C.bold}┃ 🔔 MANDATORY: AskUserQuestion After EVERY Response      ┃${C.reset}\n`;
+    content += `${C.coral}${C.bold}┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛${C.reset}\n`;
+    content += `${C.bold}After completing ANY task${C.reset} (implementation, fix, etc.):\n`;
+    content += `${C.mintGreen}→ ALWAYS${C.reset} call ${C.skyBlue}AskUserQuestion${C.reset} tool to offer next steps\n`;
+    content += `${C.coral}→ NEVER${C.reset} end with text like "Done!" or "What's next?"\n\n`;
+    content += `${C.dim}Balance: Use at natural pause points. Don't ask permission for routine work.${C.reset}\n\n`;
+  }
+
+  // 0. PROGRESSIVE DISCLOSURE (section activation)
+  if (activeSections.length > 0) {
+    content += `\n${C.cyan}${C.bold}═══ 📖 Progressive Disclosure: Active Sections ═══${C.reset}\n`;
+    content += `${C.dim}The following sections are activated based on command parameters.${C.reset}\n`;
+    content += `${C.dim}Look for <!-- SECTION: name --> markers in the command file.${C.reset}\n\n`;
+
+    activeSections.forEach(section => {
+      content += `  ${C.mintGreen}✓${C.reset} ${C.bold}${section}${C.reset}\n`;
+    });
+
+    // Map sections to their triggers for context
+    const sectionDescriptions = {
+      'loop-mode': 'Autonomous epic execution (MODE=loop)',
+      'multi-session': 'Multi-session coordination detected',
+      'visual-e2e': 'Visual screenshot verification (VISUAL=true)',
+      'delegation': 'Expert spawning patterns (load when spawning)',
+      'stuck': 'Research prompt guidance (load after 2 failures)',
+      'plan-mode': 'Planning workflow details (load when entering plan mode)',
+      'tools': 'Tool usage guidance (load when needed)',
+    };
+
+    content += `\n${C.dim}Section meanings:${C.reset}\n`;
+    activeSections.forEach(section => {
+      const desc = sectionDescriptions[section] || 'Conditional content';
+      content += `  ${C.dim}• ${section}: ${desc}${C.reset}\n`;
+    });
+    content += '\n';
+  }
+
   // 1. GIT STATUS (using vibrant 256-color palette)
   content += `\n${C.skyBlue}${C.bold}═══ Git Status ═══${C.reset}\n`;
   const branch = safeExec('git branch --show-current') || 'unknown';
@@ -376,62 +534,52 @@ function generateFullContent() {
       // Backwards compatibility for old format
       content += `Active command: ${C.skyBlue}${sessionState.active_command.name}${C.reset}\n`;
     }
+
+    // Show batch loop status if active
+    const batchLoop = sessionState.batch_loop;
+    if (batchLoop && batchLoop.enabled) {
+      content += `\n${C.skyBlue}${C.bold}── Batch Loop Active ──${C.reset}\n`;
+      content += `Pattern: ${C.cyan}${batchLoop.pattern}${C.reset}\n`;
+      content += `Action: ${C.cyan}${batchLoop.action}${C.reset}\n`;
+      content += `Current: ${C.lightYellow}${batchLoop.current_item || 'none'}${C.reset}\n`;
+      const summary = batchLoop.summary || {};
+      content += `Progress: ${C.lightGreen}${summary.completed || 0}${C.reset}/${summary.total || 0} `;
+      content += `(${C.lightYellow}${summary.in_progress || 0}${C.reset} in progress)\n`;
+      content += `Iteration: ${batchLoop.iteration || 0}/${batchLoop.max_iterations || 50}\n`;
+    }
   } else {
     content += `${C.dim}No session-state.json found${C.reset}\n`;
   }
 
-  // 4. SESSION CONTEXT (multi-session awareness)
-  content += `\n${C.skyBlue}${C.bold}═══ Session Context ═══${C.reset}\n`;
-  const sessionManagerPath = path.join(__dirname, 'session-manager.js');
-  const altSessionManagerPath = '.agileflow/scripts/session-manager.js';
+  // 4. SESSION CONTEXT (details - banner shown above)
+  // Note: Prominent SESSION CONTEXT banner is shown at the top of output
+  // This section provides additional details for non-main sessions
+  const sessionMgrPath = path.join(__dirname, 'session-manager.js');
+  const altSessionMgrPath = '.agileflow/scripts/session-manager.js';
 
-  if (fs.existsSync(sessionManagerPath) || fs.existsSync(altSessionManagerPath)) {
-    const managerPath = fs.existsSync(sessionManagerPath)
-      ? sessionManagerPath
-      : altSessionManagerPath;
-    const sessionStatus = safeExec(`node "${managerPath}" status`);
+  if (fs.existsSync(sessionMgrPath) || fs.existsSync(altSessionMgrPath)) {
+    const mgrPath = fs.existsSync(sessionMgrPath) ? sessionMgrPath : altSessionMgrPath;
+    const sessionStatusStr = safeExec(`node "${mgrPath}" status`);
 
-    if (sessionStatus) {
+    if (sessionStatusStr) {
       try {
-        const statusData = JSON.parse(sessionStatus);
-        if (statusData.current) {
+        const statusData = JSON.parse(sessionStatusStr);
+        if (statusData.current && !statusData.current.is_main) {
+          // Only show additional details for non-main sessions
+          content += `\n${C.skyBlue}${C.bold}═══ Session Details ═══${C.reset}\n`;
           const session = statusData.current;
-          const isMain = session.is_main === true;
-
-          if (isMain) {
-            content += `Session: ${C.mintGreen}Main project${C.reset} (Session ${session.id || 1})\n`;
-          } else {
-            // NON-MAIN SESSION - Show prominent banner
-            const sessionName = session.nickname
-              ? `${session.id} "${session.nickname}"`
-              : `${session.id}`;
-            content += `${C.teal}${C.bold}🔀 SESSION ${sessionName} (worktree)${C.reset}\n`;
-            content += `Branch: ${C.skyBlue}${session.branch || 'unknown'}${C.reset}\n`;
-            content += `Path: ${C.dim}${session.path || process.cwd()}${C.reset}\n`;
 
-            // Calculate relative path to main
-            const mainPath = process.cwd().replace(/-[^/]+$/, ''); // Heuristic: strip session suffix
-            content += `Main project: ${C.dim}${mainPath}${C.reset}\n`;
+          // Calculate relative path to main
+          const mainPath = process.cwd().replace(/-[^/]+$/, ''); // Heuristic: strip session suffix
+          content += `Main project: ${C.dim}${mainPath}${C.reset}\n`;
 
-            // Remind about merge flow
-            content += `${C.lavender}💡 When done: /agileflow:session:end → merge to main${C.reset}\n`;
-          }
-
-          // Show other active sessions
-          if (statusData.otherActive > 0) {
-            content += `${C.peach}⚠️ ${statusData.otherActive} other session(s) active${C.reset}\n`;
-          }
-        } else {
-          content += `${C.dim}No session registered${C.reset}\n`;
+          // Remind about merge flow
+          content += `${C.lavender}💡 When done: /agileflow:session:end → merge to main${C.reset}\n`;
         }
       } catch (e) {
-        content += `${C.dim}Session manager available but status parse failed${C.reset}\n`;
+        // Silently ignore - banner above has basic info
       }
-    } else {
-      content += `${C.dim}Session manager available${C.reset}\n`;
     }
-  } else {
-    content += `${C.dim}Multi-session not configured${C.reset}\n`;
   }
 
   // 5. STORY CLAIMS (inter-session coordination)
@@ -440,9 +588,7 @@ function generateFullContent() {
 
   if (fs.existsSync(storyClaimingPath) || fs.existsSync(altStoryClaimingPath)) {
     try {
-      const claimPath = fs.existsSync(storyClaimingPath)
-        ? storyClaimingPath
-        : altStoryClaimingPath;
+      const claimPath = fs.existsSync(storyClaimingPath) ? storyClaimingPath : altStoryClaimingPath;
       const storyClaiming = require(claimPath);
 
       // Get stories claimed by other sessions
@@ -451,7 +597,9 @@ function generateFullContent() {
         content += `\n${C.amber}${C.bold}═══ 🔒 Claimed Stories ═══${C.reset}\n`;
         content += `${C.dim}Stories locked by other sessions - pick a different one${C.reset}\n`;
         othersResult.stories.forEach(story => {
-          const sessionDir = story.claimedBy?.path ? path.basename(story.claimedBy.path) : 'unknown';
+          const sessionDir = story.claimedBy?.path
+            ? path.basename(story.claimedBy.path)
+            : 'unknown';
           content += `  ${C.coral}🔒${C.reset} ${C.lavender}${story.id}${C.reset} "${story.title}" ${C.dim}→ Session ${story.claimedBy?.session_id || '?'} (${sessionDir})${C.reset}\n`;
         });
         content += '\n';
@@ -477,9 +625,7 @@ function generateFullContent() {
 
   if (fs.existsSync(fileTrackingPath) || fs.existsSync(altFileTrackingPath)) {
     try {
-      const trackPath = fs.existsSync(fileTrackingPath)
-        ? fileTrackingPath
-        : altFileTrackingPath;
+      const trackPath = fs.existsSync(fileTrackingPath) ? fileTrackingPath : altFileTrackingPath;
       const fileTracking = require(trackPath);
 
       // Get file overlaps with other sessions
@@ -488,10 +634,12 @@ function generateFullContent() {
         content += `\n${C.amber}${C.bold}═══ ⚠️  File Overlaps ═══${C.reset}\n`;
         content += `${C.dim}Files also edited by other sessions - conflicts auto-resolved during merge${C.reset}\n`;
         overlapsResult.overlaps.forEach(overlap => {
-          const sessionInfo = overlap.otherSessions.map(s => {
-            const dir = path.basename(s.path);
-            return `Session ${s.id} (${dir})`;
-          }).join(', ');
+          const sessionInfo = overlap.otherSessions
+            .map(s => {
+              const dir = path.basename(s.path);
+              return `Session ${s.id} (${dir})`;
+            })
+            .join(', ');
           content += `  ${C.amber}⚠${C.reset} ${C.lavender}${overlap.file}${C.reset} ${C.dim}→ ${sessionInfo}${C.reset}\n`;
         });
         content += '\n';
@@ -524,7 +672,8 @@ function generateFullContent() {
   // 6. VISUAL E2E STATUS (detect from metadata or filesystem)
   const metadata = safeReadJSON('docs/00-meta/agileflow-metadata.json');
   const visualE2eConfig = metadata?.features?.visual_e2e;
-  const playwrightExists = fs.existsSync('playwright.config.ts') || fs.existsSync('playwright.config.js');
+  const playwrightExists =
+    fs.existsSync('playwright.config.ts') || fs.existsSync('playwright.config.js');
   const screenshotsExists = fs.existsSync('screenshots');
   const testsE2eExists = fs.existsSync('tests/e2e');
 
@@ -551,35 +700,7 @@ function generateFullContent() {
     content += `${C.dim}  /agileflow:configure → Visual E2E testing${C.reset}\n\n`;
   }
 
-  // 6. INTERACTION MODE (AskUserQuestion guidance)
-  const askUserQuestionConfig = metadata?.features?.askUserQuestion;
-
-  if (askUserQuestionConfig?.enabled) {
-    content += `\n${C.brand}${C.bold}═══ ⚡ INTERACTION MODE: AskUserQuestion ENABLED ═══${C.reset}\n`;
-    content += `${C.dim}${'─'.repeat(60)}${C.reset}\n`;
-    content += `${C.bold}CRITICAL RULE:${C.reset} End ${C.skyBlue}EVERY${C.reset} response with the AskUserQuestion tool.\n\n`;
-    content += `${C.mintGreen}✓ CORRECT:${C.reset} Call the actual AskUserQuestion tool\n`;
-    content += `${C.coral}✗ WRONG:${C.reset} Text like "Want me to continue?" or "What's next?"\n\n`;
-    content += `${C.lavender}Required format:${C.reset}\n`;
-    content += `${C.dim}\`\`\`xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "What would you like to do next?",
-  "header": "Next step",
-  "multiSelect": false,
-  "options": [
-    {"label": "Option A (Recommended)", "description": "Why this is best"},
-    {"label": "Option B", "description": "Alternative approach"},
-    {"label": "Pause", "description": "Stop here for now"}
-  ]
-}]</parameter>
-</invoke>
-\`\`\`${C.reset}\n`;
-    content += `${C.dim}${'─'.repeat(60)}${C.reset}\n`;
-    content += `${C.dim}Mode: ${askUserQuestionConfig.mode || 'all'} | Configure: /agileflow:configure${C.reset}\n\n`;
-  }
-
-  // 5. DOCS STRUCTURE (using vibrant 256-color palette)
+  // DOCS STRUCTURE (using vibrant 256-color palette)
   content += `\n${C.skyBlue}${C.bold}═══ Documentation ═══${C.reset}\n`;
   const docsDir = 'docs';
   const docFolders = safeLs(docsDir).filter(f => {

package/scripts/session-boundary.js

@@ -61,8 +61,9 @@ function isInsideSession(filePath, sessionPath) {
   const normalizedFile = path.resolve(filePath);
   const normalizedSession = path.resolve(sessionPath);
 
-  return normalizedFile.startsWith(normalizedSession + path.sep) ||
-         normalizedFile === normalizedSession;
+  return (
+    normalizedFile.startsWith(normalizedSession + path.sep) || normalizedFile === normalizedSession
+  );
 }
 
 // Output blocked message
@@ -117,7 +118,6 @@ function main() {
       // File is OUTSIDE active session - BLOCK
       outputBlocked(filePath, activeSession);
       process.exit(2);
-
     } catch (e) {
       // Parse error or other issue - fail open
       process.exit(0);