agileflow 3.2.1 → 3.4.0

package/scripts/lib/README-portable-tasks.md

@@ -0,0 +1,424 @@
+# Portable Task Tracking System
+
+A file-based, IDE-agnostic task tracking system for AgileFlow projects. Works with Claude Code, Cursor, Windsurf, Codex, and any IDE that can read/write files.
+
+## Overview
+
+Unlike Claude Code's native `TaskCreate`/`TaskUpdate` tools (which only work in Claude Code), this system stores tasks in a simple markdown file (`.agileflow/tasks.md`) that ANY IDE's AI can read and modify.
+
+**Key Features:**
+- Pure markdown format - human-readable, git-friendly
+- No dependencies beyond Node.js built-ins
+- Works across all IDEs
+- Supports filtering, custom fields, and blocking relationships
+- Round-trip stable (parse → modify → format → parse)
+
+## Files
+
+- **`portable-tasks.js`** - Core module (functions for CRUD operations)
+- **`portable-tasks-cli.js`** - Command-line interface (callable from any IDE)
+
+## Installation
+
+Copy both files to your project's `.agileflow/scripts/lib/` directory during setup. They are published with the agileflow npm package.
+
+## File Format
+
+Tasks are stored in `.agileflow/tasks.md`:
+
+```markdown
+# AgileFlow Tasks
+
+> Auto-managed task list. Edit carefully - format matters.
+> Last updated: 2026-02-20T15:30:00Z
+
+## Active Tasks
+
+### T-001: Implement user authentication [in_progress]
+- **Owner**: AG-API
+- **Created**: 2026-02-20
+- **Story**: US-0042
+- **Description**: Add JWT-based auth to /api/login endpoint
+
+### T-002: Write auth tests [pending]
+- **Owner**: AG-CI
+- **Created**: 2026-02-20
+- **Story**: US-0042
+- **Blocked by**: T-001
+- **Description**: Unit and integration tests for auth flow
+
+## Completed Tasks
+
+### T-003: Setup database schema [completed]
+- **Owner**: AG-DEVOPS
+- **Created**: 2026-02-19
+- **Completed**: 2026-02-20
+- **Story**: US-0041
+- **Description**: Create users and sessions tables
+```
+
+## API Reference
+
+### Module: `portable-tasks.js`
+
+#### `loadTasks(projectDir)`
+Load tasks from `.agileflow/tasks.md`.
+
+```javascript
+const { loadTasks } = require('./portable-tasks');
+const { activeTasks, completedTasks } = loadTasks(process.cwd());
+```
+
+Returns: `{ activeTasks: [], completedTasks: [] }`
+
+#### `saveTasks(projectDir, tasksData)`
+Save tasks back to markdown file.
+
+```javascript
+saveTasks(process.cwd(), { activeTasks, completedTasks });
+```
+
+Returns: `boolean` (success/failure)
+
+#### `addTask(projectDir, taskData)`
+Create a new task.
+
+```javascript
+const result = addTask(process.cwd(), {
+  subject: 'Write API tests',
+  description: 'Integration tests for new endpoints',
+  owner: 'AG-CI',
+  status: 'pending',        // pending, in_progress, completed, blocked
+  story: 'US-0040',
+  blockedBy: 'T-001',       // optional
+});
+
+// result: { ok: true, taskId: 'T-001' } or { ok: false, error: 'message' }
+```
+
+#### `updateTask(projectDir, taskId, updates)`
+Update an existing task.
+
+```javascript
+updateTask(process.cwd(), 'T-001', {
+  status: 'in_progress',
+  description: 'Updated description',
+  owner: 'AG-DEVOPS',
+});
+```
+
+Returns: `{ ok: boolean, error?: string }`
+
+Moves task between active/completed sections automatically when status changes.
+
+#### `deleteTask(projectDir, taskId)`
+Remove a task.
+
+```javascript
+deleteTask(process.cwd(), 'T-001');
+```
+
+Returns: `{ ok: boolean, error?: string }`
+
+#### `getTask(projectDir, taskId)`
+Retrieve a single task by ID.
+
+```javascript
+const task = getTask(process.cwd(), 'T-001');
+// Returns task object or null if not found
+```
+
+#### `listTasks(projectDir, filters?)`
+List tasks with optional filtering.
+
+```javascript
+// All active tasks (default)
+const tasks = listTasks(process.cwd());
+
+// Filter by status
+listTasks(process.cwd(), { status: 'pending' });
+listTasks(process.cwd(), { status: ['pending', 'blocked'] });
+
+// Filter by owner
+listTasks(process.cwd(), { owner: 'AG-API' });
+
+// Include completed tasks
+listTasks(process.cwd(), { includeCompleted: true });
+
+// Combine filters
+listTasks(process.cwd(), {
+  status: 'pending',
+  owner: 'AG-API',
+  includeCompleted: true,
+});
+```
+
+Returns: `Array` of task objects
+
+#### `getNextId(tasks)`
+Generate the next sequential task ID.
+
+```javascript
+const nextId = getNextId(allTasks); // 'T-001', 'T-002', etc.
+```
+
+#### Parsing Functions
+- `parseTasksFile(content)` - Parse markdown content into task objects
+- `formatTasksFile(activeTasks, completedTasks)` - Generate markdown from tasks
+
+## CLI: `portable-tasks-cli.js`
+
+Command-line interface for task management (works in any IDE's terminal).
+
+### Usage
+
+```bash
+node portable-tasks-cli.js [command] [options]
+```
+
+### Commands
+
+#### List Tasks
+```bash
+# List active tasks
+node portable-tasks-cli.js list
+
+# Filter by status
+node portable-tasks-cli.js list --status=pending
+node portable-tasks-cli.js list --status=in_progress
+
+# Filter by owner
+node portable-tasks-cli.js list --owner=AG-API
+
+# Include completed tasks
+node portable-tasks-cli.js list --include-completed
+
+# Output as JSON
+node portable-tasks-cli.js list --json
+
+# Combine filters
+node portable-tasks-cli.js list --status=pending --owner=AG-CI
+```
+
+#### Add Task
+```bash
+# Minimal (subject required)
+node portable-tasks-cli.js add --subject="Fix login bug"
+
+# Full details
+node portable-tasks-cli.js add \
+  --subject="Implement auth" \
+  --description="Add JWT tokens to API" \
+  --owner=AG-API \
+  --status=in_progress \
+  --story=US-0040 \
+  --blocked-by=T-001
+```
+
+#### Update Task
+```bash
+# Change status
+node portable-tasks-cli.js update T-001 --status=completed
+
+# Update multiple fields
+node portable-tasks-cli.js update T-001 \
+  --status=in_progress \
+  --owner=AG-API \
+  --description="Started implementation"
+```
+
+#### Get Task
+```bash
+# Display task
+node portable-tasks-cli.js get T-001
+
+# Output as JSON
+node portable-tasks-cli.js get T-001 --json
+```
+
+#### Delete Task
+```bash
+node portable-tasks-cli.js delete T-001
+node portable-tasks-cli.js rm T-001  # alias
+```
+
+### Output Formats
+
+**Human-readable (default):**
+```
+T-001 [in_progress] Implement user auth (AG-API) [blocked by T-002]
+T-002 [pending] Write tests (AG-CI)
+```
+
+**JSON output:**
+```json
+[
+  {
+    "id": "T-001",
+    "title": "Implement user auth",
+    "status": "in_progress",
+    "owner": "AG-API",
+    "created": "2026-02-20",
+    "completed": null,
+    "story": "US-0040",
+    "blockedBy": "T-002",
+    "description": "Add JWT tokens to /api/login endpoint"
+  }
+]
+```
+
+### Exit Codes
+- **0**: Success
+- **1**: Error (invalid command, missing task, etc.)
+
+## Task Fields
+
+Every task has these fields:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | Yes | Auto-generated ID (T-001, T-002, etc.) |
+| `title` | string | Yes | Task summary |
+| `status` | string | Yes | One of: `pending`, `in_progress`, `completed`, `blocked` |
+| `owner` | string | No | Responsible agent/team (e.g., AG-API) |
+| `created` | date | No | Creation date (YYYY-MM-DD) |
+| `completed` | date | No | Completion date (auto-set when status → completed) |
+| `story` | string | No | Link to parent story (e.g., US-0040) |
+| `blockedBy` | string | No | Task ID blocking this task (e.g., T-001) |
+| `description` | string | No | Detailed task description |
+
+## Examples
+
+### Python Script Using Module
+```python
+import subprocess
+import json
+
+# List all pending tasks
+result = subprocess.run(
+  ['node', '.agileflow/scripts/lib/portable-tasks-cli.js', 'list', '--status=pending', '--json'],
+  capture_output=True,
+  text=True
+)
+tasks = json.loads(result.stdout)
+for task in tasks:
+    print(f"{task['id']}: {task['title']} ({task['owner']})")
+```
+
+### JavaScript Using Module
+```javascript
+const { addTask, listTasks, updateTask } = require('./.agileflow/scripts/lib/portable-tasks');
+
+// Create task
+const result = addTask(process.cwd(), {
+  subject: 'Run integration tests',
+  owner: 'AG-CI',
+  status: 'pending'
+});
+
+// List tasks for an owner
+const tasks = listTasks(process.cwd(), { owner: 'AG-CI' });
+
+// Update task
+updateTask(process.cwd(), result.taskId, { status: 'in_progress' });
+```
+
+### Bash Script
+```bash
+#!/bin/bash
+
+# Add task
+node .agileflow/scripts/lib/portable-tasks-cli.js add \
+  --subject="Deploy to staging" \
+  --owner=AG-DEVOPS
+
+# Get all pending tasks for AG-API
+node .agileflow/scripts/lib/portable-tasks-cli.js list \
+  --status=pending \
+  --owner=AG-API
+
+# Mark task complete
+node .agileflow/scripts/lib/portable-tasks-cli.js update T-001 \
+  --status=completed
+```
+
+## Status Values
+
+- **`pending`** - Task not started
+- **`in_progress`** - Task actively being worked on
+- **`blocked`** - Task blocked by another (see `blockedBy` field)
+- **`completed`** - Task finished
+
+## Markdown Format Details
+
+The markdown format is strict for correct parsing:
+
+**Correct:**
+```markdown
+### T-001: Task title [status]
+- **Owner**: Value
+- **Blocked by**: T-002
+- **Description**: Description text
+```
+
+**Incorrect (will not parse):**
+```markdown
+### T-001: Task title [status]
+- Owner: Value         # Missing **bold** markers
+- **Blocked By**: T-002  # Wrong case (must be "Blocked by")
+- **Description**: Description text
+# Extra blank lines between fields are ok
+```
+
+**Rules:**
+- Task header: `### T-NNN: Title [status]`
+- Field format: `- **Field name**: Value`
+- Field names are case-insensitive (will be normalized)
+- Extra blank lines, comments, headers are ignored
+- Tasks can have any fields beyond the standard ones
+
+## Thread Safety
+
+The system uses atomic writes (write to temp file, then rename) to prevent corruption if multiple processes write simultaneously. However, reads are NOT locked, so concurrent reads during writes may see partial data. For production use with high concurrency, implement file locking via `fcntl` or `flock`.
+
+## Testing
+
+Run the comprehensive test suite:
+
+```bash
+cd packages/cli
+npm test -- __tests__/scripts/lib/portable-tasks.test.js --no-coverage
+```
+
+Coverage:
+- 47 tests across all functions
+- Parsing, formatting, CRUD operations
+- Round-trip integrity (parse → modify → format → parse)
+- Error handling and edge cases
+- Integration workflows
+
+## Design Decisions
+
+1. **Markdown format** - Human-readable, diff-friendly, git-compatible (vs JSON/YAML)
+2. **Status-driven sections** - Completed/active sections based on task status, not location
+3. **Auto-ID generation** - Sequential IDs (T-001) simplify references
+4. **No dependencies** - Only Node.js built-ins to minimize install footprint
+5. **Lazy parsing** - Parse on load, format on save (vs streaming)
+6. **Fail-safe writes** - Atomic writes prevent corruption on crashes
+
+## Limitations
+
+- No encryption (store sensitive data elsewhere)
+- No versioning/history (file is current state only)
+- No concurrent write locking (implement if needed)
+- No real-time sync (changes require reload)
+- Task IDs are reassigned if you manually edit the file
+
+## Future Enhancements
+
+- [ ] Watch mode (monitor file for external changes)
+- [ ] Priority levels (high/medium/low)
+- [ ] Time tracking (estimated/actual hours)
+- [ ] Comments/notes per task
+- [ ] Subtasks (nested hierarchy)
+- [ ] Recurring tasks

package/scripts/lib/audit-cleanup.js

@@ -0,0 +1,250 @@
+/**
+ * audit-cleanup.js - Orphan cleanup for ULTRADEEP audit sessions
+ *
+ * Cleans up abandoned tmux sessions and incomplete sentinel directories
+ * from ULTRADEEP audit runs. Designed to be called from Stop hooks or
+ * manually for maintenance.
+ *
+ * Usage:
+ *   const { cleanupOrphanSessions } = require('./audit-cleanup');
+ *   cleanupOrphanSessions(rootDir);
+ *
+ * CLI:
+ *   node scripts/lib/audit-cleanup.js [--max-age=60] [--dry-run]
+ */
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const MAX_AGE_MINUTES = 60;
+
+/**
+ * Find all ultradeep trace directories.
+ * @param {string} rootDir - Project root
+ * @returns {Array<{ traceId: string, dir: string, status: object|null }>}
+ */
+function findTraceDirectories(rootDir) {
+  const ultradeepDir = path.join(rootDir, 'docs', '09-agents', 'ultradeep');
+
+  if (!fs.existsSync(ultradeepDir)) {
+    return [];
+  }
+
+  const traces = [];
+  try {
+    const entries = fs.readdirSync(ultradeepDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const traceDir = path.join(ultradeepDir, entry.name);
+      const statusFile = path.join(traceDir, '_status.json');
+      let status = null;
+
+      try {
+        if (fs.existsSync(statusFile)) {
+          status = JSON.parse(fs.readFileSync(statusFile, 'utf8'));
+        }
+      } catch (_) {
+        // Corrupt status file
+      }
+
+      traces.push({
+        traceId: entry.name,
+        dir: traceDir,
+        status,
+      });
+    }
+  } catch (_) {
+    // Directory read failure
+  }
+
+  return traces;
+}
+
+/**
+ * Check if a trace is stale (older than maxAge).
+ * @param {object} trace - Trace info from findTraceDirectories
+ * @param {number} maxAgeMinutes - Maximum age in minutes
+ * @returns {boolean}
+ */
+function isStaleTrace(trace, maxAgeMinutes) {
+  if (!trace.status || !trace.status.started_at) {
+    // No status = assume stale
+    return true;
+  }
+
+  const startedAt = new Date(trace.status.started_at).getTime();
+  if (isNaN(startedAt)) return true; // Invalid date = treat as stale
+  const age = Date.now() - startedAt;
+  return age > maxAgeMinutes * 60 * 1000;
+}
+
+/**
+ * Check if a trace is incomplete (not all analyzers have findings).
+ * @param {object} trace - Trace info from findTraceDirectories
+ * @returns {boolean}
+ */
+function isIncompleteTrace(trace) {
+  if (!trace.status || !trace.status.analyzers) return true;
+
+  const expected = trace.status.analyzers;
+  const completed = trace.status.completed || [];
+
+  return completed.length < expected.length;
+}
+
+/**
+ * Find orphaned tmux sessions matching audit pattern.
+ * @returns {string[]} Array of session names
+ */
+function findOrphanedTmuxSessions() {
+  try {
+    const output = execFileSync('tmux', ['list-sessions', '-F', '#{session_name}'], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+
+    if (!output) return [];
+
+    return output.split('\n').filter(name => name.startsWith('audit-'));
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * Kill a tmux session by name.
+ * @param {string} sessionName - Session name to kill
+ * @returns {boolean} True if killed successfully
+ */
+function killTmuxSession(sessionName) {
+  try {
+    execFileSync('tmux', ['kill-session', '-t', sessionName], {
+      stdio: 'pipe',
+    });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Remove a sentinel directory.
+ * @param {string} dir - Directory to remove
+ * @returns {boolean} True if removed successfully
+ */
+function removeSentinelDir(dir) {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Clean up orphaned ULTRADEEP audit sessions and stale sentinel dirs.
+ *
+ * @param {string} rootDir - Project root directory
+ * @param {object} [options] - Options
+ * @param {number} [options.maxAgeMinutes] - Max age for stale traces (default: 60)
+ * @param {boolean} [options.dryRun] - If true, report but don't delete
+ * @returns {{ sessionsKilled: string[], tracesRemoved: string[], errors: string[] }}
+ */
+function cleanupOrphanSessions(rootDir, options) {
+  const maxAge = (options && options.maxAgeMinutes) || MAX_AGE_MINUTES;
+  const dryRun = (options && options.dryRun) || false;
+
+  const result = {
+    sessionsKilled: [],
+    tracesRemoved: [],
+    errors: [],
+  };
+
+  // 1. Find and kill orphaned tmux sessions
+  const orphanedSessions = findOrphanedTmuxSessions();
+  for (const session of orphanedSessions) {
+    // Extract trace ID from session name: audit-{type}-{traceId}
+    const parts = session.split('-');
+    if (parts.length < 3) continue; // Malformed session name, skip
+    const traceId = parts.slice(2).join('-');
+
+    if (dryRun) {
+      result.sessionsKilled.push(`${session} (dry-run)`);
+      continue;
+    }
+
+    if (killTmuxSession(session)) {
+      result.sessionsKilled.push(session);
+    } else {
+      result.errors.push(`Failed to kill session: ${session}`);
+    }
+  }
+
+  // 2. Clean up stale sentinel directories
+  const traces = findTraceDirectories(rootDir);
+  for (const trace of traces) {
+    if (isStaleTrace(trace, maxAge) && isIncompleteTrace(trace)) {
+      if (dryRun) {
+        result.tracesRemoved.push(`${trace.traceId} (dry-run)`);
+        continue;
+      }
+
+      if (removeSentinelDir(trace.dir)) {
+        result.tracesRemoved.push(trace.traceId);
+      } else {
+        result.errors.push(`Failed to remove trace dir: ${trace.traceId}`);
+      }
+    }
+  }
+
+  return result;
+}
+
+// CLI
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  let maxAge = MAX_AGE_MINUTES;
+  let dryRun = false;
+
+  for (const arg of args) {
+    if (arg.startsWith('--max-age=')) {
+      const parsed = parseInt(arg.split('=')[1], 10);
+      maxAge = isNaN(parsed) ? MAX_AGE_MINUTES : parsed;
+    }
+    if (arg === '--dry-run') dryRun = true;
+  }
+
+  const rootDir = process.cwd();
+  const result = cleanupOrphanSessions(rootDir, { maxAgeMinutes: maxAge, dryRun });
+
+  if (result.sessionsKilled.length > 0) {
+    console.log(`Killed ${result.sessionsKilled.length} orphaned session(s):`);
+    result.sessionsKilled.forEach(s => console.log(`  - ${s}`));
+  }
+
+  if (result.tracesRemoved.length > 0) {
+    console.log(`Removed ${result.tracesRemoved.length} stale trace(s):`);
+    result.tracesRemoved.forEach(t => console.log(`  - ${t}`));
+  }
+
+  if (result.errors.length > 0) {
+    console.error(`${result.errors.length} error(s):`);
+    result.errors.forEach(e => console.error(`  - ${e}`));
+  }
+
+  if (result.sessionsKilled.length === 0 && result.tracesRemoved.length === 0) {
+    console.log('No orphaned sessions or stale traces found.');
+  }
+}
+
+module.exports = {
+  findTraceDirectories,
+  isStaleTrace,
+  isIncompleteTrace,
+  findOrphanedTmuxSessions,
+  killTmuxSession,
+  removeSentinelDir,
+  cleanupOrphanSessions,
+};