frankbria
diff --git a/‎CLAUDE.md‎
Lines changed: 25 additions & 1 deletion b/‎CLAUDE.md‎
Lines changed: 25 additions & 1 deletion
diff --git a/‎README.md‎
Lines changed: 61 additions & 1 deletion b/‎README.md‎
Lines changed: 61 additions & 1 deletion
diff --git a/‎docs/QUEUE_MANAGEMENT.md‎
Lines changed: 154 additions & 0 deletions b/‎docs/QUEUE_MANAGEMENT.md‎
Lines changed: 154 additions & 0 deletions
@@ -22,6 +22,7 @@ Ralph for Claude Code — an autonomous AI development loop system enabling cont
     - One `gh issue list --limit 500` query (server-side where gh supports it; exclude-label and title matching client-side via jq); candidates sorted oldest-first. Cap-hit handling (gh returns newest-first, so a capped set may be missing the true oldest matches): WARN for server-side-only queries; hard ERROR when client-side filters are active (they could pick the wrong issue or report zero matches over a truncated set)
     - `--select first|interactive|priority` picks among multiple matches: priority understands bare `P0`–`P9` and `priority: PN` labels (ties → oldest, none → first); interactive falls back to first on non-TTY/EOF. `--dry-run` previews the match table + would-be selection without importing
   - Completeness assessment + plan generation (Issue #70): issues are scored 0–100 via `lib/issue_analyzer.sh`; below `--completeness-threshold` (default 60) an implementation plan is generated via Claude CLI (`--plan-model` passthrough) and appended to the PRD before conversion, plus saved to `.ralph/specs/implementation-plan.md`. Flags: `--generate-plan` (force), `--no-generate-plan` (fail if below threshold), `--plan-model <model>`, `--completeness-threshold <0-100>`, `--auto-approve` (skip the approval prompt; non-TTY sessions auto-accept)
+- **ralph_queue.sh** — `ralph-queue` command: batch processing and issue queue management (Issue #72). Builds a persistent queue at `.ralph/queue.json` of GitHub issues (reuses `ralph_import.sh`'s `gh` machinery: `resolve_github_issue_candidates`, `fetch_github_issue`, `format_issue_as_prd`) or local PRD specs. Subcommands: `add` (`--github-issues N,N` | filter flags | `--prd <file>`), `status [--json]`, `next`, `remove`, `clear`, `reorder`, `validate`, `process [--halt-on-failure]`, `resume`. The sequential processor stages `.ralph/` from each ready item (priority + dependency order), runs the loop via `RALPH_LOOP_CMD` (default `ralph_loop.sh`; overridable for tests), commits `Fix #N: <title>` per issue, skips failures (or halts), and writes `.ralph/logs/queue_processing.log`. Single branch, no concurrency. See [docs/QUEUE_MANAGEMENT.md](docs/QUEUE_MANAGEMENT.md)
 - **ralph_enable.sh** — interactive wizard enabling Ralph in existing projects (environment detection, task source selection, generates `.ralphrc`)
 - **ralph_enable_ci.sh** — non-interactive version for CI/automation; `--json` output mode; exit codes: 0 (success), 1 (error), 2 (already enabled)
 
@@ -37,6 +38,7 @@ Ralph for Claude Code — an autonomous AI development loop system enabling cont
 - **issue_analyzer.sh** — `assess_issue_completeness()`: deterministic 0–100 heuristic scoring of issue PRDs (acceptance criteria +25, checklists/code blocks/sections/keywords/length +15 each); JSON output with `confidence_score`, `completeness_level`, `missing_elements`, `recommendation`; `log_issue_analysis()` for summaries
 - **file_protection.sh** — `validate_ralph_integrity()` checks `RALPH_REQUIRED_PATHS` exist; runs every loop iteration; `get_integrity_report()` for recovery instructions
 - **log_utils.sh** — `rotate_logs()` rotates `$LOG_DIR/ralph.log` at 10MB, keeping 4 archives (`.log.1`–`.log.4`); GNU `stat -c%s` with BSD `stat -f%z` fallback
+- **queue_manager.sh** — queue state primitives backing `ralph-queue` (Issue #72). State at `.ralph/queue.json` (`{version, created_at, updated_at, repository, queue:[…]}`); entries carry `id`/`source` (`github`|`prd`)/`issue_number`/`path`/`title`/`priority`/`labels`/`milestone`/`dependencies`/`status`/timestamps. Functions: `init_queue`, `add_to_queue` (dedupe by id, fills defaults; rc 0/1/2), `remove_from_queue`, `clear_queue`, `mark_issue_status` (validates status, stamps started/completed), `get_queue_status` (counts JSON), `sort_queue_by_priority` (rank then FIFO), `get_priority_from_labels` (reuses the P0–P9 / `priority: PN` parser), `parse_issue_dependencies` (`depends on/blocked by/requires #N`), `is_dependency_satisfied`, `get_next_issue` (ready+priority+FIFO), `validate_dependencies` (jq cycle detection). All mutations are atomic temp-file+`mv` via `_queue_apply`
 
 ## Key Commands
 
@@ -81,6 +83,28 @@ ralph --rollback                 # List available backup branches
 ralph --rollback ralph-backup-loop-3-1775155286   # Roll back to a specific backup
 ```
 
+### Batch Processing / Issue Queue (Issue #72)
+```bash
+# Build a queue (GitHub issues or local PRDs)
+ralph-queue add --github-label "bug,P0"      # filters reuse the ralph-import flags
+ralph-queue add --github-issues 69,70,71     # explicit list
+ralph-queue add --github-milestone "v1.0"
+ralph-queue add --prd ./docs/feature.md
+
+# Manage
+ralph-queue status [--json]      # also: ralph --queue-status
+ralph-queue next                 # also: ralph --queue-next
+ralph-queue reorder              # sort by priority (P0 first)
+ralph-queue validate             # detect circular dependencies
+ralph-queue remove 69            # also: ralph --queue-remove 69
+ralph-queue clear                # also: ralph --queue-clear
+
+# Process sequentially (priority + dependency order; one commit per issue)
+ralph --process-queue            # also: ralph-queue process
+ralph --process-queue --halt-on-failure
+ralph --resume-queue             # continue remaining pending items
+```
+
 ### Monitoring
 ```bash
 ralph-monitor                    # Manual monitoring in separate terminal
@@ -269,7 +293,7 @@ project-name/
 ## Global Installation
 
 `./install.sh` installs:
-- **Commands** → `~/.local/bin/`: `ralph`, `ralph-monitor`, `ralph-setup`, `ralph-import`, `ralph-migrate`, `ralph-enable`, `ralph-enable-ci`, `ralph-stats`
+- **Commands** → `~/.local/bin/`: `ralph`, `ralph-monitor`, `ralph-setup`, `ralph-import`, `ralph-queue`, `ralph-migrate`, `ralph-enable`, `ralph-enable-ci`, `ralph-stats`
 - **Scripts + templates** → `~/.ralph/` (main scripts, `templates/`, `lib/`)
 
 **External dependencies**: Claude Code CLI (execution engine), tmux (integrated monitoring), git (projects must be repos), jq (JSON processing), standard Unix tools.
 
@@ -179,7 +179,7 @@ cd ralph-claude-code
 ./install.sh
 ```
 
-This adds `ralph`, `ralph-monitor`, `ralph-setup`, `ralph-import`, `ralph-migrate`, `ralph-enable`, and `ralph-enable-ci` commands to your PATH.
+This adds `ralph`, `ralph-monitor`, `ralph-setup`, `ralph-import`, `ralph-queue`, `ralph-migrate`, `ralph-enable`, and `ralph-enable-ci` commands to your PATH.
 
 > **Note**: You only need to do this once per system. After installation, you can delete the cloned repository if desired.
 
@@ -485,6 +485,57 @@ Generated plans are shown for approval before conversion. Non-interactive sessio
 ### Troubleshooting
 - **"GitHub CLI (gh) is not installed"** — install it from https://cli.github.com
 - **"GitHub CLI is not authenticated"** — run `gh auth login`
+
+## Batch Processing and Issue Queue
+
+For larger efforts, the `ralph-queue` command builds a persistent queue of work items (GitHub issues or local PRD specs) and processes them sequentially, respecting priority and dependencies. The queue is stored at `.ralph/queue.json` and survives restarts, so an interrupted run can be resumed. See [docs/QUEUE_MANAGEMENT.md](docs/QUEUE_MANAGEMENT.md) for the full guide.
+
+### Building a queue
+
+```bash
+# Queue issues by metadata filter (reuses the import filter flags)
+ralph-queue add --github-label "bug,P0"
+ralph-queue add --github-milestone "v1.0"
+
+# Queue specific issues by number
+ralph-queue add --github-issues 69,70,71
+
+# Queue a local PRD/spec file
+ralph-queue add --prd ./docs/feature.md
+```
+
+When a GitHub issue is queued, its priority is read from `P0`–`P9` / `priority: PN` labels and its dependencies are parsed from the body (`depends on #N`, `blocked by #N`, `requires #N`).
+
+### Managing the queue
+
+```bash
+ralph-queue status            # Show the queue (counts + items); --json for machine output
+ralph-queue next              # Print the id of the next ready item
+ralph-queue reorder           # Sort the queue by priority (P0 first)
+ralph-queue validate          # Check for circular dependencies
+ralph-queue remove 69         # Remove an item by issue number or id
+ralph-queue clear             # Empty the queue
+```
+
+These are also available through `ralph` itself: `ralph --queue-status`, `ralph --queue-next`, `ralph --queue-clear`, and `ralph --queue-remove <id|N>`.
+
+### Processing the queue
+
+```bash
+# Process all ready pending items in priority/dependency order
+ralph --process-queue
+ralph-queue process
+
+# Stop at the first failure instead of skipping it
+ralph --process-queue --halt-on-failure
+
+# Resume after an interruption (only pending items are picked up)
+ralph --resume-queue
+```
+
+For each ready item the processor stages the project from the issue/spec, runs the Ralph loop, commits the work as `Fix #N: <title>` (one commit per issue when in a git repo), then advances. Failed items are marked `failed` and skipped by default (or halt the run with `--halt-on-failure`); items whose dependencies never complete remain `pending`. Progress is written to `.ralph/logs/queue_processing.log` and shown in the `ralph-monitor` dashboard.
+
+Concurrent (parallel) processing is intentionally out of scope — items are processed one at a time on a single branch.
 - **"Could not fetch issue #N"** — check the issue number, your repo access, and the `--repo` value
 - **"No issues match the specified filters"** — relax or remove some filters; only open issues are matched unless `--github-state closed|all` is given. `--dry-run` shows what a filter set matches.
 
@@ -952,6 +1003,12 @@ ralph [OPTIONS]
   --circuit-status        Show circuit breaker status
   --auto-reset-circuit    Auto-reset circuit breaker on startup (bypasses cooldown)
   --reset-session         Reset session state manually
+  --queue-status          Show the issue queue and exit
+  --process-queue         Process pending queued issues sequentially (--halt-on-failure to stop on first failure)
+  --resume-queue          Resume processing the remaining pending issues
+  --queue-next            Print the id of the next ready queued issue
+  --queue-clear           Remove all items from the queue
+  --queue-remove <id|N>   Remove one item from the queue
 ```
 
 > **Full reference**: every flag is documented in depth, with examples and `.ralphrc` patterns, in [docs/CLI_OPTIONS.md](docs/CLI_OPTIONS.md).
@@ -962,6 +1019,9 @@ ralph-setup project-name     # Create new Ralph project
 ralph-enable                 # Enable Ralph in existing project (interactive)
 ralph-enable-ci              # Enable Ralph in existing project (non-interactive)
 ralph-import prd.md project  # Convert PRD/specs to Ralph project
+ralph-queue add --github-label bug   # Build a batch queue of issues
+ralph-queue status           # Show the issue queue
+ralph --process-queue        # Process the queue sequentially
 ralph --monitor              # Start with integrated monitoring
 ralph --status               # Check current loop status
 ralph --verbose              # Enable detailed progress updates
 
@@ -0,0 +1,154 @@
+# Batch Processing and Issue Queue Management
+
+Ralph can work through multiple GitHub issues (or local PRD specs) in one
+autonomous session using a persistent, priority- and dependency-aware queue.
+This guide covers building, managing, and processing that queue.
+
+> Introduced in Issue #72. Requires the GitHub CLI (`gh`) and `jq` for the
+> GitHub-issue paths; the PRD path needs neither.
+
+## Concepts
+
+- **Queue file** — `.ralph/queue.json` in the current Ralph project. It is the
+  single source of truth and persists across restarts, so an interrupted run
+  can be resumed. It is created automatically the first time you add an item.
+- **Item** — one unit of work. A *github* item carries the issue number,
+  title, priority, labels, milestone, and parsed dependencies. A *prd* item
+  carries a path to a local spec file and a derived title.
+- **Status** — each item is `pending`, `processing`, `completed`, `failed`,
+  or `skipped`.
+- **Priority** — read from `P0`–`P9` or `priority: PN` labels (lower number =
+  higher priority). Items without a priority label sort last.
+- **Dependencies** — parsed from the issue body via `depends on #N`,
+  `blocked by #N`, and `requires #N` (case-insensitive). An item only becomes
+  *ready* once every dependency it references in the queue is `completed`.
+
+## Building a queue
+
+`ralph-queue add` accepts three kinds of sources.
+
+```bash
+# 1) Metadata filters — reuses the same flags as `ralph-import`
+ralph-queue add --github-label "bug,P0"            # ALL labels (comma = AND)
+ralph-queue add --github-milestone "v1.0"
+ralph-queue add --github-search "login timeout"
+ralph-queue add --github-title "[P0]*"             # * is the only wildcard
+ralph-queue add --github-assignee @me              # or a username, or none
+ralph-queue add --github-label bug --exclude-label wontfix
+ralph-queue add --github-state all                 # open (default), closed, all
+ralph-queue add --github-label bug --repo owner/repo
+
+# 2) Explicit issue numbers
+ralph-queue add --github-issues 69,70,71
+
+# 3) A local PRD/spec file
+ralph-queue add --prd ./docs/feature.md
+```
+
+Adding is idempotent — an item already in the queue (matched by id) is skipped
+with a warning, so re-running a filter add only appends what's new.
+
+## Managing the queue
+
+```bash
+ralph-queue status            # Human-readable table of items + counts
+ralph-queue status --json     # { total, pending, processing, completed, failed, skipped }
+ralph-queue next              # Print the id of the next ready item (or exit 1)
+ralph-queue reorder           # Persist a priority sort (P0 first, FIFO within a tier)
+ralph-queue validate          # Exit non-zero if a circular dependency exists
+ralph-queue remove 69         # Remove by issue number or id (e.g. github-69, prd-feature-md)
+ralph-queue clear             # Remove every item
+```
+
+The most common queries are mirrored on the `ralph` command itself:
+
+```bash
+ralph --queue-status
+ralph --queue-next
+ralph --queue-clear
+ralph --queue-remove 69
+```
+
+## Processing the queue
+
+```bash
+ralph --process-queue                  # or: ralph-queue process
+ralph --process-queue --halt-on-failure
+ralph --resume-queue                   # continue with the remaining pending items
+```
+
+For each ready item, in priority then FIFO order, the processor:
+
+1. Marks the item `processing`.
+2. Stages the project from the source — for a GitHub issue it writes
+   `.ralph/specs/issue-<N>.md` and points `.ralph/fix_plan.md` at it; for a PRD
+   it copies the spec into `.ralph/specs/`.
+3. Runs the Ralph loop (`ralph_loop.sh`) until it exits.
+4. On success, commits the work as `Fix #N: <title>` (one commit per issue,
+   when the project is a git repo) and marks the item `completed`.
+5. On a non-zero loop exit, marks the item `failed` and either skips it
+   (default) or halts the whole run (`--halt-on-failure`).
+6. Re-evaluates dependencies and moves to the next ready item.
+
+Items whose dependencies never complete stay `pending` and are reported at the
+end of the run. Resuming simply re-runs `process`: completed and failed items
+are left alone, and only ready `pending` items are picked up. Any item left in
+`processing` by an interrupted run (SIGKILL, power loss) is reset to `pending`
+at the start of the next `process`/`resume` so it is retried.
+
+Two things to know about processing:
+
+- **GitHub connectivity is needed at process time.** Each GitHub item is
+  re-fetched when it is processed (to use the freshest issue body), so
+  `process` requires `gh` access even when the items are already in
+  `queue.json`.
+- **PROMPT.md may gain a security fence.** If the project's `.ralph/PROMPT.md`
+  predates the "Handling Spec Content" untrusted-input fence, the processor
+  appends it (once) so the trust boundary described above is always present.
+
+### Progress and logging
+
+- `.ralph/logs/queue_processing.log` captures the loop output per item.
+- `ralph-queue status` (and `ralph --queue-status`) show live counts.
+- The `ralph-monitor` dashboard renders an **Issue Queue** panel
+  (completed/total, pending/active/failed, and the item currently processing)
+  whenever a non-empty `.ralph/queue.json` is present.
+
+## Security: queued content is untrusted input
+
+Processing a queued item feeds the issue body (or PRD) into an autonomous agent
+as the work to implement. Two protections apply:
+
+- **Comments are excluded.** Only the issue *body* is used (via
+  `format_issue_as_prd … false`); on public repos anyone can comment, so comment
+  text — a prime prompt-injection surface — never reaches the agent.
+- **Spec content is marked as data.** The generated `.ralph/PROMPT.md` instructs
+  the agent to treat spec files as requirements describing *what* to build and to
+  ignore any embedded instructions that try to change its task or tool
+  permissions (the same posture as `ralph-import`).
+
+Even so, the body is the work instruction by design. **Only queue issues you
+trust** (e.g. your own backlog or a maintained milestone), and review unfamiliar
+issues before processing them unattended.
+
+## Design notes and limits
+
+- **Single branch, one commit per issue.** Items are processed sequentially on
+  the current branch; there is no per-issue branching.
+- **Failures are isolated.** A failed item does not abort the run unless you
+  pass `--halt-on-failure`; this maximizes throughput across a backlog.
+- **Circular dependencies are refused.** `process` runs `validate` first and
+  stops if the dependency graph contains a cycle. Fix the cycle (or
+  `remove` an offending item) and retry.
+- **No concurrency.** Parallel processing is intentionally out of scope — the
+  queue is processed one item at a time.
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| `GitHub CLI (gh) is not installed` | Install `gh` (https://cli.github.com) |
+| `GitHub CLI is not authenticated` | `gh auth login` |
+| `circular dependency detected` | Run `ralph-queue validate`; remove or fix the cycle |
+| Items stuck `pending` after a run | Their dependencies failed or aren't in the queue — add/complete the dependency, then resume |
+| Query results were capped | Narrow your filters; very large result sets are truncated by `gh` |