From de82ccf00ff7c8338ce934c5548a4fbb70dbf62a Mon Sep 17 00:00:00 2001
From: Codevena <codevena@proton.me>
Date: Thu, 11 Jun 2026 07:32:51 +0100
Subject: [PATCH 1/3] docs: design spec for product improvements

Bundles five improvements: read-only --dry-run, --issue N, --check-cmd
test gate, Ctrl-C abort trap, and .fixbuddy.conf config files (+ wizard).
Captures the approved design decisions and integration points.
---
 .../2026-06-11-product-improvements-design.md | 185 ++++++++++++++++++
 1 file changed, 185 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-11-product-improvements-design.md

diff --git a/docs/superpowers/specs/2026-06-11-product-improvements-design.md b/docs/superpowers/specs/2026-06-11-product-improvements-design.md
new file mode 100644
index 0000000..00d421c
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-11-product-improvements-design.md
@@ -0,0 +1,185 @@
+# fixbuddy Product Improvements — Design
+
+Date: 2026-06-11
+Status: Approved (design), pending implementation plan
+
+Five independent improvements to `fixbuddy.sh` (and `fixbuddy-wizard.sh`), bundled into one
+round. Each is small-to-medium and touches a distinct region of the script. All line numbers
+reference the post-audit state of `fixbuddy.sh` (commit `5cadeb7` and later) and are
+indicative — implementation re-locates the exact spots.
+
+## Goals
+
+1. Make `--dry-run` truly read-only (currently a bug: it mutates labels before the dry-run check).
+2. Add `--issue N` to target specific issues.
+3. Add `--check-cmd` for a deterministic test gate before review/push.
+4. Add a Ctrl-C/abort trap that cleans up the in-flight branch so the next run resumes.
+5. Add `.fixbuddy.conf` config files (safe-parsed) plus wizard integration.
+
+## Non-Goals
+
+- No GitLab/forge abstraction, no parallelism/worktrees, no cost tracking (separate future work).
+- No change to the agent invocation, prompt builders, or the label state machine beyond what
+  each feature below requires.
+
+---
+
+## 1. Read-only `--dry-run`
+
+**Problem.** `$DRY_RUN` is only checked at `fixbuddy.sh:257`, but two mutating blocks run before
+it: the control-label creation loop (`175-184`, `gh label create --force`) and the
+fix:pr-open unstick scan (`186-221`, `gh issue edit --remove-label`). README/action.yml promise
+"without changing anything". The issue fetch (`224-255`) is read-only.
+
+**Design.**
+- Wrap the label-creation block and the unstick scan in `if ! $DRY_RUN; then … fi`. Suppress
+  their `info` lines ("Scanning for stuck…") under dry-run.
+- Keep the read-only fetch where it is; the dry-run exit stays after the fetch.
+- Improve the dry-run report (`257-262`):
+  - Print the planned config (fix/review agent, base branch, auto-merge, check-cmds) the run
+    *would* use — mirror the confirmation block at `264-273`.
+  - Respect `--max`: if `MAX` is set, show that the run would stop after `MAX` issues; list the
+    first `MAX` (or all when unset) instead of a silent `head -20`, and print the total
+    actionable count explicitly so nothing is hidden.
+
+**Error handling.** None new; fetch errors already fail closed (W4).
+
+**Test.** Run `--dry-run` against a repo and assert no labels are created and no
+`gh issue edit` is called (CI smoke test already runs dry-run on a runner with no agent CLIs).
+
+---
+
+## 2. `--issue N`
+
+**Design.**
+- New repeatable flag `--issue N` → `ISSUES+=("$2")`. Validate each value as a positive integer
+  in the validation block (alongside the W3 numeric checks): non-numeric → `err` + exit 2.
+- In the fetch/filter stage, when `ISSUES` is non-empty, restrict `filtered` to those numbers by
+  passing a JSON array into jq and adding `and (.number as $n | $wanted | index($n))` to the
+  existing select. The dedup filters (`fix:applied`, `fix:pr-open`, `fix:needs-human`,
+  `fix:rejected`, `fix:false-positive`, umbrella/meta) **remain active**.
+- After filtering, diff the requested numbers against the actionable set and `warn` for each
+  requested issue that was not found / not actionable (e.g. already `fix:applied`, closed, or
+  filtered out), so a silent skip never looks like success.
+- `--issue` composes with `--label`/`--severity` as an additional AND constraint.
+
+**Test.** `--issue` + `--dry-run` lists only the requested, actionable issues and warns about
+requested-but-skipped numbers.
+
+---
+
+## 3. `--check-cmd` (deterministic test gate)
+
+**Design.**
+- New repeatable flag `--check-cmd 'pnpm test'` → `CHECK_CMDS+=("$2")`.
+- Helper `run_checks()`:
+  - For each cmd: `( cd "$PROJECT" && eval "$cmd" ) >tmp 2>&1`; capture combined output.
+  - Return non-zero on the first failing command; expose the failing command + its output to the
+    caller (via stdout / a global). `eval` is acceptable: `--check-cmd` is operator-supplied
+    (same trust level as any CLI flag), unlike attacker-controlled issue content. This is
+    documented in the help text and the security note.
+- **Integration point** (in `process_issue`, the fix→review retry loop, ~`700-815`): after the
+  `DONE-FIX-APPLIED` marker check and the `commit_count` verification, and **before** the
+  `review_prompt` agent call (~`773`):
+  - If `CHECK_CMDS` is non-empty, run `run_checks`.
+  - On failure: set `feedback` to a labelled block ("Project checks failed:\n<cmd>\n<output>")
+    and re-enter the fix retry loop exactly like the `DONE-REJECTED` branch (decrement the
+    retry budget, loop back to the fix stage). On exhausted budget → `fix:rejected` via the same
+    path the review-reject uses, with the check output in the GitHub comment.
+  - On success: proceed to the review agent.
+- Because a PR is only opened after review approval, and review is only reached after checks
+  pass, checks gate the PR and therefore auto-merge — no change needed in the merge path.
+- The check output passed into the fix prompt is operator/tool output; it is embedded as
+  `feedback`, which is already sanitized before reuse (W8 path), so no new injection surface.
+
+**Error handling.** A missing check binary (e.g. `pnpm` absent) surfaces as a non-zero check →
+treated as a failed check (retry/reject), with the error text in the feedback. Document that
+check commands run in `$PROJECT`.
+
+**Test.** With `--check-cmd false`, a fix is never reviewed/pushed and the issue ends
+`fix:rejected` after the retry budget. With `--check-cmd true`, behavior is unchanged.
+
+---
+
+## 4. Ctrl-C / abort trap
+
+**Problem.** No `trap` exists. Aborting during FIX leaves `$PROJECT` on `fix/issue-N` with a
+dirty tree; the next run's preflight clean check then refuses to start.
+
+**Design.**
+- New globals (init empty near the other state vars ~`58`): `CURRENT_ISSUE`, `CURRENT_BRANCH`,
+  `CURRENT_AGENT_PID`, `CURRENT_WATCH_PID`.
+- `run_agent` sets `CURRENT_AGENT_PID=$agent_pid` / `CURRENT_WATCH_PID=$watch_pid` right after
+  launch, and clears both (`=""`) after the final `wait`.
+- `process_issue` sets `CURRENT_ISSUE` / `CURRENT_BRANCH` after the fix branch is created and
+  clears them at every return path / loop end.
+- `on_interrupt()` handler, registered once via `trap on_interrupt INT TERM` after the helper
+  functions are defined:
+  - `warn` that the run was interrupted and is cleaning up.
+  - Kill children then the agent/watchdog: `pkill -P "$CURRENT_AGENT_PID"`, `kill "$CURRENT_AGENT_PID"`
+    (guarded by non-empty), same for the watchdog PID.
+  - If `CURRENT_BRANCH` is set: `cleanup_branch "$CURRENT_ISSUE" "$CURRENT_BRANCH" "interrupted"`
+    (existing helper: stash dirty work → checkout base → `branch -D`). **No label is set.**
+  - `exit 130`.
+- No terminal label means the issue stays in the queue and is naturally retried next run (covers
+  the "Explicit resume mode" roadmap item via consistent label state).
+
+**Error handling.** `cleanup_branch` already swallows its own failures (`|| true`); the stash is
+recoverable via `git stash list` as documented elsewhere.
+
+**Test.** Hard to unit-test signals; verify by inspection + a manual SIGINT during a run leaves
+`$PROJECT` clean on the base branch with the fix branch gone and no new label on the issue.
+
+---
+
+## 5. `.fixbuddy.conf` config files
+
+**Design.**
+- **Locations & precedence** (lowest to highest): built-in defaults → `~/.fixbuddy/config`
+  (global) → `./.fixbuddy.conf` (current directory; the common case is `cd`-ing into the repo,
+  so CWD == project root and the file is the repo's checked-in config) → CLI flags.
+- **Loading order:** read global, then project config **before** the arg-parsing loop, populating
+  the same global variables. Arg parsing then runs last, so CLI flags override config naturally.
+  Scalars: last writer wins (CLI > project > global). Repeatable keys (`label`, `check_cmd`):
+  additive (config entries + CLI entries combine).
+- **Safe parser** `load_config(file)`:
+  - Skip blank lines and `#` comments. Split each line on the first `=`. Trim surrounding
+    whitespace from key and value. Strip one optional layer of matching surrounding quotes from
+    the value.
+  - Map the key (lower_snake) against an explicit allowlist and assign to the corresponding
+    variable. **No `source`, no `eval`** — values are only ever assigned as plain strings, so a
+    malicious config cannot execute code (worst case: a known variable holds a string).
+  - Unknown key → `warn "unknown config key '$k' in $file (ignored)"`.
+  - Boolean keys (`auto_merge`) accept `true`/`false` only; anything else warns and is ignored.
+- **Allowlisted keys → variables:** `repo→REPO`, `project→PROJECT`, `fix_agent→FIX_AGENT`,
+  `review_agent→REVIEW_AGENT`, `max→MAX`, `max_retries→MAX_RETRIES`,
+  `agent_timeout→AGENT_TIMEOUT`, `crash_abort→CRASH_ABORT_THRESHOLD`, `base→BASE_BRANCH`,
+  `severity→SEVERITY`, `skip_label→SKIP_LABEL`, `auto_merge→AUTO_MERGE`,
+  `label→LABELS+=` (repeatable), `check_cmd→CHECK_CMDS+=` (repeatable).
+- Numeric/agent/auto_merge values still pass through the existing validation block, so a bad
+  config value fails with the same clear error as a bad CLI value.
+- **Security note (documented):** config files are operator-controlled and trusted at the same
+  level as CLI flags. `check_cmd` from a config is executed by `run_checks`, consistent with the
+  threat model where only *issue* content is untrusted.
+
+**Wizard integration (`fixbuddy-wizard.sh`).**
+- After the command preview, add a prompt: "Save these settings to ./.fixbuddy.conf? [y/N]".
+  On yes, write the collected answers as `key = value` lines (only the keys the wizard gathered).
+  Then print that the next run can be just `fixbuddy.sh` (which reads the config).
+- Do not overwrite an existing `.fixbuddy.conf` without confirming.
+
+**Test.** A `.fixbuddy.conf` setting `max = 5` is honored; `--max 3` on the CLI overrides it to 3
+(CLI wins); an unknown key warns; a config with `source`-style content (e.g. `$(rm x)`) is stored
+as a literal string and never executed.
+
+---
+
+## Cross-cutting
+
+- **Help text / usage** (`sed -n '2,36p' "$0"` block at the top): document `--issue`,
+  `--check-cmd`, and `.fixbuddy.conf` precedence; note that `--check-cmd` runs operator-trusted
+  commands in `$PROJECT`.
+- **README**: add the new flags, the config-file section, and correct the dry-run wording.
+- **Static gate**: every change must keep `bash -n` and `shellcheck -S warning` clean.
+- **Ordering of work** (suggested): (1) dry-run read-only → (2) trap → (3) `--issue` →
+  (4) `--check-cmd` → (5) config + wizard. Each is independently committable and testable.

From 58c740cdfe8cae760b1b01a6a478c4e645867154 Mon Sep 17 00:00:00 2001
From: Codevena <codevena@proton.me>
Date: Thu, 11 Jun 2026 07:40:47 +0100
Subject: [PATCH 2/3] docs: revise product-improvements spec per Codex review

Incorporate Codex's design-review feedback:
- --check-cmd reuses the exact DONE-REJECTED retry/budget path; insertion
  point pinned before the review block; output capped/tailed
- add --auto-merge flag so the boolean is CLI-overridable both ways
- document additive label/check_cmd config keys (AND filter, not override)
- harden Ctrl-C trap: CURRENT_PUSHED guard (don't delete pushed branches),
  kill+wait children before git cleanup, disarm re-entrancy, best-effort PIDs
- config parser: strip CRLF, warn on malformed lines
- --issue fetches issues directly to dodge the 200-item list limit
- wizard writes to CWD with absolute-path notice + quoting
---
 .../2026-06-11-product-improvements-design.md | 102 ++++++++++++------
 1 file changed, 71 insertions(+), 31 deletions(-)

diff --git a/docs/superpowers/specs/2026-06-11-product-improvements-design.md b/docs/superpowers/specs/2026-06-11-product-improvements-design.md
index 00d421c..1b789f9 100644
--- a/docs/superpowers/specs/2026-06-11-product-improvements-design.md
+++ b/docs/superpowers/specs/2026-06-11-product-improvements-design.md
@@ -54,14 +54,17 @@ fix:pr-open unstick scan (`186-221`, `gh issue edit --remove-label`). README/act
 **Design.**
 - New repeatable flag `--issue N` → `ISSUES+=("$2")`. Validate each value as a positive integer
   in the validation block (alongside the W3 numeric checks): non-numeric → `err` + exit 2.
-- In the fetch/filter stage, when `ISSUES` is non-empty, restrict `filtered` to those numbers by
-  passing a JSON array into jq and adding `and (.number as $n | $wanted | index($n))` to the
-  existing select. The dedup filters (`fix:applied`, `fix:pr-open`, `fix:needs-human`,
-  `fix:rejected`, `fix:false-positive`, umbrella/meta) **remain active**.
-- After filtering, diff the requested numbers against the actionable set and `warn` for each
-  requested issue that was not found / not actionable (e.g. already `fix:applied`, closed, or
-  filtered out), so a silent skip never looks like success.
-- `--issue` composes with `--label`/`--severity` as an additional AND constraint.
+- When `ISSUES` is non-empty, **fetch each requested issue directly** (`gh issue view N --repo
+  "$REPO" --json number,title,labels,url,state,body`) instead of relying on the 200-item
+  `gh issue list` page (`224`). This guarantees a requested issue outside the first list page is
+  never silently missed (Codex NICE-TO-HAVE). Assemble these into the same JSON shape the loop
+  consumes.
+- The dedup filters (`fix:applied`, `fix:pr-open`, `fix:needs-human`, `fix:rejected`,
+  `fix:false-positive`, umbrella/meta) **remain active** on the directly-fetched issues, and
+  `--label`/`--severity` still apply as additional AND constraints.
+- For each requested number, `warn` distinctly when it is not found (no such issue / not in
+  `$REPO`), closed, or filtered out as non-actionable (already `fix:applied`, etc.), so a silent
+  skip never looks like success.
 
 **Test.** `--issue` + `--dry-run` lists only the requested, actionable issues and warns about
 requested-but-skipped numbers.
@@ -78,15 +81,22 @@ requested-but-skipped numbers.
     caller (via stdout / a global). `eval` is acceptable: `--check-cmd` is operator-supplied
     (same trust level as any CLI flag), unlike attacker-controlled issue content. This is
     documented in the help text and the security note.
-- **Integration point** (in `process_issue`, the fix→review retry loop, ~`700-815`): after the
-  `DONE-FIX-APPLIED` marker check and the `commit_count` verification, and **before** the
-  `review_prompt` agent call (~`773`):
+  - **Output cap:** tail the last ~200 lines / ~16 KB of combined output before handing it to the
+    caller (mirrors the 500 KB diff cap at `755-760`), so a huge test log cannot bloat the fix
+    prompt, the GitHub comment, or a shell variable (Codex IMPORTANT).
+- **Integration point** (in `process_issue`, the fix→review retry loop). The loop increments
+  `attempt` at its top (`686-687`) and the exhausted-budget reject path lives at `823-838`;
+  `--check-cmd` must **reuse that exact machinery, not a parallel budget**. After the
+  `DONE-FIX-APPLIED` marker check and the `commit_count` verification (`740-749`), and **before**
+  the review block — i.e. before the diff capture / diff-cap / worktree stash and before
+  `info "[#$num] REVIEW"` (`751-779`) so a failing local gate is never recorded as a review
+  attempt (Codex IMPORTANT):
   - If `CHECK_CMDS` is non-empty, run `run_checks`.
-  - On failure: set `feedback` to a labelled block ("Project checks failed:\n<cmd>\n<output>")
-    and re-enter the fix retry loop exactly like the `DONE-REJECTED` branch (decrement the
-    retry budget, loop back to the fix stage). On exhausted budget → `fix:rejected` via the same
-    path the review-reject uses, with the check output in the GitHub comment.
-  - On success: proceed to the review agent.
+  - On failure: set the **same** `feedback` variable the `DONE-REJECTED` branch uses (a labelled
+    block: "Project checks failed:\n<cmd>\n<capped output>") and fall through into the identical
+    reject/continue path — same `cleanup_branch`, same loop-continue, and on exhausted budget the
+    same `fix:rejected` label + GitHub comment (`823-838`). No new budget counter is introduced.
+  - On success: proceed to the review block / review agent.
 - Because a PR is only opened after review approval, and review is only reached after checks
   pass, checks gate the PR and therefore auto-merge — no change needed in the merge path.
 - The check output passed into the fix prompt is operator/tool output; it is embedded as
@@ -107,25 +117,38 @@ check commands run in `$PROJECT`.
 dirty tree; the next run's preflight clean check then refuses to start.
 
 **Design.**
-- New globals (init empty near the other state vars ~`58`): `CURRENT_ISSUE`, `CURRENT_BRANCH`,
-  `CURRENT_AGENT_PID`, `CURRENT_WATCH_PID`.
+- New globals (init empty/false near the other state vars ~`58`): `CURRENT_ISSUE`,
+  `CURRENT_BRANCH`, `CURRENT_AGENT_PID`, `CURRENT_WATCH_PID`, `CURRENT_PUSHED=false`.
 - `run_agent` sets `CURRENT_AGENT_PID=$agent_pid` / `CURRENT_WATCH_PID=$watch_pid` right after
   launch, and clears both (`=""`) after the final `wait`.
 - `process_issue` sets `CURRENT_ISSUE` / `CURRENT_BRANCH` after the fix branch is created and
-  clears them at every return path / loop end.
+  clears them (and resets `CURRENT_PUSHED=false`) at **every** return path / loop end.
+- **Push lifecycle (Codex IMPORTANT):** push/PR/labeling spans `843-925`. Set
+  `CURRENT_PUSHED=true` immediately after `git push` succeeds. Once a branch is pushed, its
+  remote branch + PR are durable and are reconciled next run by the `fix:pr-open`/unstick logic —
+  so the trap must **not** delete a pushed branch.
 - `on_interrupt()` handler, registered once via `trap on_interrupt INT TERM` after the helper
   functions are defined:
-  - `warn` that the run was interrupted and is cleaning up.
-  - Kill children then the agent/watchdog: `pkill -P "$CURRENT_AGENT_PID"`, `kill "$CURRENT_AGENT_PID"`
-    (guarded by non-empty), same for the watchdog PID.
-  - If `CURRENT_BRANCH` is set: `cleanup_branch "$CURRENT_ISSUE" "$CURRENT_BRANCH" "interrupted"`
-    (existing helper: stash dirty work → checkout base → `branch -D`). **No label is set.**
-  - `exit 130`.
+  1. **Disarm re-entrancy first:** `trap - INT TERM` so a second Ctrl-C cannot re-enter cleanup.
+  2. `warn` that the run was interrupted and is cleaning up.
+  3. **Kill, then `wait`, the children before any git op** (avoids racing an agent/git process
+     that is still exiting): `pkill -P "$CURRENT_AGENT_PID"` then `kill "$CURRENT_AGENT_PID"`
+     (guarded by non-empty), same for the watchdog PID, then `wait` on them. PID cleanup is
+     **best-effort**: `$!` captures the pipeline's last process, not a process-group handle, so
+     `pkill -P` + `kill` match the existing watchdog semantics rather than guaranteeing a full
+     process-group sweep.
+  4. If `CURRENT_BRANCH` is set **and `CURRENT_PUSHED` is false**:
+     `cleanup_branch "$CURRENT_ISSUE" "$CURRENT_BRANCH" "interrupted"` (existing helper: stash
+     dirty work → checkout base → `branch -D`). If already pushed, leave the local + remote branch
+     intact. **No label is set in either case.**
+  5. `exit 130`.
 - No terminal label means the issue stays in the queue and is naturally retried next run (covers
   the "Explicit resume mode" roadmap item via consistent label state).
 
 **Error handling.** `cleanup_branch` already swallows its own failures (`|| true`); the stash is
-recoverable via `git stash list` as documented elsewhere.
+recoverable via `git stash list` as documented elsewhere. `exit 130` from a trap is safe here
+because the script does not use `set -e` and already exits explicitly throughout
+(validation/fetch failures).
 
 **Test.** Hard to unit-test signals; verify by inspection + a manual SIGINT during a run leaves
 `$PROJECT` clean on the base branch with the fix branch gone and no new label on the issue.
@@ -142,10 +165,20 @@ recoverable via `git stash list` as documented elsewhere.
   the same global variables. Arg parsing then runs last, so CLI flags override config naturally.
   Scalars: last writer wins (CLI > project > global). Repeatable keys (`label`, `check_cmd`):
   additive (config entries + CLI entries combine).
+- **Additive-key caveat (Codex IMPORTANT):** because `label`/`check_cmd` are additive, a config
+  `label = bug` plus CLI `--label security` becomes an AND filter (`gh issue list --label bug
+  --label security`), not an override — a user **cannot remove** a config-provided label or
+  check from the CLI. This is intended but must be documented in the help text and the config
+  section of the README.
+- **Boolean override (Codex IMPORTANT):** today only `--no-auto-merge` exists. Add a matching
+  `--auto-merge` flag (sets `AUTO_MERGE=true`) so a global `auto_merge = false` can be overridden
+  back to true from the CLI, honouring "CLI wins" in both directions.
 - **Safe parser** `load_config(file)`:
-  - Skip blank lines and `#` comments. Split each line on the first `=`. Trim surrounding
-    whitespace from key and value. Strip one optional layer of matching surrounding quotes from
-    the value.
+  - Skip blank lines and `#` comments. **Strip a trailing `\r`** from each line so CRLF
+    (Windows-authored) configs parse cleanly. A non-comment, non-blank line **without `=`** →
+    `warn "malformed config line in $file: <line>"` and skip (Codex IMPORTANT).
+  - Split each line on the first `=`. Trim surrounding whitespace from key and value. Strip one
+    optional layer of matching surrounding quotes from the value.
   - Map the key (lower_snake) against an explicit allowlist and assign to the corresponding
     variable. **No `source`, no `eval`** — values are only ever assigned as plain strings, so a
     malicious config cannot execute code (worst case: a known variable holds a string).
@@ -166,6 +199,13 @@ recoverable via `git stash list` as documented elsewhere.
 - After the command preview, add a prompt: "Save these settings to ./.fixbuddy.conf? [y/N]".
   On yes, write the collected answers as `key = value` lines (only the keys the wizard gathered).
   Then print that the next run can be just `fixbuddy.sh` (which reads the config).
+- **Location footgun (Codex IMPORTANT):** the wizard writes to `./.fixbuddy.conf` in the **CWD**,
+  consistent with where fixbuddy reads the project config. Print the **absolute path** written,
+  and if `CWD != PROJECT`, `warn` that the config lives in the launch directory ("run fixbuddy
+  from here, or move `.fixbuddy.conf` to where you'll run it"). This keeps the simple CWD model
+  while removing the silent-mismatch trap.
+- **Quote on write:** values containing spaces or `#` (repo paths, project paths, check commands)
+  must be written quoted in the parser's supported quoting form, so they round-trip correctly.
 - Do not overwrite an existing `.fixbuddy.conf` without confirming.
 
 **Test.** A `.fixbuddy.conf` setting `max = 5` is honored; `--max 3` on the CLI overrides it to 3
@@ -177,8 +217,8 @@ as a literal string and never executed.
 ## Cross-cutting
 
 - **Help text / usage** (`sed -n '2,36p' "$0"` block at the top): document `--issue`,
-  `--check-cmd`, and `.fixbuddy.conf` precedence; note that `--check-cmd` runs operator-trusted
-  commands in `$PROJECT`.
+  `--check-cmd`, `--auto-merge`, and `.fixbuddy.conf` precedence (incl. the additive-key caveat);
+  note that `--check-cmd` runs operator-trusted commands in `$PROJECT`.
 - **README**: add the new flags, the config-file section, and correct the dry-run wording.
 - **Static gate**: every change must keep `bash -n` and `shellcheck -S warning` clean.
 - **Ordering of work** (suggested): (1) dry-run read-only → (2) trap → (3) `--issue` →

From a900fdb1b09f6efa7efb4182fefedc24c997e908 Mon Sep 17 00:00:00 2001
From: Codevena <codevena@proton.me>
Date: Thu, 11 Jun 2026 08:33:42 +0100
Subject: [PATCH 3/3] feat: dry-run read-only, --issue, --check-cmd, abort
 trap, config files

Implements the five approved product improvements (see
docs/superpowers/specs/2026-06-11-product-improvements-design.md):

- --dry-run is now fully read-only: label creation, the fix:pr-open
  unstick scan, and the dirty-worktree preflight are skipped; the report
  shows the planned config + check commands and respects --max.
- --issue N (repeatable): process specific issues, fetched directly via
  `gh issue view` (no 200-item list blind spot); dedup filters and
  --label/--severity still apply; non-actionable numbers warn distinctly.
- --check-cmd (repeatable): deterministic test gate run in the project dir
  after the fix commit and before review; failure shares the exact
  review-rejection retry path (same budget, fix:rejected on exhaustion),
  so it also gates auto-merge. Output is capped (200 lines / 16 KB).
- Ctrl-C/abort trap: kills the in-flight agent (PIDs via a shared file,
  since run_agent runs in a command-substitution subshell), SIGTERM ->
  SIGKILL escalation, then local-only branch cleanup (remote branch/PR
  survive). No label is set, so the issue resumes next run.
- .fixbuddy.conf config files: safe-parsed (no eval/source) from
  ~/.fixbuddy/config then ./.fixbuddy.conf, before arg parsing so CLI
  wins; allowlisted keys, additive label/check_cmd; new --auto-merge flag;
  the wizard offers to write the config; action.yml passes the flag both
  ways.

Reviewed via the DoD pipeline (Codex x2 + Claude x2): all PASS.
---
 README.md                                     |  81 ++++-
 action.yml                                    |   2 +-
 .../2026-06-11-product-improvements-design.md |  47 +--
 fixbuddy-wizard.sh                            |  74 +++-
 fixbuddy.sh                                   | 331 ++++++++++++++++--
 5 files changed, 481 insertions(+), 54 deletions(-)

diff --git a/README.md b/README.md
index f870abc..afbe433 100644
--- a/README.md
+++ b/README.md
@@ -104,11 +104,65 @@ These agent invocations are intentionally powerful. Run fixbuddy only against re
 | `--agent-timeout <secs>` | Wall-clock timeout per agent call | `1200` |
 | `--crash-abort <n>` | Abort after consecutive agent crashes | `3` |
 | `--base <branch>` | PR base branch | auto-detect |
+| `--issue <N>` | Process only this issue number. Repeatable; dedup filters and `--label`/`--severity` still apply. Warns for requested numbers that are not found, closed, or already labeled non-actionable | none |
+| `--check-cmd <cmd>` | Shell command to run as a test gate after each fix commit and before review. Repeatable. A non-zero exit is treated as a review rejection: output is fed back to the fix agent and the attempt is retried; if the retry budget is exhausted the issue is labeled `fix:rejected`. Because review and PR are only reached after all checks pass, checks also gate auto-merge. Commands run in `$PROJECT` and are operator-trusted (same trust level as CLI flags) | none |
+| `--auto-merge` | Enable auto-merge, overriding a config `auto_merge = false` | off |
 | `--no-auto-merge` | Open PRs without requesting auto-merge | off |
 | `--skip-label <label>` | Skip issues with this label | `fix:applied` |
-| `--dry-run` | List target issues without changing anything | off |
+| `--dry-run` | List issues that would be processed, with the planned config, without making any changes (no labels created, no issues edited) | off |
 | `-y`, `--yes` | Skip confirmation | off |
 
+## Configuration file
+
+fixbuddy reads `key = value` config files (blank lines and `#` comments ignored) from two locations, applied in precedence order from lowest to highest:
+
+1. `~/.fixbuddy/config` — global defaults applied to every run
+2. `./.fixbuddy.conf` — per-project config in the current working directory (the common case is running fixbuddy from the repo root)
+3. CLI flags — always win over any config value
+
+**Format example:**
+
+```ini
+# .fixbuddy.conf
+repo        = owner/repo
+project     = /home/user/code/repo
+fix_agent   = claude
+review_agent = codex
+max         = 10
+severity    = high
+auto_merge  = true
+label       = bug
+check_cmd   = pnpm test
+check_cmd   = pnpm typecheck
+```
+
+**Allowlisted keys** (unknown keys warn and are ignored):
+
+| Key | Equivalent flag | Notes |
+| --- | --- | --- |
+| `repo` | `--repo` | |
+| `project` | `--project` | |
+| `fix_agent` | `--fix-agent` | |
+| `review_agent` | `--review-agent` | |
+| `max` | `--max` | |
+| `max_retries` | `--max-retries` | |
+| `agent_timeout` | `--agent-timeout` | |
+| `crash_abort` | `--crash-abort` | |
+| `base` | `--base` | |
+| `severity` | `--severity` | |
+| `skip_label` | `--skip-label` | |
+| `auto_merge` | `--auto-merge` / `--no-auto-merge` | accepts `true` or `false` |
+| `label` | `--label` | additive (see below) |
+| `check_cmd` | `--check-cmd` | additive (see below) |
+
+**Scalar keys** (all keys except `label` and `check_cmd`): CLI value wins; last writer wins across config files (project overrides global).
+
+**Additive keys** (`label`, `check_cmd`): config entries and CLI entries are combined, not replaced. A config `label = bug` plus `--label security` on the CLI results in an AND filter for both labels. There is no way to remove a config-provided label or check command from the CLI.
+
+**Security note:** config files are operator-controlled and parsed without `eval` or `source`. Values are assigned as plain strings, so a config containing shell metacharacters (e.g. `$(...)`) cannot execute code. `check_cmd` entries are run by fixbuddy itself, consistent with the same operator-trust model as CLI flags — only issue *content* is treated as untrusted input.
+
+**Wizard:** running `fixbuddy-wizard.sh` offers to save the collected settings to `./.fixbuddy.conf` at the end. The absolute path written is printed, and a warning is shown if the current directory differs from `--project`, since fixbuddy reads the project config from wherever it is launched.
+
 ## Labels
 
 fixbuddy creates and manages these labels:
@@ -150,12 +204,26 @@ Useful markers:
 
 ## Examples
 
-Preview targets:
+Preview targets (no writes at all — no labels created, no issues edited):
 
 ```bash
 ./fixbuddy.sh --repo owner/repo --project ~/code/repo --severity high --dry-run
 ```
 
+Fix specific issues only:
+
+```bash
+./fixbuddy.sh --repo owner/repo --project ~/code/repo --issue 42 --issue 57
+```
+
+Add a test gate so fixes are never reviewed unless all checks pass:
+
+```bash
+./fixbuddy.sh --repo owner/repo --project ~/code/repo \
+  --check-cmd 'pnpm test' --check-cmd 'pnpm typecheck' \
+  --fix-agent claude --review-agent codex
+```
+
 Open PRs but do not request auto-merge:
 
 ```bash
@@ -245,7 +313,7 @@ The action does not read API keys itself; each agent CLI reads its own environme
 
 The action does **not** run `actions/checkout` for you — your workflow controls the checkout. fixbuddy refuses to run against a dirty working tree, but a fresh CI checkout is always clean, so this is a non-issue in practice.
 
-A `dry-run: "true"` input lists target issues without invoking any agent — useful for a first run, and it needs no API keys or agent CLIs at all.
+A `dry-run: "true"` input lists target issues (with the planned config) without invoking any agent and without making any changes — useful for a first run, and it needs no API keys or agent CLIs at all.
 
 ### Logs
 
@@ -263,8 +331,8 @@ The action copies each run's logs into `fixbuddy-logs/` in the workspace. Add an
 | `label` | `--label` (comma-separated, becomes repeated flags) | none |
 | `max` | `--max` | `5` |
 | `base-branch` | `--base` | auto-detect |
-| `auto-merge` | `--no-auto-merge` when `false` | `true` |
-| `dry-run` | `--dry-run` when `true` | `false` |
+| `auto-merge` | `--no-auto-merge` when `false`; `--auto-merge` when `true` | `true` |
+| `dry-run` | `--dry-run` when `true` — lists targets, makes no changes | `false` |
 | `github-token` | `GH_TOKEN` for `gh` | `${{ github.token }}` |
 
 Running fixbuddy in CI gives AI agents repository write access through whatever token you hand them. Read [SECURITY.md](SECURITY.md) before enabling this on a repository that matters.
@@ -288,10 +356,9 @@ Native Windows is not tested. WSL2 is the recommended Windows environment.
 
 ## Roadmap
 
-- Config file support
 - More deterministic integration tests with mocked CLIs
 - Optional notifications for run summaries
-- Explicit resume mode for interrupted runs
+- Explicit resume mode for interrupted runs (interrupting a run cleans up the in-progress branch; the issue is retried automatically on the next run)
 
 ## Contributing
 
diff --git a/action.yml b/action.yml
index c7b9220..4015066 100644
--- a/action.yml
+++ b/action.yml
@@ -95,7 +95,7 @@ runs:
 
         if [ -n "$FIXBUDDY_SEVERITY" ]; then cmd+=(--severity "$FIXBUDDY_SEVERITY"); fi
         if [ -n "$FIXBUDDY_BASE" ]; then cmd+=(--base "$FIXBUDDY_BASE"); fi
-        if [ "$FIXBUDDY_AUTO_MERGE" = "false" ]; then cmd+=(--no-auto-merge); fi
+        if [ "$FIXBUDDY_AUTO_MERGE" = "false" ]; then cmd+=(--no-auto-merge); else cmd+=(--auto-merge); fi
         if [ "$FIXBUDDY_DRY_RUN" = "true" ]; then cmd+=(--dry-run); fi
 
         # Comma-separated labels become repeated --label flags. Each entry is
diff --git a/docs/superpowers/specs/2026-06-11-product-improvements-design.md b/docs/superpowers/specs/2026-06-11-product-improvements-design.md
index 1b789f9..e18cec2 100644
--- a/docs/superpowers/specs/2026-06-11-product-improvements-design.md
+++ b/docs/superpowers/specs/2026-06-11-product-improvements-design.md
@@ -118,29 +118,34 @@ dirty tree; the next run's preflight clean check then refuses to start.
 
 **Design.**
 - New globals (init empty/false near the other state vars ~`58`): `CURRENT_ISSUE`,
-  `CURRENT_BRANCH`, `CURRENT_AGENT_PID`, `CURRENT_WATCH_PID`, `CURRENT_PUSHED=false`.
-- `run_agent` sets `CURRENT_AGENT_PID=$agent_pid` / `CURRENT_WATCH_PID=$watch_pid` right after
-  launch, and clears both (`=""`) after the final `wait`.
+  `CURRENT_BRANCH`, `CURRENT_PUSHED=false`, and `AGENT_PIDFILE`.
+- **PID visibility (Codex CRITICAL):** `run_agent` runs inside a command-substitution subshell
+  (`out=$(run_agent …)`), so any variable it assigns is invisible to the parent shell where the
+  trap runs. The agent/watchdog PIDs are therefore written to a **file** (`AGENT_PIDFILE`,
+  created via `mktemp` before the main loop) by `run_agent`, and cleared after the agent is
+  reaped. A file written by the subshell IS visible to the parent.
 - `process_issue` sets `CURRENT_ISSUE` / `CURRENT_BRANCH` after the fix branch is created and
-  clears them (and resets `CURRENT_PUSHED=false`) at **every** return path / loop end.
-- **Push lifecycle (Codex IMPORTANT):** push/PR/labeling spans `843-925`. Set
-  `CURRENT_PUSHED=true` immediately after `git push` succeeds. Once a branch is pushed, its
-  remote branch + PR are durable and are reconciled next run by the `fix:pr-open`/unstick logic —
-  so the trap must **not** delete a pushed branch.
-- `on_interrupt()` handler, registered once via `trap on_interrupt INT TERM` after the helper
-  functions are defined:
+  the main loop clears all three (incl. `CURRENT_PUSHED`) after `process_issue` returns, so every
+  return path is covered without per-path resets.
+- **Push lifecycle:** set `CURRENT_PUSHED=true` immediately after `git push` succeeds. This is
+  **informational only** (used for a clarifying log line) — see the cleanup rule below.
+- `on_interrupt()` handler, registered via `trap on_interrupt INT TERM` after the helpers are
+  defined (and disarmed on normal exit):
   1. **Disarm re-entrancy first:** `trap - INT TERM` so a second Ctrl-C cannot re-enter cleanup.
-  2. `warn` that the run was interrupted and is cleaning up.
-  3. **Kill, then `wait`, the children before any git op** (avoids racing an agent/git process
-     that is still exiting): `pkill -P "$CURRENT_AGENT_PID"` then `kill "$CURRENT_AGENT_PID"`
-     (guarded by non-empty), same for the watchdog PID, then `wait` on them. PID cleanup is
-     **best-effort**: `$!` captures the pipeline's last process, not a process-group handle, so
-     `pkill -P` + `kill` match the existing watchdog semantics rather than guaranteeing a full
-     process-group sweep.
-  4. If `CURRENT_BRANCH` is set **and `CURRENT_PUSHED` is false**:
-     `cleanup_branch "$CURRENT_ISSUE" "$CURRENT_BRANCH" "interrupted"` (existing helper: stash
-     dirty work → checkout base → `branch -D`). If already pushed, leave the local + remote branch
-     intact. **No label is set in either case.**
+  2. `warn` that the run was interrupted and is cleaning up (no label set).
+  3. **Kill children + process for BOTH the agent and the watchdog**, reading their PIDs from
+     `AGENT_PIDFILE`: `pkill -P "$pid"` then `kill "$pid"`. We cannot `wait` on them (they are
+     children of a command-substitution subshell, not of this shell), so **poll `kill -0`**:
+     ~5 s SIGTERM grace, then escalate to **SIGKILL** (`pkill -KILL -P` + `kill -KILL`) and a
+     short settle, so cleanup never runs while a wedged agent is still writing to the worktree.
+  4. If `CURRENT_BRANCH` is set, **always** run
+     `cleanup_branch "$CURRENT_ISSUE" "$CURRENT_BRANCH" "interrupted"`. `cleanup_branch` is
+     **local-only** (stash dirty WIP → checkout base → `git branch -D` the LOCAL branch); it
+     never touches the remote. Deleting the local branch is therefore harmless to an open PR
+     (which references `origin/fix/issue-N`): when `CURRENT_PUSHED` is true, the **remote branch
+     and PR survive intact** and are reconciled next run by the `fix:pr-open`/unstick logic; a
+     pushed-but-not-yet-PR'd branch is reused on the next run (the existing "PR already open"
+     path prevents duplicates). **No label is set in any case.**
   5. `exit 130`.
 - No terminal label means the issue stays in the queue and is naturally retried next run (covers
   the "Explicit resume mode" roadmap item via consistent label state).
diff --git a/fixbuddy-wizard.sh b/fixbuddy-wizard.sh
index c92a87d..5b9f1d4 100755
--- a/fixbuddy-wizard.sh
+++ b/fixbuddy-wizard.sh
@@ -264,6 +264,79 @@ for arg in "${CMD[@]}"; do
 done
 printf "%s\n\n" "$RST"
 
+# -------- Offer to save .fixbuddy.conf --------
+# Offered BEFORE "Start now?" so a user who declines to run can still save the settings.
+# conf_val: return value quoted if the string contains spaces or '#',
+# otherwise bare — so it round-trips through a parser that strips one
+# surrounding matching-quote layer.
+conf_val() {
+  local v="$1"
+  case "$v" in
+    *' '*|*'#'*) printf '"%s"' "$v" ;;
+    *)           printf '%s'   "$v" ;;
+  esac
+}
+
+CONF_PATH="$(pwd)/.fixbuddy.conf"
+step "9." "Save these settings to .fixbuddy.conf?"
+note "  → $CONF_PATH"
+ask "Save settings? [y/N]:"
+read -r save_ans
+case "$save_ans" in
+  [yY]|[yY][eE][sS])
+    # If file already exists, ask before overwriting.
+    if [ -f "$CONF_PATH" ]; then
+      ask ".fixbuddy.conf already exists. Overwrite? [y/N]:"
+      read -r overwrite_ans
+      case "$overwrite_ans" in
+        [yY]|[yY][eE][sS]) ;;
+        *) note "skipped — existing config left unchanged."; ;;
+      esac
+      # Re-check so we only write when overwrite was confirmed.
+      case "$overwrite_ans" in
+        [yY]|[yY][eE][sS]) : ;;
+        *) unset CONF_PATH ;;
+      esac
+    fi
+
+    if [ -n "$CONF_PATH" ]; then
+      {
+        printf '# .fixbuddy.conf — generated by fixbuddy-wizard\n'
+        printf 'repo          = %s\n' "$(conf_val "$REPO")"
+        printf 'project       = %s\n' "$(conf_val "$PROJECT")"
+        printf 'fix_agent     = %s\n' "$(conf_val "$FIX_AGENT")"
+        printf 'review_agent  = %s\n' "$(conf_val "$REVIEW_AGENT")"
+        # severity: only write when a specific level was chosen (not "all").
+        if [ -n "$SEVERITY" ]; then
+          printf 'severity      = %s\n' "$(conf_val "$SEVERITY")"
+        fi
+        # max: only write when a numeric limit was chosen.
+        if [ "${#MAX_FLAG[@]}" -gt 0 ]; then
+          # MAX_FLAG is (--max N); the value is the second element.
+          printf 'max           = %s\n' "${MAX_FLAG[1]}"
+        fi
+        # auto_merge: meaningful only for careful/autonomous modes, not dry-run.
+        case "$MODE_LABEL" in
+          autonomous) printf 'auto_merge    = true\n'  ;;
+          careful)    printf 'auto_merge    = false\n' ;;
+        esac
+      } > "$CONF_PATH"
+      ok "written: $CONF_PATH"
+      # Warn when CWD differs from the chosen project directory, because
+      # fixbuddy reads .fixbuddy.conf from wherever it is launched.
+      if [ "$(pwd)" != "$PROJECT" ]; then
+        printf "  ${RED}!${RST} Config is in launch dir, not project dir.\n"
+        note "Run fixbuddy from $(pwd), or move .fixbuddy.conf into $PROJECT"
+      fi
+      note "Next time you can just run: fixbuddy.sh"
+    fi
+    ;;
+  *)
+    note "skipped — no config written."
+    ;;
+esac
+
+# -------- Confirm + Run --------
 ask "Start now? [y/N]:"
 read -r go
 case "$go" in
@@ -271,5 +344,4 @@ case "$go" in
   *) note "aborted — copy the command above to run later."; exit 0 ;;
 esac
 
-# -------- Run --------
 exec "${CMD[@]}"
diff --git a/fixbuddy.sh b/fixbuddy.sh
index 972de6c..a0d619d 100755
--- a/fixbuddy.sh
+++ b/fixbuddy.sh
@@ -19,20 +19,32 @@
 #
 # Options:
 #   --label <label>           Filter issues by label (repeatable)
+#   --issue <n>               Process only this issue number (repeatable). Fetched
+#                             directly; dedup filters and --label/--severity still apply.
 #   --severity <level>        Only issues with label severity:<level>
 #   --max <n>                 Stop after N issues processed
 #   --fix-agent <agent>       claude | codex | opencode | gemini (default: claude)
 #   --review-agent <agent>    claude | codex | opencode | gemini (default: codex — cross-agent)
 #                             Note: gemini runs read-only (--approval-mode plan) when
 #                             used as verify/review agent. Warned about as fix-agent.
+#   --check-cmd <cmd>         Deterministic test gate (repeatable). Run in the project dir
+#                             after the fix commit and before review; a non-zero exit is
+#                             treated like a review rejection (retried, then fix:rejected).
+#                             Commands are OPERATOR-TRUSTED and run via the shell.
 #   --max-retries <n>         Fix retries after review rejection (default: 1 → 2 total attempts)
 #   --agent-timeout <secs>    Wall-clock timeout per agent invocation (default: 1200 = 20min)
 #   --crash-abort <n>         Abort batch after N consecutive agent crashes (default: 3)
 #   --base <branch>           Base branch (default: auto-detect main/master)
+#   --auto-merge              Enable auto-merge (default; overrides config auto_merge=false)
 #   --no-auto-merge           Create PR but don't enable auto-merge
 #   --skip-label <lbl>        Skip issues with this label (default: fix:applied)
-#   --dry-run                 List targets, don't execute
+#   --dry-run                 List targets only — fully read-only (no labels, no edits)
 #   --yes, -y                 Skip confirmation
+#
+# Config files (key = value, parsed without eval; CLI flags override):
+#   ~/.fixbuddy/config (global), then ./.fixbuddy.conf (cwd). label and check_cmd are
+#   ADDITIVE: config and CLI entries combine (labels become an AND filter), and a
+#   config-provided label/check cannot be removed from the CLI.
 
 set -uo pipefail
 VERSION="0.4.0"
@@ -41,6 +53,8 @@ VERSION="0.4.0"
 REPO=""
 PROJECT=""
 LABELS=()
+ISSUES=()
+CHECK_CMDS=()
 SEVERITY=""
 MAX=""
 FIX_AGENT="claude"
@@ -57,6 +71,16 @@ AUTO_YES=false
 # Runtime crash counter (bumped by handle_agent_crash, reset on successful agent output)
 CONSECUTIVE_CRASHES=0
 
+# Interrupt-handler state — tracks the issue/branch currently in flight so the Ctrl-C trap
+# can clean up. CURRENT_PUSHED is informational (the remote branch/PR are durable and get
+# reconciled next run). Agent/watchdog PIDs live in a FILE, not variables: run_agent runs
+# inside a command-substitution subshell whose variable assignments never reach the parent
+# shell where the trap runs, but a file written by the subshell is visible to the parent.
+CURRENT_ISSUE=""
+CURRENT_BRANCH=""
+CURRENT_PUSHED=false
+AGENT_PIDFILE=""
+
 # -------- Logging --------
 ts()    { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
 info()  { printf "\033[36m[INFO ]\033[0m %s %s\n" "$(ts)" "$*" >&2; }
@@ -65,25 +89,89 @@ err()   { printf "\033[31m[ERROR]\033[0m %s %s\n" "$(ts)" "$*" >&2; }
 ok()    { printf "\033[32m[ OK  ]\033[0m %s %s\n" "$(ts)" "$*" >&2; }
 hdr()   { printf "\033[35m\n====== %s ======\033[0m\n" "$*" >&2; }
 
+# Trim leading/trailing whitespace (bash 3.2-safe, no external process).
+_trim() {
+  local s="$1"
+  s="${s#"${s%%[![:space:]]*}"}"
+  s="${s%"${s##*[![:space:]]}"}"
+  printf '%s' "$s"
+}
+
+# -------- Config files --------
+# Parse a `key = value` config file into the option globals WITHOUT eval/source, so a
+# config can never execute code — values are only ever assigned as plain strings. Loaded
+# before arg parsing, so CLI flags override; global is loaded before project so project
+# wins. Repeatable keys (label, check_cmd) are additive. Unknown/malformed lines warn.
+load_config() {
+  local file="$1"
+  [ -f "$file" ] && [ -r "$file" ] || return 0
+  local line key value
+  while IFS= read -r line || [ -n "$line" ]; do
+    line="${line%$'\r'}"                 # tolerate CRLF (Windows-authored configs)
+    line="$(_trim "$line")"
+    [ -z "$line" ] && continue
+    case "$line" in \#*) continue ;; esac
+    case "$line" in
+      *=*) ;;
+      *) warn "malformed config line in $file (no '='): $line"; continue ;;
+    esac
+    key="$(_trim "${line%%=*}")"
+    value="$(_trim "${line#*=}")"
+    # Strip one optional layer of matching surrounding quotes.
+    case "$value" in
+      '"'*'"') value="${value#\"}"; value="${value%\"}" ;;
+      "'"*"'") value="${value#\'}"; value="${value%\'}" ;;
+    esac
+    case "$key" in
+      repo)          REPO="$value" ;;
+      project)       PROJECT="$value" ;;
+      fix_agent)     FIX_AGENT="$value" ;;
+      review_agent)  REVIEW_AGENT="$value" ;;
+      max)           MAX="$value" ;;
+      max_retries)   MAX_RETRIES="$value" ;;
+      agent_timeout) AGENT_TIMEOUT="$value" ;;
+      crash_abort)   CRASH_ABORT_THRESHOLD="$value" ;;
+      base)          BASE_BRANCH="$value" ;;
+      severity)      SEVERITY="$value" ;;
+      skip_label)    SKIP_LABEL="$value" ;;
+      auto_merge)
+        case "$value" in
+          true)  AUTO_MERGE=true ;;
+          false) AUTO_MERGE=false ;;
+          *) warn "config: auto_merge must be true|false (got '$value') in $file — ignored" ;;
+        esac ;;
+      label)     LABELS+=("$value") ;;
+      check_cmd) CHECK_CMDS+=("$value") ;;
+      *) warn "unknown config key '$key' in $file (ignored)" ;;
+    esac
+  done < "$file"
+}
+
+load_config "$HOME/.fixbuddy/config"
+load_config "./.fixbuddy.conf"
+
 # -------- Arg parsing --------
 while [ $# -gt 0 ]; do
   case "$1" in
     --repo) REPO="$2"; shift 2 ;;
     --project) PROJECT="$2"; shift 2 ;;
     --label) LABELS+=("$2"); shift 2 ;;
+    --issue) ISSUES+=("$2"); shift 2 ;;
     --severity) SEVERITY="$2"; shift 2 ;;
     --max) MAX="$2"; shift 2 ;;
     --fix-agent) FIX_AGENT="$2"; shift 2 ;;
     --review-agent) REVIEW_AGENT="$2"; shift 2 ;;
+    --check-cmd) CHECK_CMDS+=("$2"); shift 2 ;;
     --max-retries) MAX_RETRIES="$2"; shift 2 ;;
     --agent-timeout) AGENT_TIMEOUT="$2"; shift 2 ;;
     --crash-abort) CRASH_ABORT_THRESHOLD="$2"; shift 2 ;;
     --base) BASE_BRANCH="$2"; shift 2 ;;
+    --auto-merge) AUTO_MERGE=true; shift ;;
     --no-auto-merge) AUTO_MERGE=false; shift ;;
     --skip-label) SKIP_LABEL="$2"; shift 2 ;;
     --dry-run) DRY_RUN=true; shift ;;
     -y|--yes) AUTO_YES=true; shift ;;
-    -h|--help) sed -n '2,36p' "$0"; exit 0 ;;
+    -h|--help) sed -n '2,47p' "$0"; exit 0 ;;
     --version) echo "fixbuddy $VERSION"; exit 0 ;;
     *) err "Unknown arg: $1"; exit 2 ;;
   esac
@@ -146,6 +234,12 @@ if [ -n "$MAX" ]; then
     0) err "--max must be greater than 0"; exit 2 ;;
   esac
 fi
+for i in "${ISSUES[@]+"${ISSUES[@]}"}"; do
+  case "$i" in
+    ''|*[!0-9]*) err "--issue must be a positive integer (got: '$i')"; exit 2 ;;
+    0) err "--issue must be greater than 0"; exit 2 ;;
+  esac
+done
 
 # -------- Auto-detect base branch --------
 if [ -z "$BASE_BRANCH" ]; then
@@ -163,15 +257,24 @@ info "Base branch: $BASE_BRANCH"
 # to succeed — the fix agent would then see user WIP mixed in with its own work.
 # Require a clean tree up-front; user recovers stashed content via `git stash pop` when
 # the run is done.
-dirty_status=$(cd "$PROJECT" && git status --porcelain)
-if [ -n "$dirty_status" ]; then
-  err "working tree at $PROJECT is not clean:"
-  printf '%s\n' "$dirty_status" | sed 's/^/    /' >&2
-  err "Commit, stash, or clean your changes before running fixbuddy (it creates commits"
-  err "on per-issue branches and cannot safely share the worktree with local WIP)."
-  exit 2
+# Skipped under --dry-run: a preview never touches the worktree, so it must not refuse
+# just because the tree has local WIP.
+if ! $DRY_RUN; then
+  dirty_status=$(cd "$PROJECT" && git status --porcelain)
+  if [ -n "$dirty_status" ]; then
+    err "working tree at $PROJECT is not clean:"
+    printf '%s\n' "$dirty_status" | sed 's/^/    /' >&2
+    err "Commit, stash, or clean your changes before running fixbuddy (it creates commits"
+    err "on per-issue branches and cannot safely share the worktree with local WIP)."
+    exit 2
+  fi
 fi
 
+# Label creation and the fix:pr-open unstick scan both MUTATE the repo, so they are
+# skipped under --dry-run to keep a preview fully read-only. The issue fetch further
+# below is read-only and runs unconditionally.
+if ! $DRY_RUN; then
+
 # -------- Ensure control labels exist --------
 for l_info in "fix:applied|0E8A16|fixbuddy merged a fix" \
               "fix:pr-open|1D76DB|fixbuddy opened a PR that is not merged yet" \
@@ -219,24 +322,55 @@ while IFS= read -r stuck_issue; do
   fi
 done < <(echo "$stuck_list" | jq -c '.[]')
 [ "$unstuck" -gt 0 ] && info "Unstuck $unstuck issue(s) whose fix:pr-open PRs are no longer open"
+fi  # end: skip mutating setup under --dry-run
 
 # -------- Fetch issues --------
-search_args=(--repo "$REPO" --state open --json "number,title,labels,url,body" --limit 200)
-for l in "${LABELS[@]+"${LABELS[@]}"}"; do search_args+=(--label "$l"); done
-[ -n "$SEVERITY" ] && search_args+=(--label "severity:$SEVERITY")
-
-info "Fetching issues from $REPO..."
-if ! issues_json=$(gh issue list "${search_args[@]}" 2>&1); then
-  err "gh issue list failed: $issues_json"
-  exit 1
+# Required-label set (from --label plus --severity), enforced in the jq filter below for
+# BOTH fetch modes so --label/--severity compose with --issue as additional AND constraints.
+req_labels=()
+for l in "${LABELS[@]+"${LABELS[@]}"}"; do req_labels+=("$l"); done
+[ -n "$SEVERITY" ] && req_labels+=("severity:$SEVERITY")
+req_json='[]'
+if [ "${#req_labels[@]}" -gt 0 ]; then
+  req_json=$(printf '%s\n' "${req_labels[@]}" | jq -R . | jq -s .)
+fi
+
+if [ "${#ISSUES[@]}" -gt 0 ]; then
+  # Targeted mode: fetch each requested issue directly so a number outside the 200-item
+  # list page is never silently missed. Missing/closed issues warn and are dropped.
+  info "Fetching ${#ISSUES[@]} requested issue(s) from $REPO..."
+  issues_json='[]'
+  for inum in "${ISSUES[@]}"; do
+    iv_rc=0
+    iv=$(gh issue view "$inum" --repo "$REPO" \
+      --json number,title,labels,url,state,body 2>/dev/null) || iv_rc=$?
+    if [ "$iv_rc" -ne 0 ] || [ -z "$iv" ]; then
+      warn "issue #$inum not found in $REPO (or not accessible) — skipping"
+      continue
+    fi
+    if [ "$(jq -r '.state // empty' <<<"$iv")" != "OPEN" ]; then
+      warn "issue #$inum is not open — skipping"
+      continue
+    fi
+    issues_json=$(jq -c --argjson cur "$iv" '. + [$cur]' <<<"$issues_json")
+  done
+else
+  search_args=(--repo "$REPO" --state open --json "number,title,labels,url,body" --limit 200)
+  for l in "${LABELS[@]+"${LABELS[@]}"}"; do search_args+=(--label "$l"); done
+  [ -n "$SEVERITY" ] && search_args+=(--label "severity:$SEVERITY")
+  info "Fetching issues from $REPO..."
+  if ! issues_json=$(gh issue list "${search_args[@]}" 2>&1); then
+    err "gh issue list failed: $issues_json"
+    exit 1
+  fi
 fi
 total_issues=$(echo "$issues_json" | jq 'length')
 case "$total_issues" in
-  ''|*[!0-9]*) err "gh issue list returned unexpected data (total_issues='$total_issues')"; exit 1 ;;
+  ''|*[!0-9]*) err "fetch returned unexpected data (total_issues='$total_issues')"; exit 1 ;;
 esac
 
 # Filter out completed, pending-PR, rejected, false-positive, and umbrella/meta issues.
-filtered=$(echo "$issues_json" | jq --arg skip "$SKIP_LABEL" '
+filtered=$(echo "$issues_json" | jq --arg skip "$SKIP_LABEL" --argjson req "$req_json" '
   [.[] | select(
     ((.labels|map(.name)) | index($skip) | not)
     and ((.labels|map(.name)) | index("fix:pr-open") | not)
@@ -245,6 +379,7 @@ filtered=$(echo "$issues_json" | jq --arg skip "$SKIP_LABEL" '
     and ((.labels|map(.name)) | index("fix:false-positive") | not)
     and ((.labels|map(.name)) | index("fix:rejected") | not)
     and ((.labels|map(.name)) | index("fix:needs-human") | not)
+    and (([.labels[].name]) as $have | ($req | map(. as $r | ($have | index($r)) != null) | all))
   )]')
 target_count=$(echo "$filtered" | jq 'length')
 case "$target_count" in
@@ -252,12 +387,42 @@ case "$target_count" in
 esac
 
 info "Found $total_issues matching; $target_count actionable after filters"
+
+# In targeted mode, warn about requested issues that were fetched (open) but filtered out
+# (already completed, or excluded by a dedup/label filter), so a skip is never silent.
+# Issues that were missing/closed were already warned during the direct fetch above.
+if [ "${#ISSUES[@]}" -gt 0 ]; then
+  fetched_nums=" $(echo "$issues_json" | jq -r '.[].number' | tr '\n' ' ')"
+  filtered_nums=" $(echo "$filtered" | jq -r '.[].number' | tr '\n' ' ')"
+  for inum in "${ISSUES[@]}"; do
+    case "$filtered_nums" in *" $inum "*) continue ;; esac
+    case "$fetched_nums" in
+      *" $inum "*) warn "issue #$inum is open but not actionable (already completed or excluded by a label/dedup filter) — skipping" ;;
+    esac
+  done
+fi
+
 [ "$target_count" = "0" ] && { warn "No issues to process."; exit 0; }
 
 if $DRY_RUN; then
   echo ""
-  echo "=== Would process (first 20): ==="
-  echo "$filtered" | jq -r '.[] | "#\(.number) [\(.labels|map(.name)|join(","))] \(.title)"' | head -20
+  echo "=== Dry run — would process $target_count issue(s)${MAX:+ (stopping after --max $MAX)} ==="
+  echo "  Fix agent:    $FIX_AGENT"
+  echo "  Review agent: $REVIEW_AGENT"
+  echo "  Project:      $PROJECT"
+  echo "  Base branch:  $BASE_BRANCH"
+  echo "  Auto-merge:   $AUTO_MERGE"
+  if [ "${#CHECK_CMDS[@]}" -gt 0 ]; then
+    echo "  Checks:"
+    for c in "${CHECK_CMDS[@]}"; do echo "    - $c"; done
+  fi
+  echo ""
+  if [ -n "$MAX" ]; then
+    echo "$filtered" | jq -r '.[] | "#\(.number) [\(.labels|map(.name)|join(","))] \(.title)"' | head -n "$MAX"
+    [ "$target_count" -gt "$MAX" ] && echo "  … and $((target_count - MAX)) more not shown (--max $MAX)"
+  else
+    echo "$filtered" | jq -r '.[] | "#\(.number) [\(.labels|map(.name)|join(","))] \(.title)"'
+  fi
   exit 0
 fi
 
@@ -318,6 +483,8 @@ run_agent() {
       ;;
   esac
   local agent_pid=$!
+  # Record the PID in the shared file so the parent's interrupt trap can reach this agent.
+  [ -n "$AGENT_PIDFILE" ] && printf '%s\n' "$agent_pid" > "$AGENT_PIDFILE"
 
   # Watchdog — polls every 10s, kills process group on timeout
   (
@@ -339,6 +506,7 @@ run_agent() {
     kill -KILL "$agent_pid" 2>/dev/null
   ) >/dev/null 2>&1 &
   local watch_pid=$!
+  [ -n "$AGENT_PIDFILE" ] && printf '%s %s\n' "$agent_pid" "$watch_pid" > "$AGENT_PIDFILE"
 
   wait "$agent_pid" 2>/dev/null
   local rc=$?
@@ -361,6 +529,7 @@ run_agent() {
 
   kill "$watch_pid" 2>/dev/null
   wait "$watch_pid" 2>/dev/null
+  [ -n "$AGENT_PIDFILE" ] && : > "$AGENT_PIDFILE"
 
   local out
   out=$(cat "$outfile")
@@ -388,6 +557,74 @@ cleanup_branch() {
   ) || true
 }
 
+# Run the operator-supplied --check-cmd gate(s) in the project dir. Commands are trusted
+# (CLI/config level, not issue content), so the shell runs them via eval. Returns 0 when
+# all pass; on the first failure returns non-zero and prints a "<cmd>\n<capped output>"
+# block on stdout. The full command output is streamed to a temp FILE (never held whole in
+# a shell variable); only the last 200 lines AND at most 16 KB are read back, so a huge or
+# long-lined test log can't bloat memory, the prompt, or the GitHub comment.
+run_checks() {
+  [ "${#CHECK_CMDS[@]}" -gt 0 ] || return 0
+  local cmd rc tmp capped
+  tmp=$(mktemp "${TMPDIR:-/tmp}/fixbuddy-check.XXXXXX") || return 1
+  for cmd in "${CHECK_CMDS[@]}"; do
+    ( cd "$PROJECT" && eval "$cmd" ) >"$tmp" 2>&1
+    rc=$?
+    if [ "$rc" -ne 0 ]; then
+      # Last 200 lines, then clamp to the trailing 16 KB — both caps applied to the file.
+      capped=$(tail -n 200 "$tmp" | tail -c 16384)
+      rm -f "$tmp"
+      printf 'Check failed (exit %s): %s\n\n%s\n' "$rc" "$cmd" "$capped"
+      return 1
+    fi
+  done
+  rm -f "$tmp"
+  return 0
+}
+
+# Interrupt handler — on Ctrl-C/SIGTERM, stop the in-flight agent and leave the LOCAL repo
+# in a clean state so the next run resumes. No label is set: an interrupted issue simply
+# stays in the queue. cleanup_branch is local-only (stash + checkout base + delete LOCAL
+# branch), so it is always safe — a pushed branch's remote side and any PR are untouched
+# and reconciled on the next run.
+on_interrupt() {
+  trap - INT TERM   # disarm first so a second Ctrl-C cannot re-enter cleanup
+  warn "interrupted — stopping current agent and cleaning up (no label set; issue will retry next run)"
+  # PIDs come from the shared file (run_agent's assignments happen in a subshell and never
+  # reach this parent shell). Kill children then the process for BOTH the agent and the
+  # watchdog. Best-effort: $! is the pipeline's last process, not a process-group handle.
+  local apid="" wpid=""
+  if [ -n "$AGENT_PIDFILE" ] && [ -s "$AGENT_PIDFILE" ]; then
+    read -r apid wpid < "$AGENT_PIDFILE" || true
+  fi
+  for p in "$apid" "$wpid"; do
+    [ -n "$p" ] || continue
+    pkill -P "$p" 2>/dev/null || true
+    kill "$p" 2>/dev/null || true
+  done
+  # We cannot `wait` on the agent (it is a child of a command-substitution subshell, not of
+  # this shell), so poll for its exit before touching git, to avoid racing a fix commit that
+  # is still in flight. Mirror the watchdog escalation: ~5s SIGTERM grace, then SIGKILL, then
+  # a short settle — so cleanup never runs while a wedged agent is still writing.
+  if [ -n "$apid" ]; then
+    local tries=0
+    while kill -0 "$apid" 2>/dev/null && [ "$tries" -lt 5 ]; do sleep 1; tries=$((tries+1)); done
+    if kill -0 "$apid" 2>/dev/null; then
+      warn "agent did not exit on SIGTERM after 5s — sending SIGKILL"
+      pkill -KILL -P "$apid" 2>/dev/null || true
+      kill -KILL "$apid" 2>/dev/null || true
+      sleep 1   # guaranteed settle after SIGKILL before any git op, regardless of reap speed
+      tries=0
+      while kill -0 "$apid" 2>/dev/null && [ "$tries" -lt 5 ]; do sleep 1; tries=$((tries+1)); done
+    fi
+  fi
+  if [ -n "$CURRENT_BRANCH" ]; then
+    $CURRENT_PUSHED && warn "branch was already pushed; cleaning up locally only (remote branch/PR are reconciled next run)"
+    cleanup_branch "$CURRENT_ISSUE" "$CURRENT_BRANCH" "interrupted"
+  fi
+  exit 130
+}
+
 # Called when run_agent returned a crash rc. Labels the issue fix:blocked (auto-requeues
 # on next run), adds a comment explaining the failure class, cleans up the fix branch if
 # provided, and bumps CONSECUTIVE_CRASHES so the main loop can abort after N in a row.
@@ -635,6 +872,13 @@ process_issue() {
   local issue_log="$log_root/issue-$num.log"
   : > "$issue_log"
 
+  # Interrupt-handler state for this issue. CURRENT_BRANCH is set only once the branch
+  # exists; CURRENT_PUSHED flips after a successful push. The main loop clears all three
+  # after process_issue returns, so every return path is covered without per-path resets.
+  CURRENT_ISSUE="$num"
+  CURRENT_BRANCH=""
+  CURRENT_PUSHED=false
+
   hdr "Issue #$num: $title"
 
   # ---- Stage 1: VERIFY ----
@@ -706,6 +950,7 @@ The \`fix:needs-human\` label has been applied. This issue will not be retried a
       blocked=$((blocked+1))
       return 0
     fi
+    CURRENT_BRANCH="$branch"   # branch now exists — interrupt trap may clean it up
 
     info "[#$num] FIX attempt $attempt/$((MAX_RETRIES+1))"
     out=$(run_agent "$FIX_AGENT" "$(fix_prompt "$num" "$title" "$body" "$feedback")" "$issue_log" fix)
@@ -748,6 +993,28 @@ The \`fix:needs-human\` label has been applied. This issue requires human attent
       return 0
     fi
 
+    # ---- CHECK GATE (deterministic, before review) ----
+    # Operator-supplied --check-cmd(s) run here so a failing build/test never reaches the
+    # reviewer or a PR. A failure sets $feedback and flags skip_review, then falls through to
+    # the SHARED reject/retry handling below — the exact same path a review rejection uses
+    # (same retry budget via the loop's attempt counter, same fix:rejected label/comment,
+    # same cleanup_branch).
+    local skip_review=false
+    if [ "${#CHECK_CMDS[@]}" -gt 0 ]; then
+      info "[#$num] CHECK (${#CHECK_CMDS[@]} command(s))"
+      local check_out
+      if ! check_out=$(run_checks); then
+        warn "[#$num] checks failed — treating as rejection"
+        feedback="Project checks failed (these run before review). Fix them so the checks pass:
+
+$check_out"
+        skip_review=true
+      else
+        ok "[#$num] checks passed"
+      fi
+    fi
+
+    if ! $skip_review; then
     # ---- REVIEW ----
     info "[#$num] REVIEW attempt $attempt/$((MAX_RETRIES+1))"
     local diff
@@ -818,14 +1085,17 @@ The \`fix:needs-human\` label has been applied. This issue will not be retried a
     if [ -z "$feedback" ]; then
       feedback="DONE-REJECTED: (reviewer produced no DONE-APPROVED or DONE-REJECTED marker — inspect $issue_log)"
     fi
+    fi  # end: skip review when checks already failed this attempt
+
+    # ---- SHARED reject/retry handling (review rejection OR failed check gate) ----
     warn "[#$num] $feedback"
 
     if [ "$attempt" -gt "$MAX_RETRIES" ]; then
       err "[#$num] retry budget exhausted, giving up"
       gh issue edit "$num" --repo "$REPO" --add-label "fix:rejected" >/dev/null 2>&1 || true
-      gh issue comment "$num" --repo "$REPO" --body "**fixbuddy reviewer rejected all $((MAX_RETRIES+1)) attempts.**
+      gh issue comment "$num" --repo "$REPO" --body "**fixbuddy: no acceptable fix after $((MAX_RETRIES+1)) attempt(s)** (review rejection or failed checks).
 
-Last reviewer feedback:
+Last feedback:
 $feedback
 
 Full logs: \`$issue_log\` on the machine where fixbuddy ran." >/dev/null 2>&1 || true
@@ -834,7 +1104,7 @@ Full logs: \`$issue_log\` on the machine where fixbuddy ran." >/dev/null 2>&1 ||
       return 0
     fi
 
-    info "[#$num] retrying with reviewer feedback"
+    info "[#$num] retrying with feedback"
     # Loop continues: branch will be reset at top of loop
   done
 
@@ -850,6 +1120,7 @@ Full logs: \`$issue_log\` on the machine where fixbuddy ran." >/dev/null 2>&1 ||
     blocked=$((blocked+1))
     return 0
   fi
+  CURRENT_PUSHED=true   # remote branch now exists — interrupt trap must not delete it
 
   local commit_title
   commit_title=$(cd "$PROJECT" && git log -1 --pretty=%s "$branch")
@@ -926,6 +1197,11 @@ The PR is awaiting human review or merge. The issue is labeled \`fix:pr-open\` s
 }
 
 # -------- Main loop --------
+# Shared file for in-flight agent/watchdog PIDs (see AGENT_PIDFILE note above), then arm the
+# interrupt handler now that all helpers (cleanup_branch, run_agent) are defined.
+AGENT_PIDFILE=$(mktemp "${TMPDIR:-/tmp}/fixbuddy-pids.XXXXXX" 2>/dev/null || true)
+trap on_interrupt INT TERM
+
 while IFS= read -r issue; do
   num=$(echo "$issue" | jq -r '.number')
   title=$(echo "$issue" | jq -r '.title')
@@ -940,6 +1216,9 @@ while IFS= read -r issue; do
 
   process_issue "$num" "$title" "$body"
   processed=$((processed+1))
+  # Issue finished — clear interrupt-handler state so a later Ctrl-C (between issues)
+  # doesn't act on a stale branch reference.
+  CURRENT_ISSUE=""; CURRENT_BRANCH=""; CURRENT_PUSHED=false
 
   if [ "$CONSECUTIVE_CRASHES" -ge "$CRASH_ABORT_THRESHOLD" ]; then
     err "$CONSECUTIVE_CRASHES consecutive agent crashes — aborting batch to avoid fake-rejects."
@@ -951,6 +1230,10 @@ while IFS= read -r issue; do
   fi
 done < <(echo "$filtered" | jq -c '.[]')
 
+# Run finished normally — disarm the interrupt trap and drop the PID file.
+trap - INT TERM
+[ -n "$AGENT_PIDFILE" ] && rm -f "$AGENT_PIDFILE"
+
 # -------- Summary --------
 hdr "Summary"
 info "Processed:        $processed"