flight-rules 0.15.0 → 0.15.3

package/dist/commands/ralph.d.ts

@@ -16,6 +16,10 @@ export interface TaskGroupPlan {
         status: string;
     }>;
 }
+/**
+ * Format a timestamp for verbose output: [HH:MM:SS]
+ */
+export declare function formatTimestamp(): string;
 /**
  * Parse the discovery response from Claude into TaskGroupPlan objects.
  * Returns null if the response cannot be parsed (tags not found).

package/dist/commands/ralph.js

@@ -80,6 +80,16 @@ function buildAreaConstraint(area) {
 - If no incomplete task groups exist in Area ${area}, respond with ALL_COMPLETE
 `;
 }
+/**
+ * Format a timestamp for verbose output: [HH:MM:SS]
+ */
+export function formatTimestamp() {
+    const now = new Date();
+    const hours = String(now.getHours()).padStart(2, '0');
+    const minutes = String(now.getMinutes()).padStart(2, '0');
+    const seconds = String(now.getSeconds()).padStart(2, '0');
+    return `[${hours}:${minutes}:${seconds}]`;
+}
 /**
  * Check if Claude CLI is available
  */
@@ -113,43 +123,62 @@ async function runClaudeWithPrompt(promptContent, verbose) {
         ], {
             stdio: ['pipe', 'pipe', 'pipe'],
         });
-        let output = '';
+        let reassembledText = ''; // Plain text reassembled from stream-json fragments
+        let resultText = ''; // Full text from the final result event (fallback)
         let errorOutput = '';
         let lineBuffer = ''; // Buffer for incomplete JSON lines
+        let needsTimestamp = true; // Track whether next text output needs a timestamp
         claude.stdout?.on('data', (data) => {
             const text = data.toString();
-            output += text;
-            if (verbose) {
-                // Prepend any buffered partial line from previous chunk
-                const fullText = lineBuffer + text;
-                const lines = fullText.split('\n');
-                // Last element might be incomplete - save it for next chunk
-                lineBuffer = lines.pop() || '';
-                for (const line of lines) {
-                    if (!line.trim())
-                        continue;
-                    try {
-                        const parsed = JSON.parse(line);
-                        // Handle different message types in stream-json format
-                        if (parsed.type === 'assistant' && parsed.message?.content) {
-                            for (const block of parsed.message.content) {
-                                if (block.type === 'text' && block.text) {
+            // Parse stream-json lines to reassemble plain text output
+            const fullText = lineBuffer + text;
+            const lines = fullText.split('\n');
+            // Last element might be incomplete - save it for next chunk
+            lineBuffer = lines.pop() || '';
+            for (const line of lines) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const parsed = JSON.parse(line);
+                    // Handle different message types in stream-json format
+                    if (parsed.type === 'assistant' && parsed.message?.content) {
+                        for (const block of parsed.message.content) {
+                            if (block.type === 'text' && block.text) {
+                                reassembledText += block.text;
+                                if (verbose) {
+                                    if (needsTimestamp) {
+                                        process.stdout.write(`${formatTimestamp()} `);
+                                        needsTimestamp = false;
+                                    }
                                     process.stdout.write(block.text);
                                 }
                             }
                         }
-                        else if (parsed.type === 'content_block_delta' && parsed.delta?.text) {
+                    }
+                    else if (parsed.type === 'content_block_delta' && parsed.delta?.text) {
+                        reassembledText += parsed.delta.text;
+                        if (verbose) {
+                            if (needsTimestamp) {
+                                process.stdout.write(`${formatTimestamp()} `);
+                                needsTimestamp = false;
+                            }
                             process.stdout.write(parsed.delta.text);
                         }
-                        else if (parsed.type === 'content_block_stop') {
-                            // Add newline after each content block ends
-                            process.stdout.write('\n');
+                    }
+                    else if (parsed.type === 'content_block_stop') {
+                        if (verbose) {
+                            // Add newline + blank line after each content block ends
+                            process.stdout.write('\n\n');
+                            needsTimestamp = true;
                         }
                     }
-                    catch {
-                        // Not valid JSON, skip
+                    else if (parsed.type === 'result' && typeof parsed.result === 'string') {
+                        resultText = parsed.result;
                     }
                 }
+                catch {
+                    // Not valid JSON, skip
+                }
             }
         });
         claude.stderr?.on('data', (data) => {
@@ -160,6 +189,30 @@ async function runClaudeWithPrompt(promptContent, verbose) {
             }
         });
         claude.on('close', (code) => {
+            // Flush any remaining data in lineBuffer
+            if (lineBuffer.trim()) {
+                try {
+                    const parsed = JSON.parse(lineBuffer);
+                    if (parsed.type === 'assistant' && parsed.message?.content) {
+                        for (const block of parsed.message.content) {
+                            if (block.type === 'text' && block.text) {
+                                reassembledText += block.text;
+                            }
+                        }
+                    }
+                    else if (parsed.type === 'content_block_delta' && parsed.delta?.text) {
+                        reassembledText += parsed.delta.text;
+                    }
+                    else if (parsed.type === 'result' && typeof parsed.result === 'string') {
+                        resultText = parsed.result;
+                    }
+                }
+                catch {
+                    // Not valid JSON, skip
+                }
+            }
+            // Prefer reassembled streaming text; fall back to result event text
+            const output = reassembledText || resultText;
             resolve({ output, exitCode: code ?? 0 });
         });
         claude.on('error', (err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flight-rules",
-  "version": "0.15.0",
+  "version": "0.15.3",
   "description": "An opinionated framework for AI-assisted software development",
   "type": "module",
   "main": "dist/index.js",

package/payload/AGENTS.md

@@ -1,6 +1,6 @@
 # Flight Rules – Agent Guidelines
 
-flight_rules_version: 0.15.0
+flight_rules_version: 0.15.3
 
 This file defines how agents (Claude Code, Cursor, etc.) should work on software projects using the Flight Rules system.
 

package/payload/prompts/ralph-discovery.md

@@ -1,20 +1,25 @@
 # Flight Rules Discovery Agent
 
-You are a discovery agent for Flight Rules. Your ONLY job is to scan implementation docs and report which task groups have incomplete tasks. Do NOT implement anything.
+You are a discovery agent for Flight Rules. Your ONLY job is to scan implementation docs and report which task groups have **incomplete** (not-yet-done) tasks. Do NOT implement anything.
 
 ## Instructions
 
 1. Read `docs/implementation/overview.md` to understand the area/task-group structure
 2. Scan each Area directory in `docs/implementation/`
-3. For each Task Group file (.md), check every task's status
-4. Report all task groups that contain any task with status other than ✅ Complete (i.e., 🔵 Planned, 🟡 In Progress, or ⏸️ Blocked)
+3. For each Task Group file (.md), check every task's `**Status**:` field
+4. A task is **incomplete** if its status is 🔵 Planned, 🟡 In Progress, or ⏸️ Blocked
+5. A task is **complete** only if its status is ✅ Complete
+6. Report all task groups that contain any incomplete task
 
 ## Response Format
 
-Respond with a pipe-delimited report inside `<ralph-discovery>` tags. Use EXACTLY this format:
+Output ONLY the `<ralph-discovery>` block below. No commentary, no summary, no interpretation before or after the tags. Your entire response must be the block and nothing else.
+
+When incomplete tasks exist (the common case), use this format:
 
 ```
 <ralph-discovery>
+INCOMPLETE|{totalIncompleteTaskCount}
 TASK_GROUP|{id}|{title}|{filePath}|{areaDir}
 TASK|{taskId}|{taskTitle}|{status}
 TASK|{taskId}|{taskTitle}|{status}
@@ -23,16 +28,17 @@ TASK|{taskId}|{taskTitle}|{status}
 </ralph-discovery>
 ```
 
-- Each `TASK_GROUP` line is followed by its `TASK` lines (only incomplete tasks)
+- First line is `INCOMPLETE|{N}` where N = total number of incomplete tasks across all task groups
+- Each `TASK_GROUP` line is followed by its incomplete `TASK` lines
 - `{id}` = task group ID as written in the file (e.g., "1.1", "2.3")
 - `{title}` = task group title
 - `{filePath}` = relative path from project root to the task group file
 - `{areaDir}` = area directory name (e.g., "1-project-setup", "2-cli-core")
 - `{taskId}` = individual task ID (e.g., "1.1.1", "2.3.2")
 - `{taskTitle}` = individual task title
-- `{status}` = one of: planned, in_progress, blocked
+- `{status}` = one of: `planned`, `in_progress`, `blocked` — all three mean the task is NOT done
 
-If ALL tasks in ALL task groups are ✅ Complete, respond with:
+Only if every single task in every single task group has ✅ Complete status (this is rare during active development), respond with:
 
 ```
 <ralph-discovery>
@@ -40,11 +46,21 @@ ALL_COMPLETE
 </ralph-discovery>
 ```
 
+## Field Reference
+
+| Status in doc | Meaning | Output value |
+|---|---|---|
+| 🔵 Planned | Not started, work remains | `planned` |
+| 🟡 In Progress | Started but not finished | `in_progress` |
+| ⏸️ Blocked | Cannot proceed, work remains | `blocked` |
+| ✅ Complete | Done, do NOT include in output | (omit) |
+
 ## Rules
 
 - Do NOT implement or modify any code
 - Do NOT create or modify any files
 - Do NOT run any scripts or quality checks
 - ONLY read implementation files and report status
-- Always include the `<ralph-discovery>` tags in your response
-- List task groups in the order they should be worked on (by area number, then task group number)
+- Your response must contain ONLY the `<ralph-discovery>` block — no other text
+- List task groups in order by area number, then task group number
+- Never output `ALL_COMPLETE` if any task has a status of planned, in_progress, or blocked