@fermindi/pwn-cli 0.5.0 → 0.7.0

package/src/ui/backlog-viewer.js

@@ -0,0 +1,394 @@
+/**
+ * PWN Backlog Viewer — Interactive TUI
+ *
+ * Navigable terminal viewer for prd.json stories.
+ * Uses raw readline + ANSI escape codes (no extra deps).
+ */
+
+import readline from 'readline';
+import chalk from 'chalk';
+
+/**
+ * Launch the interactive backlog viewer.
+ * @param {object} options
+ * @param {string} options.project - Project name
+ * @param {Array<object>} options.stories - Stories from prd.json
+ * @param {Array<object>} options.taskFiles - Task files from .ai/batch/tasks/
+ * @returns {Promise<void>} Resolves when user quits
+ */
+export function startViewer({ project, stories, taskFiles }) {
+  return new Promise((resolve) => {
+    if (stories.length === 0) {
+      console.log(chalk.yellow('No stories found in prd.json'));
+      resolve();
+      return;
+    }
+
+    let selectedIndex = 0;
+    let detailMode = false;   // true = full-screen detail view
+    let detailScroll = 0;     // scroll offset inside detail view
+    const taskMap = new Map(taskFiles.map(t => [t.id, t]));
+
+    function getStatus(story) {
+      if (story.passes) return 'done';
+      const tf = taskMap.get(story.id);
+      if (tf) {
+        if (tf.status === 'completed') return 'done';
+        if (tf.status === 'planned' || tf.status === 'running') return 'active';
+      }
+      return 'pending';
+    }
+
+    function statusIcon(status) {
+      if (status === 'done') return chalk.green('✅');
+      if (status === 'active') return chalk.yellow('🔄');
+      return chalk.dim('⏳');
+    }
+
+    function statusLabel(status) {
+      if (status === 'done') return chalk.green('done');
+      if (status === 'active') return chalk.yellow('active');
+      return chalk.dim('pending');
+    }
+
+    function truncate(str, maxLen) {
+      if (!str) return '';
+      if (str.length <= maxLen) return str;
+      return str.slice(0, maxLen - 1) + '…';
+    }
+
+    function buildDetailLines(story, cols) {
+      const status = getStatus(story);
+      const contentLines = [];
+
+      contentLines.push(chalk.bold(` ${story.id} · ${story.title}`));
+      contentLines.push('');
+
+      const phase = story.phase || '—';
+      const effort = story.effort || '—';
+      const deps = story.dependencies?.length > 0 ? story.dependencies.join(', ') : 'none';
+      contentLines.push(` Phase: ${phase}  |  Effort: ${effort}  |  Status: ${statusLabel(status)}  |  Deps: ${deps}`);
+      contentLines.push('');
+
+      if (story.acceptance_criteria?.length > 0) {
+        contentLines.push(chalk.bold(' Acceptance Criteria:'));
+        for (const ac of story.acceptance_criteria) {
+          const check = status === 'done' ? chalk.green('✓') : chalk.dim('○');
+          contentLines.push(`  ${check} ${truncate(ac, cols - 6)}`);
+        }
+        contentLines.push('');
+      }
+
+      if (story.notes) {
+        contentLines.push(chalk.bold(' Notes:'));
+        // Word-wrap notes to terminal width
+        const words = story.notes.split(' ');
+        let line = ' ';
+        for (const word of words) {
+          if (line.length + word.length + 1 > cols - 2) {
+            contentLines.push(chalk.dim(line));
+            line = ' ' + word;
+          } else {
+            line += (line.length > 1 ? ' ' : '') + word;
+          }
+        }
+        if (line.length > 1) contentLines.push(chalk.dim(line));
+        contentLines.push('');
+      }
+
+      // Show task file info if available
+      const tf = taskMap.get(story.id);
+      if (tf) {
+        contentLines.push(chalk.bold(' Batch Task Info:'));
+        if (tf.complexity) contentLines.push(`  Complexity: ${tf.complexity}`);
+        if (tf.estimated_time_seconds) contentLines.push(`  Estimated: ~${tf.estimated_time_seconds}s`);
+        if (tf.plan?.length > 0 && tf.plan[0] !== 'fallback - no plan available') {
+          contentLines.push(chalk.bold('  Plan:'));
+          for (const step of tf.plan) {
+            contentLines.push(`    · ${truncate(step, cols - 8)}`);
+          }
+        }
+        if (tf.failure_reason) {
+          contentLines.push(chalk.red(`  Failed: ${tf.failure_reason}`));
+        }
+        contentLines.push('');
+      }
+
+      return contentLines;
+    }
+
+    function renderDetailView() {
+      const rows = process.stdout.rows || 24;
+      const cols = process.stdout.columns || 80;
+      const story = stories[selectedIndex];
+
+      process.stdout.write('\x1b[H\x1b[2J');
+
+      const lines = [];
+
+      // Header
+      const header = `📋 ${story.id} — Detail View`;
+      const pos = `${selectedIndex + 1}/${stories.length}`;
+      const headerLine = `${header}${' '.repeat(Math.max(1, cols - header.length - pos.length - 2))}${pos}`;
+      lines.push(chalk.bold(headerLine));
+      lines.push(chalk.dim('─'.repeat(cols)));
+
+      // Build full content and apply scroll
+      const contentLines = buildDetailLines(story, cols);
+      const maxContent = rows - 4; // header(2) + footer(2)
+      const maxScroll = Math.max(0, contentLines.length - maxContent);
+      if (detailScroll > maxScroll) detailScroll = maxScroll;
+
+      const visible = contentLines.slice(detailScroll, detailScroll + maxContent);
+      for (const line of visible) {
+        lines.push(line);
+      }
+
+      // Scroll indicator
+      const scrollInfo = contentLines.length > maxContent
+        ? ` (${detailScroll + 1}-${Math.min(detailScroll + maxContent, contentLines.length)}/${contentLines.length})`
+        : '';
+
+      // Pad
+      while (lines.length < rows - 2) {
+        lines.push('');
+      }
+
+      lines.push(chalk.dim('─'.repeat(cols)));
+      lines.push(chalk.dim(`  ↑/k ↓/j scroll  ←/→ prev/next story  Esc/Backspace back to list  q quit${scrollInfo}`));
+
+      process.stdout.write(lines.join('\n'));
+    }
+
+    function render() {
+      if (detailMode) {
+        renderDetailView();
+        return;
+      }
+
+      const rows = process.stdout.rows || 24;
+      const cols = process.stdout.columns || 80;
+      const doneCount = stories.filter(s => getStatus(s) === 'done').length;
+
+      // Move cursor to top-left and clear screen
+      process.stdout.write('\x1b[H\x1b[2J');
+
+      const lines = [];
+
+      // Header
+      const header = `📋 Product Backlog — ${project}`;
+      const progress = `${doneCount}/${stories.length} done`;
+      const headerLine = `${header}${' '.repeat(Math.max(1, cols - header.length - progress.length - 2))}${progress}`;
+      lines.push(chalk.bold(headerLine));
+      lines.push(chalk.dim('─'.repeat(cols)));
+
+      // Story list — compute how many rows we can show
+      const detailReserved = 12; // lines reserved for detail panel + footer
+      const maxListRows = Math.max(3, rows - lines.length - detailReserved);
+
+      // Scrolling window
+      let scrollOffset = 0;
+      if (selectedIndex >= scrollOffset + maxListRows) {
+        scrollOffset = selectedIndex - maxListRows + 1;
+      }
+      if (selectedIndex < scrollOffset) {
+        scrollOffset = selectedIndex;
+      }
+
+      const visibleStories = stories.slice(scrollOffset, scrollOffset + maxListRows);
+
+      for (let i = 0; i < visibleStories.length; i++) {
+        const story = visibleStories[i];
+        const idx = scrollOffset + i;
+        const status = getStatus(story);
+        const icon = statusIcon(status);
+        const pointer = idx === selectedIndex ? chalk.cyan('▸') : ' ';
+        const id = chalk.bold(story.id);
+        const title = truncate(story.title, cols - story.id.length - 12);
+        const line = `  ${pointer} ${id}  ${title}  ${icon}`;
+        lines.push(idx === selectedIndex ? chalk.cyan(line) : line);
+      }
+
+      // Separator
+      lines.push(chalk.dim('─'.repeat(cols)));
+
+      // Detail panel for selected story
+      const story = stories[selectedIndex];
+      const status = getStatus(story);
+
+      lines.push(chalk.bold(` ${story.id} · ${story.title}`));
+
+      const phase = story.phase || '—';
+      const effort = story.effort || '—';
+      const deps = story.dependencies?.length > 0 ? story.dependencies.join(', ') : 'none';
+      lines.push(` Phase: ${phase}  |  Effort: ${effort}  |  Status: ${statusLabel(status)}  |  Deps: ${deps}`);
+      lines.push('');
+
+      // Acceptance criteria
+      if (story.acceptance_criteria?.length > 0) {
+        lines.push(chalk.bold(' Acceptance Criteria:'));
+        const remainingRows = rows - lines.length - 3; // leave room for notes + footer
+        const maxAC = Math.max(1, remainingRows - 2);
+        const acs = story.acceptance_criteria.slice(0, maxAC);
+        for (const ac of acs) {
+          const check = status === 'done' ? chalk.green('✓') : chalk.dim('○');
+          lines.push(`  ${check} ${truncate(ac, cols - 6)}`);
+        }
+        if (story.acceptance_criteria.length > maxAC) {
+          lines.push(chalk.dim(`  ... +${story.acceptance_criteria.length - maxAC} more — press Enter for full view`));
+        }
+      }
+
+      // Notes
+      if (story.notes) {
+        lines.push('');
+        lines.push(chalk.dim(` Notes: ${truncate(story.notes, cols - 10)}`));
+      }
+
+      // Pad to fill screen
+      while (lines.length < rows - 2) {
+        lines.push('');
+      }
+
+      // Footer separator + keybindings
+      lines.push(chalk.dim('─'.repeat(cols)));
+      lines.push(chalk.dim('  ↑/k up  ↓/j down  Enter detail  Home/End first/last  q quit'));
+
+      process.stdout.write(lines.join('\n'));
+    }
+
+    // Enter alternate screen buffer and hide cursor
+    process.stdout.write('\x1b[?1049h\x1b[?25l');
+
+    // Enable raw mode for keypress detection
+    readline.emitKeypressEvents(process.stdin);
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+
+    render();
+
+    function cleanup() {
+      // Restore screen buffer and show cursor
+      process.stdout.write('\x1b[?25h\x1b[?1049l');
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+      }
+      process.stdin.pause();
+      process.stdin.removeListener('keypress', onKeypress);
+      resolve();
+    }
+
+    function onKeypress(_str, key) {
+      if (!key) return;
+
+      if (key.name === 'q' || (key.ctrl && key.name === 'c')) {
+        cleanup();
+        return;
+      }
+
+      if (detailMode) {
+        // Detail view keybindings
+        if (key.name === 'escape' || key.name === 'backspace') {
+          detailMode = false;
+          detailScroll = 0;
+          render();
+        } else if (key.name === 'up' || key.name === 'k') {
+          if (detailScroll > 0) {
+            detailScroll--;
+            render();
+          }
+        } else if (key.name === 'down' || key.name === 'j') {
+          detailScroll++;
+          render();
+        } else if (key.name === 'left') {
+          if (selectedIndex > 0) {
+            selectedIndex--;
+            detailScroll = 0;
+            render();
+          }
+        } else if (key.name === 'right') {
+          if (selectedIndex < stories.length - 1) {
+            selectedIndex++;
+            detailScroll = 0;
+            render();
+          }
+        } else if (key.name === 'home') {
+          detailScroll = 0;
+          render();
+        } else if (key.name === 'end') {
+          detailScroll = 9999; // clamped in renderDetailView
+          render();
+        }
+        return;
+      }
+
+      // List view keybindings
+      if (key.name === 'return') {
+        detailMode = true;
+        detailScroll = 0;
+        render();
+      } else if (key.name === 'up' || key.name === 'k') {
+        if (selectedIndex > 0) {
+          selectedIndex--;
+          render();
+        }
+      } else if (key.name === 'down' || key.name === 'j') {
+        if (selectedIndex < stories.length - 1) {
+          selectedIndex++;
+          render();
+        }
+      } else if (key.name === 'home') {
+        selectedIndex = 0;
+        render();
+      } else if (key.name === 'end') {
+        selectedIndex = stories.length - 1;
+        render();
+      }
+    }
+
+    process.stdin.on('keypress', onKeypress);
+
+    // Handle terminal resize
+    process.stdout.on('resize', render);
+  });
+}
+
+/**
+ * Print backlog as plain text (non-interactive mode).
+ * @param {object} options
+ * @param {string} options.project - Project name
+ * @param {Array<object>} options.stories - Stories from prd.json
+ * @param {Array<object>} options.taskFiles - Task files from .ai/batch/tasks/
+ */
+export function printPlain({ project, stories, taskFiles }) {
+  if (stories.length === 0) {
+    console.log('No stories found in prd.json');
+    return;
+  }
+
+  const taskMap = new Map(taskFiles.map(t => [t.id, t]));
+
+  function getStatus(story) {
+    if (story.passes) return 'done';
+    const tf = taskMap.get(story.id);
+    if (tf) {
+      if (tf.status === 'completed') return 'done';
+      if (tf.status === 'planned' || tf.status === 'running') return 'active';
+    }
+    return 'pending';
+  }
+
+  const doneCount = stories.filter(s => getStatus(s) === 'done').length;
+
+  console.log(`\nProduct Backlog — ${project}  (${doneCount}/${stories.length} done)\n`);
+
+  for (const story of stories) {
+    const status = getStatus(story);
+    const icon = status === 'done' ? '[x]' : status === 'active' ? '[~]' : '[ ]';
+    console.log(`  ${icon} ${story.id}  ${story.title}`);
+  }
+
+  console.log('');
+}

package/templates/workspace/.ai/agents/claude.md

@@ -38,9 +38,9 @@ Read these files in order:
    - Ask user before deviating from active decisions
 
 2. **`/.ai/memory/patterns.md`**
-   - Index of patterns documented in `.ai/patterns/`
-   - Check which patterns exist for this project
-   - Add index entry when creating new pattern files
+   - Codebase patterns learned by team
+   - Apply these patterns to new work
+   - Add new patterns when discovered
 
 3. **`/.ai/memory/deadends.md`**
    - Failed approaches documented (DE-XXX)
@@ -71,10 +71,10 @@ If this is your first session:
    - Blocked items and blockers
    - Priority ordering
 
-2. **`/.ai/tasks/backlog.md`** (if needed)
-   - Future work not yet started
+2. **`/.ai/tasks/prd.json`** (if needed)
+   - Future work as structured JSON stories
    - Use when no active work assigned
-   - Pick highest priority unblocked item
+   - Pick next story with dependencies satisfied
 
 3. **Project-specific notes** (if applicable)
    - Check `/CLAUDE.md` in project root
@@ -208,42 +208,6 @@ If any gate fails:
 - Ask user if unsure how to proceed
 - Don't commit until gates pass
 
-### Pattern Checkpoint (Mandatory Before Commit)
-
-Before every commit, review the work done and check if any pattern should be documented.
-
-**Document a pattern when ANY of these criteria are met:**
-
-1. **User corrected your approach** - The user told you to do something differently. Document the correct approach so future sessions don't repeat the mistake.
-2. **You chose between alternatives** - You evaluated 2+ options and picked one. Document what was chosen and why.
-3. **Workaround for limitation** - A library, framework, or tool has a non-obvious limitation. Document the workaround.
-4. **Convention established** - First time implementing a certain type of thing in this codebase (first API route, first test, first component). Document the convention for consistency.
-5. **Repeated approach** - You used the same approach 2+ times in this session. Document it to avoid re-deriving it.
-6. **Non-trivial solution** - The solution wasn't obvious or took investigation to find. Document it so it's immediately available next time.
-
-**If a criterion is met:**
-
-1. Create pattern file: `.ai/patterns/{category}/{pattern-name}.md`
-   ```markdown
-   # Pattern Name
-
-   ## Context
-   When to apply this pattern.
-
-   ## Pattern
-   Description or code example.
-
-   ## Rationale
-   Why this approach works better.
-
-   ## Examples
-   - `src/path/file.ts:42`
-   ```
-2. Add index entry to `.ai/memory/patterns.md`
-3. Commit pattern files together with the code change
-
-**If no criteria are met:** proceed to commit normally. Don't force patterns that aren't there.
-
 ### Commit Message Format
 
 Use conventional commits:
@@ -281,9 +245,15 @@ When completing work:
    - [x] US-042: My completed task (YYYY-MM-DD)
    ```
 
-2. Document patterns following the **Pattern Checkpoint** criteria above
-   - Create file in `.ai/patterns/{category}/{name}.md`
-   - Add index entry in `.ai/memory/patterns.md`
+2. Update `/.ai/memory/patterns.md` if new pattern discovered
+   ```
+   ## New Pattern Category
+
+   ### Pattern Name
+   **Context:** When to use
+   **Pattern:** Description
+   **Rationale:** Why it's better
+   ```
 
 3. Add to `/.ai/memory/deadends.md` if approach failed
    ```
@@ -298,110 +268,41 @@ When completing work:
 
 ## Batch Mode
 
-When `session_mode` is "batch" (autonomous task execution):
+Autonomous task execution via `.ai/batch/batch_runner.sh`.
 
-### Your Role
-- Execute tasks from backlog autonomously
-- Follow quality gates strictly
-- Make conservative decisions (ask user when uncertain)
-- Commit and push changes automatically
-- Continue until backlog depleted or limits reached
+The runner reads stories from `.ai/tasks/prd.json`, spawns fresh Claude sessions
+per task, runs quality gates, and tracks progress.
 
-### Batch Workflow
-
-```
-1. Read tasks/active.md
-   ├─ If incomplete tasks: resume work
-   └─ If no active tasks: read backlog.md
-
-2. Select highest-priority unblocked task
-   ├─ Check dependencies
-   ├─ Verify not blocked
-   └─ Move to tasks/active.md
-
-3. Create feature branch
-   └─ Name: feature/{task-id}-{slug}
-
-4. Execute work following patterns
-   ├─ Auto-apply triggers from patterns/index.md
-   ├─ Keep commits atomic and descriptive
-   └─ Test incrementally
-
-5. Quality gates must pass
-   ├─ If gate fails:
-   │  ├─ Attempt auto-fix if pattern known
-   │  ├─ Pause batch if can't fix
-   │  └─ Notify user
-   └─ If all pass: proceed to commit
-
-6. Commit and push
-   ├─ Stage all changes
-   ├─ Commit with conventional format
-   ├─ Push to origin
-   └─ Create PR if configured
-
-7. Clean up and continue
-   ├─ Delete local feature branch
-   ├─ Update tasks/active.md
-   ├─ Check if more tasks to execute
-   └─ Continue or stop
-
-8. Completion report
-   └─ Show summary: tasks done, time spent, any issues
+### Usage
+```bash
+./.ai/batch/batch_runner.sh --dry-run    # Preview next task
+./.ai/batch/batch_runner.sh              # Run (default 20 iterations)
+./.ai/batch/batch_runner.sh 50           # Custom iteration limit
+./.ai/batch/batch_runner.sh --phase 3    # Specific phase only
 ```
 
-### Batch Configuration
-
-Read from `/.ai/state.json`:
+### State Files
+| File | Purpose |
+|------|---------|
+| .ai/tasks/prd.json | Single source of truth for task status |
+| .ai/batch/progress.txt | Append-only operational learnings |
+| .ai/batch/prompt.md | Prompt template for Claude sessions |
+| logs/ | Per-task Claude output logs |
 
-```json
-{
-  "batch_config": {
-    "max_tasks": 5,
-    "max_duration_hours": 4,
-    "quality_gates": ["typecheck", "lint", "test"],
-    "skip_gates": [],
-    "auto_commit": true,
-    "auto_push": false,
-    "create_pr": false,
-    "branch_format": "feature/{id}-{slug}",
-    "commit_format": "conventional"
-  }
-}
-```
-
-**Important:** Batch mode is conservative:
-- Don't skip quality gates without explicit config
-- Ask user if uncertain about task interpretation
-- Stop on first blocker and notify user
-- Don't force push or destructive operations
-- Log all decisions and timing
-
-### Batch Error Handling
-
-**Build/Test Fails:**
-- Show error with full context
-- If pattern known: auto-fix
-- If unsure: pause and notify user
-- Don't proceed without resolution
-
-**Git Conflicts:**
-- Stop immediately
-- Notify user of conflict
-- Require manual resolution
-- Resume after conflict resolved
-
-**Missing Dependencies:**
-- Check if dependency task exists
-- Add to batch queue if available
-- Execute dependency first
-- Resume original task
-
-**Resource Limits Reached:**
-- Stop execution gracefully
-- Report progress
-- Create clean state for next batch
-- Notify user of completion status
+### How It Works
+1. Read prd.json → find next incomplete story (deps satisfied)
+2. Spawn: `claude --print --dangerously-skip-permissions -p "implement story X"`
+3. Run quality gates (configurable per project)
+4. If pass → mark story done in prd.json, commit
+5. If fail → retry up to 2x with error context
+6. Append learnings to progress.txt
+7. Repeat until done or max iterations
+
+### Safety
+- Circuit breaker: 3 consecutive failures → stop
+- Rate limit detection + auto-wait
+- Graceful Ctrl+C shutdown
+- Per-task logs for debugging
 
 ---
 
@@ -430,7 +331,7 @@ Reference these files in this priority order:
    - Project changelog or git history
 
 5. **Fifth Priority: Planning**
-   - `/.ai/tasks/backlog.md` - Future work
+   - `/.ai/tasks/prd.json` - Future work (structured)
    - Roadmap or project documentation
    - Upstream issues or features
 
@@ -620,7 +521,7 @@ When finishing a session:
    - Add completion date if done
 
 3. **Document learnings**
-   - Document patterns in `.ai/patterns/` and index in `memory/patterns.md`
+   - Update `/.ai/memory/patterns.md` if discovered pattern
    - Update `/.ai/memory/deadends.md` if failed approach
    - Reference in commit messages