@arvorco/relentless 0.1.27 → 0.3.0

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;
+}

package/src/queue/lock.ts

@@ -0,0 +1,137 @@
+/**
+ * Queue Lock Manager
+ *
+ * Provides file-based locking for queue operations.
+ * Prevents concurrent writes and partial processing issues.
+ *
+ * Lock file location: <featurePath>/.queue.lock
+ */
+
+import { join } from "node:path";
+import { unlink } from "node:fs/promises";
+
+/** Lock file name */
+const LOCK_FILE = ".queue.lock";
+
+/** Default lock timeout in milliseconds (5 seconds) */
+let lockTimeout = 5000;
+
+/**
+ * Set the lock timeout for testing purposes
+ *
+ * @param timeout - New timeout in milliseconds
+ */
+export function setLockTimeout(timeout: number): void {
+  lockTimeout = timeout;
+}
+
+/**
+ * Get the current lock timeout
+ *
+ * @returns Current timeout in milliseconds
+ */
+export function getLockTimeout(): number {
+  return lockTimeout;
+}
+
+/**
+ * Acquire a lock for queue operations
+ *
+ * @param featurePath - Path to the feature directory
+ * @returns true if lock acquired, false if already locked
+ */
+export async function acquireQueueLock(featurePath: string): Promise<boolean> {
+  const lockPath = join(featurePath, LOCK_FILE);
+  const lockFile = Bun.file(lockPath);
+
+  // Check if lock exists and is not stale
+  if (await lockFile.exists()) {
+    const content = await lockFile.text();
+
+    try {
+      const lockData = JSON.parse(content);
+      const lockTime = new Date(lockData.timestamp).getTime();
+      const now = Date.now();
+
+      // Check if lock is stale (older than timeout)
+      if (now - lockTime < lockTimeout) {
+        // Lock is still valid
+        return false;
+      }
+      // Lock is stale, remove it
+      await releaseLockFile(lockPath);
+    } catch {
+      // Invalid lock file, remove it
+      await releaseLockFile(lockPath);
+    }
+  }
+
+  // Create new lock
+  const lockData = {
+    timestamp: new Date().toISOString(),
+    pid: process.pid,
+  };
+
+  try {
+    // Use exclusive flag to prevent race conditions
+    await Bun.write(lockPath, JSON.stringify(lockData));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Release the queue lock
+ *
+ * @param featurePath - Path to the feature directory
+ */
+export async function releaseQueueLock(featurePath: string): Promise<void> {
+  const lockPath = join(featurePath, LOCK_FILE);
+  await releaseLockFile(lockPath);
+}
+
+/**
+ * Check if the queue is currently locked
+ *
+ * @param featurePath - Path to the feature directory
+ * @returns true if locked and lock is not stale, false otherwise
+ */
+export async function isQueueLocked(featurePath: string): Promise<boolean> {
+  const lockPath = join(featurePath, LOCK_FILE);
+  const lockFile = Bun.file(lockPath);
+
+  if (!(await lockFile.exists())) {
+    return false;
+  }
+
+  const content = await lockFile.text();
+
+  try {
+    const lockData = JSON.parse(content);
+    const lockTime = new Date(lockData.timestamp).getTime();
+    const now = Date.now();
+
+    // Check if lock is stale
+    if (now - lockTime >= lockTimeout) {
+      return false;
+    }
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Helper to safely remove a lock file
+ *
+ * @param lockPath - Path to the lock file
+ */
+async function releaseLockFile(lockPath: string): Promise<void> {
+  try {
+    await unlink(lockPath);
+  } catch {
+    // Ignore if file doesn't exist
+  }
+}

package/src/queue/parser.ts

@@ -0,0 +1,142 @@
+/**
+ * Queue Parser
+ *
+ * Functions for parsing and formatting queue items.
+ * Handles line-based queue format with ISO timestamp prefix.
+ *
+ * Queue line format: `2026-01-13T10:30:00.000Z | content`
+ * Command format: `[COMMAND]` or `[COMMAND arg]`
+ */
+
+import type { QueueItem, QueueCommandType, ParsedCommand } from "./types";
+
+/**
+ * Valid command names (uppercase for matching)
+ */
+const VALID_COMMANDS = ["PAUSE", "SKIP", "PRIORITY", "ABORT"] as const;
+
+/**
+ * Commands that require a story ID argument
+ */
+const COMMANDS_WITH_STORY_ID = ["SKIP", "PRIORITY"] as const;
+
+/**
+ * Regex patterns for parsing
+ */
+const QUEUE_LINE_PATTERN = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)\s*\|\s*(.+)$/;
+const COMMAND_PATTERN = /^\[\s*([A-Za-z]+)(?:\s+([^\]]+))?\s*\]$/;
+const PROCESSED_AT_PATTERN = /\s*\|\s*processedAt:(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)$/;
+
+/**
+ * Parse a single queue line into a QueueItem
+ *
+ * @param line - The raw line from the queue file
+ * @returns QueueItem if valid, null if malformed
+ */
+export function parseQueueLine(line: string): QueueItem | null {
+  // Handle empty or whitespace-only lines
+  const trimmedLine = line.trim();
+  if (!trimmedLine) {
+    return null;
+  }
+
+  // Match the queue line pattern: timestamp | content
+  const match = trimmedLine.match(QUEUE_LINE_PATTERN);
+  if (!match) {
+    return null;
+  }
+
+  const [, timestamp, rawContent] = match;
+  let trimmedContent = rawContent.trim();
+  let processedAt: string | undefined;
+
+  // Check for processedAt suffix (from processed queue file)
+  const processedMatch = trimmedContent.match(PROCESSED_AT_PATTERN);
+  if (processedMatch) {
+    processedAt = processedMatch[1];
+    // Remove the processedAt suffix from content
+    trimmedContent = trimmedContent.replace(PROCESSED_AT_PATTERN, "").trim();
+  }
+
+  // Generate unique ID from timestamp
+  const id = `${timestamp.replace(/[:.]/g, "-")}-${Date.now() % 1000}`;
+
+  // Check if content is a command
+  const parsedCommand = parseCommand(trimmedContent);
+
+  if (parsedCommand) {
+    const item: QueueItem = {
+      id,
+      content: trimmedContent,
+      type: "command",
+      command: parsedCommand.type,
+      targetStoryId: parsedCommand.storyId,
+      addedAt: timestamp,
+    };
+    if (processedAt) {
+      item.processedAt = processedAt;
+    }
+    return item;
+  }
+
+  // Regular prompt
+  const item: QueueItem = {
+    id,
+    content: trimmedContent,
+    type: "prompt",
+    addedAt: timestamp,
+  };
+  if (processedAt) {
+    item.processedAt = processedAt;
+  }
+  return item;
+}
+
+/**
+ * Parse command content into a ParsedCommand
+ *
+ * @param content - The content string (e.g., "[PAUSE]" or "[SKIP US-003]")
+ * @returns ParsedCommand if valid command, null otherwise
+ */
+export function parseCommand(content: string): ParsedCommand | null {
+  const trimmedContent = content.trim();
+
+  // Match command pattern: [COMMAND] or [COMMAND arg]
+  const match = trimmedContent.match(COMMAND_PATTERN);
+  if (!match) {
+    return null;
+  }
+
+  const [, command, arg] = match;
+  const upperCommand = command.toUpperCase();
+
+  // Validate command name
+  if (!VALID_COMMANDS.includes(upperCommand as (typeof VALID_COMMANDS)[number])) {
+    return null;
+  }
+
+  const commandType = upperCommand as QueueCommandType;
+
+  // Check if command requires a story ID
+  if (COMMANDS_WITH_STORY_ID.includes(commandType as (typeof COMMANDS_WITH_STORY_ID)[number])) {
+    if (!arg) {
+      return null;
+    }
+    // Uppercase the story ID for consistency (e.g., "us-003" -> "US-003")
+    const storyId = arg.trim().toUpperCase();
+    return { type: commandType, storyId };
+  }
+
+  // Commands without arguments
+  return { type: commandType };
+}
+
+/**
+ * Format a QueueItem back to a queue line string
+ *
+ * @param item - The queue item to format
+ * @returns Formatted queue line string
+ */
+export function formatQueueLine(item: Pick<QueueItem, "addedAt" | "content">): string {
+  return `${item.addedAt} | ${item.content}`;
+}

package/src/queue/processor.ts

@@ -0,0 +1,141 @@
+/**
+ * Queue Processor
+ *
+ * Processes pending queue items for orchestration.
+ * Separates text prompts from structured commands.
+ * Moves processed items to .queue.processed.txt with timestamp.
+ *
+ * Queue file locations:
+ * - Pending: <featurePath>/.queue.txt
+ * - Processed: <featurePath>/.queue.processed.txt
+ */
+
+import { join } from "node:path";
+import { rename } from "node:fs/promises";
+import type { QueueItem, QueueProcessResult, QueueCommandType } from "./types";
+import { parseQueueLine, formatQueueLine } from "./parser";
+
+/** Pending queue file name */
+const QUEUE_FILE = ".queue.txt";
+
+/** Processed queue file name */
+const QUEUE_PROCESSED_FILE = ".queue.processed.txt";
+
+/**
+ * Process all pending queue items
+ *
+ * @param featurePath - Path to the feature directory
+ * @returns QueueProcessResult with prompts, commands, and warnings
+ */
+export async function processQueue(
+  featurePath: string
+): Promise<QueueProcessResult> {
+  const queuePath = join(featurePath, QUEUE_FILE);
+  const processedPath = join(featurePath, QUEUE_PROCESSED_FILE);
+
+  const result: QueueProcessResult = {
+    prompts: [],
+    commands: [],
+    warnings: [],
+  };
+
+  // Check if queue file exists
+  const queueFile = Bun.file(queuePath);
+  if (!(await queueFile.exists())) {
+    return result;
+  }
+
+  // Read queue content
+  const content = await queueFile.text();
+  const lines = content.split("\n");
+
+  // Parse all valid items
+  const items: QueueItem[] = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip empty lines silently
+    if (!trimmed) {
+      continue;
+    }
+
+    const item = parseQueueLine(trimmed);
+
+    if (item) {
+      items.push(item);
+    } else {
+      // Record warning for malformed lines
+      result.warnings.push(`Skipped malformed line: ${trimmed}`);
+    }
+  }
+
+  // If no items to process, return early
+  if (items.length === 0) {
+    return result;
+  }
+
+  // Process items and separate prompts from commands
+  const processedAt = new Date().toISOString();
+
+  for (const item of items) {
+    // Add processedAt timestamp
+    item.processedAt = processedAt;
+
+    if (item.type === "command" && item.command) {
+      // Structured command
+      const command: { type: QueueCommandType; storyId?: string } = {
+        type: item.command,
+      };
+
+      if (item.targetStoryId) {
+        command.storyId = item.targetStoryId;
+      }
+
+      result.commands.push(command);
+    } else {
+      // Text prompt - trim any trailing whitespace
+      result.prompts.push(item.content.trim());
+    }
+  }
+
+  // Move processed items to .queue.processed.txt
+  await appendToProcessedFile(processedPath, items);
+
+  // Clear the queue file (atomic write)
+  const tempPath = `${queuePath}.tmp`;
+  await Bun.write(tempPath, "");
+  await rename(tempPath, queuePath);
+
+  return result;
+}
+
+/**
+ * Append processed items to the processed queue file
+ *
+ * @param processedPath - Path to the processed queue file
+ * @param items - Items to append with processedAt timestamps
+ */
+async function appendToProcessedFile(
+  processedPath: string,
+  items: QueueItem[]
+): Promise<void> {
+  // Read existing content (if any)
+  let existingContent = "";
+  const processedFile = Bun.file(processedPath);
+  if (await processedFile.exists()) {
+    existingContent = await processedFile.text();
+  }
+
+  // Format new lines with processedAt marker
+  const newLines = items.map((item) => {
+    const baseLine = formatQueueLine(item);
+    return `${baseLine} | processedAt:${item.processedAt}`;
+  });
+
+  // Combine and write atomically
+  const newContent = existingContent + newLines.join("\n") + "\n";
+  const tempPath = `${processedPath}.tmp`;
+  await Bun.write(tempPath, newContent);
+  await rename(tempPath, processedPath);
+}

package/src/queue/types.ts

@@ -0,0 +1,81 @@
+/**
+ * Queue Types
+ *
+ * Defines Zod schemas and TypeScript types for the queue system.
+ * Used for validating queue items, commands, and state.
+ */
+
+import { z } from "zod";
+
+/**
+ * Valid queue command types
+ */
+export const QueueCommandTypeSchema = z.enum(["PAUSE", "SKIP", "PRIORITY", "ABORT"]);
+export type QueueCommandType = z.infer<typeof QueueCommandTypeSchema>;
+
+/**
+ * Queue item type - either a text prompt or a structured command
+ */
+export const QueueItemTypeSchema = z.enum(["prompt", "command"]);
+export type QueueItemType = z.infer<typeof QueueItemTypeSchema>;
+
+/**
+ * A single queue item
+ */
+export const QueueItemSchema = z.object({
+  /** Unique ID (timestamp-based) */
+  id: z.string(),
+  /** Raw content from file */
+  content: z.string(),
+  /** Type of item */
+  type: QueueItemTypeSchema,
+  /** Parsed command type (if type is "command") */
+  command: QueueCommandTypeSchema.optional(),
+  /** Target story ID (for SKIP/PRIORITY) */
+  targetStoryId: z.string().optional(),
+  /** When item was added (ISO timestamp) */
+  addedAt: z.string().datetime(),
+  /** When item was processed (ISO timestamp, null if pending) */
+  processedAt: z.string().datetime().optional(),
+});
+export type QueueItem = z.infer<typeof QueueItemSchema>;
+
+/**
+ * Queue state for a feature
+ */
+export const QueueStateSchema = z.object({
+  /** Path to feature directory */
+  featurePath: z.string(),
+  /** Pending items */
+  pending: z.array(QueueItemSchema),
+  /** Processed items (audit trail) */
+  processed: z.array(QueueItemSchema),
+  /** Last time queue was checked (ISO timestamp) */
+  lastChecked: z.string().datetime().optional(),
+  /** Warnings from loading (e.g., malformed lines) */
+  warnings: z.array(z.string()).optional(),
+});
+export type QueueState = z.infer<typeof QueueStateSchema>;
+
+/**
+ * Result of processing queue commands
+ */
+export interface QueueProcessResult {
+  /** Text prompts to inject into agent context */
+  prompts: string[];
+  /** Commands to execute */
+  commands: Array<{
+    type: QueueCommandType;
+    storyId?: string;
+  }>;
+  /** Warnings (e.g., unrecognized commands treated as prompts) */
+  warnings: string[];
+}
+
+/**
+ * Parsed command result from parseCommand
+ */
+export interface ParsedCommand {
+  type: QueueCommandType;
+  storyId?: string;
+}