@arvorco/relentless 0.2.0 → 0.3.1

package/src/execution/runner.ts

@@ -11,11 +11,29 @@ import type { AgentAdapter, AgentName } from "../agents/types";
 import { getAgent, getInstalledAgents } from "../agents/registry";
 import type { RelentlessConfig } from "../config/schema";
 import { loadConstitution, validateConstitution } from "../config/loader";
-import { loadPRD, getNextStory, isComplete, countStories } from "../prd";
+import { loadPRD, getNextStory, isComplete, countStories, markStoryAsSkipped } from "../prd";
 import type { UserStory } from "../prd/types";
-import { loadProgress, updateProgressMetadata, syncPatternsFromContent } from "../prd/progress";
+import { loadProgress, updateProgressMetadata, syncPatternsFromContent, appendProgress } from "../prd/progress";
 import { routeStory } from "./router";
 import { buildStoryPromptAddition } from "./story-prompt";
+import { processQueue } from "../queue";
+import type { QueueProcessResult } from "../queue/types";
+import {
+  shouldPause,
+  executePauseAction,
+  logPauseToProgress,
+  formatPauseMessage,
+  shouldAbort,
+  logAbortToProgress,
+  formatAbortMessage,
+  generateAbortSummary,
+  shouldSkip,
+  getSkipCommands,
+  handleSkipCommand,
+  logSkipToProgress,
+  logSkipRejectedToProgress,
+  formatSkipMessage,
+} from "./commands";
 
 export interface RunOptions {
   /** Agent to use (or "auto" for smart routing) */
@@ -55,6 +73,106 @@ interface AgentLimitState {
   detectedAt: Date;
 }
 
+/**
+ * Process queue items for an iteration
+ *
+ * Reads pending queue items and processes them.
+ * This is called at the start of each iteration.
+ *
+ * @param featurePath - Path to the feature directory
+ * @returns QueueProcessResult with prompts, commands, and warnings
+ */
+export async function processQueueForIteration(
+  featurePath: string
+): Promise<QueueProcessResult> {
+  return processQueue(featurePath);
+}
+
+/**
+ * Inject queue prompts into the agent prompt
+ *
+ * Adds a "Queued User Guidance" section to the prompt with
+ * numbered list of user messages from the queue.
+ *
+ * @param basePrompt - The original prompt
+ * @param prompts - Queue prompts to inject
+ * @returns Modified prompt with queue guidance section
+ */
+export function injectQueuePrompts(basePrompt: string, prompts: string[]): string {
+  if (prompts.length === 0) {
+    return basePrompt;
+  }
+
+  const numberedList = prompts.map((p, i) => `${i + 1}. ${p}`).join("\n");
+
+  const queueSection = `
+
+## Queued User Guidance
+
+The following messages were queued by the user during the run. Please incorporate this guidance into your work:
+
+${numberedList}
+
+---
+`;
+
+  return basePrompt + queueSection;
+}
+
+/**
+ * Acknowledge queue processing in progress.txt
+ *
+ * Appends a note about processed queue items to the progress log.
+ *
+ * @param progressPath - Path to progress.txt
+ * @param prompts - Prompts that were processed
+ */
+export async function acknowledgeQueueInProgress(
+  progressPath: string,
+  prompts: string[]
+): Promise<void> {
+  if (prompts.length === 0) {
+    return;
+  }
+
+  const timestamp = new Date().toISOString().split("T")[0];
+  const entry = `
+## Queue Processed - ${timestamp}
+
+Acknowledged ${prompts.length} queued message(s):
+${prompts.map((p) => `- ${p}`).join("\n")}
+
+---
+`;
+
+  await appendProgress(progressPath, entry);
+}
+
+/**
+ * Format queue log message for console output
+ *
+ * @param promptCount - Number of prompts in queue
+ * @param commandCount - Number of commands in queue
+ * @returns Formatted log message
+ */
+export function formatQueueLogMessage(promptCount: number, commandCount: number): string {
+  const total = promptCount + commandCount;
+
+  if (total === 0) {
+    return "";
+  }
+
+  const itemWord = total === 1 ? "item" : "items";
+  let message = `Processing ${total} queue ${itemWord}...`;
+
+  if (commandCount > 0) {
+    const cmdWord = commandCount === 1 ? "command" : "commands";
+    message = `Processing ${total} queue ${itemWord} (${commandCount} ${cmdWord})...`;
+  }
+
+  return message;
+}
+
 /**
  * Build the prompt for an iteration
  */
@@ -370,6 +488,109 @@ export async function run(options: RunOptions): Promise<RunResult> {
     console.log(chalk.bold(`  Story: ${chalk.yellow(story.id)} - ${story.title}`));
     console.log(chalk.bold(`${"═".repeat(60)}\n`));
 
+    // Process queue at start of iteration
+    const featureDir = dirname(options.prdPath);
+    let queuePrompts: string[] = [];
+    try {
+      const queueResult = await processQueueForIteration(featureDir);
+      queuePrompts = queueResult.prompts;
+
+      // Log if there are queue items (silent for empty queue)
+      const logMessage = formatQueueLogMessage(queueResult.prompts.length, queueResult.commands.length);
+      if (logMessage) {
+        console.log(chalk.cyan(`  📬 ${logMessage}`));
+      }
+
+      // Log warnings if any
+      for (const warning of queueResult.warnings) {
+        console.log(chalk.yellow(`  ⚠️  ${warning}`));
+      }
+
+      // Acknowledge in progress.txt
+      if (queueResult.prompts.length > 0 && existsSync(progressPath)) {
+        await acknowledgeQueueInProgress(progressPath, queueResult.prompts);
+      }
+
+      // Handle PAUSE command
+      if (shouldPause(queueResult.commands)) {
+        console.log(chalk.yellow(`\n  ${formatPauseMessage()}`));
+
+        // Log pause to progress.txt
+        if (existsSync(progressPath)) {
+          await logPauseToProgress(progressPath);
+        }
+
+        // Wait for user input
+        await executePauseAction();
+        console.log(chalk.green("  ▶️  Resuming...\n"));
+      }
+
+      // Handle ABORT command
+      if (shouldAbort(queueResult.commands)) {
+        console.log(chalk.red(`\n  ${formatAbortMessage()}`));
+
+        // Log abort to progress.txt
+        if (existsSync(progressPath)) {
+          await logAbortToProgress(progressPath);
+        }
+
+        // Calculate summary
+        const currentPRDForAbort = await loadPRD(options.prdPath);
+        const currentCount = countStories(currentPRDForAbort);
+        const duration = Date.now() - startTime;
+
+        // Show progress summary
+        const summary = generateAbortSummary({
+          storiesCompleted: currentCount.completed,
+          storiesTotal: currentCount.total,
+          iterations: i,
+          duration,
+        });
+        console.log(chalk.dim(summary));
+
+        // Return with success (clean exit)
+        return {
+          success: false, // Not all stories complete
+          iterations: i,
+          storiesCompleted: currentCount.completed - initialCount.completed,
+          duration,
+        };
+      }
+
+      // Handle SKIP command(s)
+      if (shouldSkip(queueResult.commands)) {
+        const skipCommands = getSkipCommands(queueResult.commands);
+        for (const skipCmd of skipCommands) {
+          // Check if trying to skip the current story in progress
+          const action = handleSkipCommand(skipCmd.storyId, story.id);
+
+          if (action.rejected) {
+            // Log rejection to console and progress.txt
+            console.log(chalk.yellow(`\n  ${formatSkipMessage(action.storyId, true)}`));
+            if (existsSync(progressPath)) {
+              await logSkipRejectedToProgress(progressPath, action.storyId);
+            }
+          } else {
+            // Mark story as skipped in PRD
+            const skipResult = await markStoryAsSkipped(options.prdPath, action.storyId);
+
+            if (skipResult.success) {
+              console.log(chalk.cyan(`\n  ${formatSkipMessage(action.storyId, false)}`));
+              if (existsSync(progressPath)) {
+                await logSkipToProgress(progressPath, action.storyId, action.customReason);
+              }
+            } else if (skipResult.error) {
+              console.log(chalk.yellow(`\n  ⚠️  ${skipResult.error}`));
+            }
+          }
+        }
+      }
+
+      // TODO: Handle PRIORITY command in future story (US-012)
+    } catch (queueError) {
+      console.warn(chalk.yellow(`  ⚠️  Queue processing error: ${queueError}`));
+    }
+
     if (options.dryRun) {
       console.log(chalk.dim("  [Dry run - skipping execution]"));
       continue;
@@ -391,7 +612,13 @@ export async function run(options: RunOptions): Promise<RunResult> {
           mkdirSync(researchDir, { recursive: true });
         }
 
-        const researchPrompt = await buildPrompt(options.promptPath, options.workingDirectory, progressPath, story);
+        let researchPrompt = await buildPrompt(options.promptPath, options.workingDirectory, progressPath, story);
+
+        // Inject queue prompts into research phase too
+        if (queuePrompts.length > 0) {
+          researchPrompt = injectQueuePrompts(researchPrompt, queuePrompts);
+        }
+
         const researchResult = await agent.invoke(researchPrompt, {
           workingDirectory: options.workingDirectory,
           dangerouslyAllowAll: options.config.agents[agent.name]?.dangerouslyAllowAll ?? true,
@@ -430,7 +657,12 @@ export async function run(options: RunOptions): Promise<RunResult> {
         console.log(chalk.cyan("  🔨 Implementation phase - applying research findings..."));
       }
 
-      const prompt = await buildPrompt(options.promptPath, options.workingDirectory, progressPath, story);
+      let prompt = await buildPrompt(options.promptPath, options.workingDirectory, progressPath, story);
+
+      // Inject queue prompts if any
+      if (queuePrompts.length > 0) {
+        prompt = injectQueuePrompts(prompt, queuePrompts);
+      }
 
       if (!needsResearch) {
         console.log(chalk.dim("  Running agent..."));

package/src/prd/parser.ts

@@ -279,3 +279,143 @@ export async function savePRD(prd: PRD, path: string): Promise<void> {
   const content = JSON.stringify(validated, null, 2);
   await Bun.write(path, content);
 }
+
+/**
+ * Result of marking a story as skipped
+ */
+export interface MarkSkippedResult {
+  success: boolean;
+  error?: string;
+  alreadySkipped?: boolean;
+}
+
+/**
+ * Result of prioritizing a story
+ */
+export interface PrioritizeStoryResult {
+  success: boolean;
+  error?: string;
+  previousPriority?: number;
+}
+
+/**
+ * Mark a story as skipped in the PRD file
+ *
+ * @param prdPath - Path to the prd.json file
+ * @param storyId - The ID of the story to skip
+ * @returns Result indicating success or failure
+ */
+export async function markStoryAsSkipped(
+  prdPath: string,
+  storyId: string
+): Promise<MarkSkippedResult> {
+  // Load current PRD
+  const prd = await loadPRD(prdPath);
+
+  // Find the story
+  const storyIndex = prd.userStories.findIndex((s) => s.id === storyId);
+  if (storyIndex === -1) {
+    return {
+      success: false,
+      error: `Story ${storyId} not found in PRD`,
+    };
+  }
+
+  const story = prd.userStories[storyIndex];
+
+  // Check if story is already completed
+  if (story.passes) {
+    return {
+      success: false,
+      error: `Story ${storyId} is already completed and cannot be skipped`,
+    };
+  }
+
+  // Check if already skipped
+  if (story.skipped) {
+    return {
+      success: true,
+      alreadySkipped: true,
+    };
+  }
+
+  // Mark as skipped
+  prd.userStories[storyIndex] = {
+    ...story,
+    skipped: true,
+    notes: story.notes
+      ? `${story.notes}\n[SKIPPED] ${new Date().toISOString().split("T")[0]}`
+      : `[SKIPPED] ${new Date().toISOString().split("T")[0]}`,
+  };
+
+  // Save the updated PRD
+  await savePRD(prd, prdPath);
+
+  return {
+    success: true,
+  };
+}
+
+/**
+ * Prioritize a story to be the next one worked on
+ *
+ * Sets the story's priority to 0 (highest priority) so it becomes
+ * the next story selected by getNextStory().
+ *
+ * @param prdPath - Path to the prd.json file
+ * @param storyId - The ID of the story to prioritize
+ * @returns Result indicating success or failure
+ */
+export async function prioritizeStory(
+  prdPath: string,
+  storyId: string
+): Promise<PrioritizeStoryResult> {
+  // Load current PRD
+  const prd = await loadPRD(prdPath);
+
+  // Find the story
+  const storyIndex = prd.userStories.findIndex((s) => s.id === storyId);
+  if (storyIndex === -1) {
+    return {
+      success: false,
+      error: `Story ${storyId} not found in PRD`,
+    };
+  }
+
+  const story = prd.userStories[storyIndex];
+
+  // Check if story is already completed
+  if (story.passes) {
+    return {
+      success: false,
+      error: `Story ${storyId} is already completed and cannot be prioritized`,
+    };
+  }
+
+  // Check if story is skipped
+  if (story.skipped) {
+    return {
+      success: false,
+      error: `Story ${storyId} is skipped and cannot be prioritized`,
+    };
+  }
+
+  const previousPriority = story.priority;
+
+  // Set priority to 0 (highest priority)
+  prd.userStories[storyIndex] = {
+    ...story,
+    priority: 0,
+    notes: story.notes
+      ? `${story.notes}\n[PRIORITIZED] ${new Date().toISOString().split("T")[0]} (was priority ${previousPriority})`
+      : `[PRIORITIZED] ${new Date().toISOString().split("T")[0]} (was priority ${previousPriority})`,
+  };
+
+  // Save the updated PRD
+  await savePRD(prd, prdPath);
+
+  return {
+    success: true,
+    previousPriority,
+  };
+}

package/src/prd/types.ts

@@ -14,13 +14,14 @@ export const UserStorySchema = z.object({
   title: z.string(),
   description: z.string(),
   acceptanceCriteria: z.array(z.string()),
-  priority: z.number().int().positive(),
+  priority: z.number().int().nonnegative(), // 0 = highest priority (used by PRIORITY command)
   passes: z.boolean().default(false),
   notes: z.string().default(""),
   dependencies: z.array(z.string()).optional(), // Array of story IDs this story depends on
   parallel: z.boolean().optional(), // Can be executed in parallel with other stories
   phase: z.string().optional(), // Phase marker (e.g., "Setup", "Foundation", "Stories", "Polish")
   research: z.boolean().optional(), // Requires research phase before implementation
+  skipped: z.boolean().optional(), // Whether the story was skipped by user command
 });
 
 export type UserStory = z.infer<typeof UserStorySchema>;
@@ -116,9 +117,9 @@ export function getNextStory(prd: PRD): UserStory | null {
   // Validate dependencies first
   validateDependencies(prd);
 
-  // Find highest priority story where passes is false and dependencies are met
+  // Find highest priority story where passes is false, not skipped, and dependencies are met
   const pendingStories = prd.userStories
-    .filter((s) => !s.passes && areDependenciesMet(s, prd))
+    .filter((s) => !s.passes && !s.skipped && areDependenciesMet(s, prd))
     .sort((a, b) => a.priority - b.priority);
 
   return pendingStories[0] ?? null;
@@ -134,11 +135,12 @@ export function isComplete(prd: PRD): boolean {
 /**
  * Count stories by status
  */
-export function countStories(prd: PRD): { total: number; completed: number; pending: number } {
+export function countStories(prd: PRD): { total: number; completed: number; skipped: number; pending: number } {
   const total = prd.userStories.length;
   const completed = prd.userStories.filter((s) => s.passes).length;
-  const pending = total - completed;
-  return { total, completed, pending };
+  const skipped = prd.userStories.filter((s) => s.skipped && !s.passes).length;
+  const pending = total - completed - skipped;
+  return { total, completed, skipped, pending };
 }
 
 /**

package/src/queue/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Queue Module
+ *
+ * Provides queue management for mid-run user input.
+ * Agents check the queue between iterations to receive
+ * user guidance and structured commands.
+ */
+
+// Export types
+export type {
+  QueueItem,
+  QueueState,
+  QueueCommandType,
+  QueueItemType,
+  QueueProcessResult,
+  ParsedCommand,
+} from "./types";
+
+export {
+  QueueItemSchema,
+  QueueStateSchema,
+  QueueCommandTypeSchema,
+  QueueItemTypeSchema,
+} from "./types";
+
+// Export parser functions
+export { parseQueueLine, parseCommand, formatQueueLine } from "./parser";
+
+// Export writer functions
+export { addToQueue, removeFromQueue, clearQueue } from "./writer";
+
+// Export loader functions
+export { loadQueue } from "./loader";
+
+// Export processor functions
+export { processQueue } from "./processor";
+
+// Export lock functions
+export {
+  acquireQueueLock,
+  releaseQueueLock,
+  isQueueLocked,
+  setLockTimeout,
+  getLockTimeout,
+} from "./lock";

package/src/queue/loader.ts

@@ -0,0 +1,97 @@
+/**
+ * Queue Loader
+ *
+ * Functions for loading queue state from files.
+ * Handles pending and processed items with graceful error handling.
+ *
+ * Queue file locations:
+ * - Pending: <featurePath>/.queue.txt
+ * - Processed: <featurePath>/.queue.processed.txt
+ */
+
+import { join } from "node:path";
+import type { QueueItem, QueueState } from "./types";
+import { parseQueueLine } from "./parser";
+
+/** Pending queue file name */
+const QUEUE_FILE = ".queue.txt";
+
+/** Processed queue file name */
+const QUEUE_PROCESSED_FILE = ".queue.processed.txt";
+
+/**
+ * Load queue state from files
+ *
+ * @param featurePath - Path to the feature directory
+ * @returns QueueState with pending and processed items
+ */
+export async function loadQueue(featurePath: string): Promise<QueueState> {
+  const pendingPath = join(featurePath, QUEUE_FILE);
+  const processedPath = join(featurePath, QUEUE_PROCESSED_FILE);
+
+  const warnings: string[] = [];
+
+  // Load pending items
+  const pending = await loadQueueFile(pendingPath, warnings);
+
+  // Load processed items
+  const processed = await loadQueueFile(processedPath, warnings);
+
+  // Build state
+  const state: QueueState = {
+    featurePath,
+    pending,
+    processed,
+    lastChecked: new Date().toISOString(),
+  };
+
+  // Only include warnings if there are any
+  if (warnings.length > 0) {
+    state.warnings = warnings;
+  }
+
+  return state;
+}
+
+/**
+ * Load items from a queue file
+ *
+ * @param filePath - Path to the queue file
+ * @param warnings - Array to collect warnings for malformed lines
+ * @returns Array of QueueItems
+ */
+async function loadQueueFile(
+  filePath: string,
+  warnings: string[]
+): Promise<QueueItem[]> {
+  const file = Bun.file(filePath);
+
+  // Handle missing file gracefully
+  if (!(await file.exists())) {
+    return [];
+  }
+
+  const content = await file.text();
+  const lines = content.split("\n");
+  const items: QueueItem[] = [];
+
+  for (const line of lines) {
+    // Skip empty lines
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+
+    // Try to parse the line
+    const item = parseQueueLine(trimmed);
+
+    if (item) {
+      items.push(item);
+    } else {
+      // Record warning for malformed line
+      warnings.push(`Skipped malformed line: ${trimmed}`);
+    }
+  }
+
+  return items;
+}