dev-loops 0.6.0 → 0.7.1

package/.claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-loops",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Agent-harness-agnostic dev-loop: agents, skills, and hooks for GitHub/Copilot-driven development loops.",
   "author": {
     "name": "Manuel Fittko",

package/.claude/agents/dev-loop.md

@@ -19,10 +19,11 @@ The envelope is the primary handoff artifact — it is derived from resolver out
 - `nextAction` — the bounded task to execute
 - `stopRules` — stop boundaries that must not be crossed without authorization
 - `acceptance` — self-validation criteria for declaring completion
+- `sanctionedCommands` — the operation → wrapper command map (reads/edits/lifecycle), plus the forbidden and orchestrator-owned lists. Carried by DEFAULT on every build so you never re-derive which wrapper performs a GitHub/loop operation. Do NOT restate the map here — the single source of truth is `scripts/loop/sanctioned-commands.mjs`, surfaced verbatim in the envelope.
 
 **Construction sequence:**
 
-1. Run the deterministic startup resolver to produce the authoritative state bundle: `npx dev-loops@0.6.0 loop startup --issue <n>` for issues, or `npx dev-loops@0.6.0 loop startup --pr <n>` for PRs.
+1. Run the deterministic startup resolver to produce the authoritative state bundle: `npx dev-loops@0.7.1 loop startup --issue <n>` for issues, or `npx dev-loops@0.7.1 loop startup --pr <n>` for PRs.
 2. Pass the resolver output, resolved settings (merged from `.devloops` and `.pi/dev-loop/defaults.yaml`), and current gate state to `buildDevLoopHandoffEnvelope()`.
 3. **Validate the envelope** with `validateHandoffEnvelope()` before consuming any field. If validation returns `ok: false`, reject the handoff with the structured error — do not load requiredReads, do not execute nextAction, do not delegate.
 4. Read the envelope as the first artifact.

package/.claude/agents/review.md

@@ -30,7 +30,8 @@ This agent has two modes. The default mode is the full-PR review described in th
 
 You are in scoped angle-review mode when the invocation supplies a single review `<angle>` plus a gate-context artifact path (`tmp/gate-context/<repo-slug>/pr-<N>/<gate>-<headSha>.json`, written by `scripts/github/write-gate-context.mjs`). Review like an external code reviewer hunting real bugs, not a process auditor: your job is to find concrete defects in the changed code and its call paths, not to remark that "there is no test" or that a doc section is thin. In that mode:
 
-- **Fresh-context guard (mandatory):** run `node scripts/github/verify-fresh-review-context.mjs --scope <angle>` at startup. If it reports `fresh: false` (exit 1) or any error, refuse to proceed and report contamination — do not review on inherited context. "Fresh" here means your context is the **neutral builder artifact + your angle**, and explicitly NOT the main agent's conversation/state or a prior reviewer session's state. The injected neutral bundle is the INTENDED seed (allowed); main-agent or cross-session state bleed still fails closed.
+- **No worktree isolation (mandatory):** you review in the PR's actual worktree/head — the same checkout the gate-context preamble ran in — never a fresh isolated worktree. You are read-only and never mutate files, so isolation buys nothing; a fresh worktree would also be checked out from `main` (not the PR head) and would lack the gitignored, worktree-local gate-context bundle below, so you'd silently review the wrong stale tree (#1135).
+- **Fresh-context guard (mandatory):** run `node scripts/github/verify-fresh-review-context.mjs --scope <angle> --context-path <gate-context-artifact-path>` at startup. If it reports `fresh: false` (exit 1) or any error — including a missing gate-context artifact (`gateContextPresent: false`), which is the fail-closed signal that you're not in the right worktree/head — refuse to proceed and report the failure; do not review on inherited context or without seeded context. "Fresh" here means your context is the **neutral builder artifact + your angle**, and explicitly NOT the main agent's conversation/state or a prior reviewer session's state. The injected neutral bundle is the INTENDED seed (allowed); main-agent or cross-session state bleed still fails closed.
 - **Use the PROVIDED neutral bundle as your base; do NOT re-derive it from scratch:** the gate-context artifact carries the diff (`scope.diffPath`) and a deterministic, neutral adjacent-code bundle in `adjacentCode` (each changed file plus its 1-hop import in/out-edges, with a `stripped`/`truncated`/`missing` manifest). Start from this bundle — it is the build-once, work-deduped seed shared verbatim across all reviewers. Only widen (load more files) per-angle when the bundle genuinely lacks something your angle needs; do not re-build the whole diff/adjacent-code graph yourself.
 - **Single-angle scope:** review ONLY the supplied angle's concern. Read the gate-context artifact for the resolved angle set, change scope (branch, head SHA, touched files), acceptance-criteria pointer, and validation posture. Do not review other angles; the fan-in pass consolidates across angles.
 - **Read the FULL diff, not just hunks:** the gate-context artifact records `scope.diffPath` (a repo-relative path to the complete captured diff) and `scope.changedFiles` (full repo-relative paths). Read the entire diff from `scope.diffPath`; if it is `null` or missing, reconstruct it yourself with `git diff` against the change's base (e.g. `git diff origin/main...HEAD` or the branch/head SHA in `scope`). Do not review off a partial or summarized hunk list — you must see every changed line for your angle.

package/.claude/commands/{auto.md → loop-auto.md}

@@ -2,6 +2,6 @@
 description: "Run an autonomous dev loop on a GitHub issue until the human approval checkpoint."
 argument-hint: "<issue>"
 ---
-<!-- GENERATED from commands/auto.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+<!-- GENERATED from commands/loop-auto.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
 
 Run the `dev-loop` skill with the public intent `auto dev loop on issue $ARGUMENTS`. Resolve authoritative state first, then continue autonomously through the routed loop until a stop condition or the human approval checkpoint. Do not pick an internal strategy name yourself.

package/.claude/commands/loop-continue.md

@@ -0,0 +1,15 @@
+---
+description: "Continue the dev loop — the current in-progress board item, or a given issue/PR."
+argument-hint: "[issue|pr]"
+---
+<!-- GENERATED from commands/loop-continue.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+
+Continue a dev loop. Two forms, both handed to the `dev-loop` skill — do NOT pick an internal strategy yourself.
+
+- With an argument (`$ARGUMENTS` is an issue or PR — `123`, `#123`, or a GitHub URL): run the `dev-loop` skill with the public intent `continue dev loop on $ARGUMENTS`. Resolve that artifact's authoritative state first, then route; ignore board position.
+
+- Bare (no `$ARGUMENTS`): resolve the single continue target from the board. Resolve the board's repo and project the same way the queue commands do, then run `node scripts/projects/resolve-active-board-item.mjs --repo <owner/name> --project <number>`. It continues the single **In Progress** item; if there is none, it picks the **HEAD of Next Up by position**. It fails closed (idle) when Next Up is empty, and still fails closed on multiple In-Progress items. It never pulls from Backlog.
+  - It returns `{ ok: true, target: { kind, number }, source }` (`source` is `"in-progress"` or `"next-up"`) → run the `dev-loop` skill with the public intent `continue dev loop on #<number>` (the resolved `target.number`), so the intent carries the concrete target instead of re-resolving board state.
+  - It returns `{ ok: false, reason }` when there are multiple in-progress items, or when there is nothing in progress **and** Next Up is empty → FAIL CLOSED: print the reason verbatim and instruct the user to run `/loop-continue #N` explicitly (or prioritize a Backlog item into Next Up). Do NOT guess, and never pick from Backlog.
+
+Resolve authoritative state before routing. All paths terminate in the dev-loop skill's `loop startup` → build-envelope → route, stopping at the human-approval checkpoint as usual. No new routing logic here.

package/.claude/commands/loop-enqueue.md

@@ -0,0 +1,22 @@
+---
+description: "Add an issue/PR to the auto queue, or quick-capture a freeform idea as a grilled issue and queue it."
+argument-hint: "<issue-or-pr-number | freeform text>"
+---
+<!-- GENERATED from commands/loop-enqueue.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+
+Add work to the dev-loop queue. Parse `$ARGUMENTS` before acting. The project is auto-resolved from `.devloops` — never pass `--project` and never invent a project number. `<owner/repo>` resolves from the git remote at invocation, same as the other loop commands.
+
+1. **Argument parsing (fail-closed):**
+   - If `$ARGUMENTS` is empty, print `Error: missing argument — provide an issue/PR number or freeform text.` and stop without mutating anything.
+   - If `$ARGUMENTS` is a single integer token, take the **numeric path**. Otherwise take the **freeform path**.
+
+2. **Numeric path (existing issue/PR):**
+   - Run `node scripts/projects/add-queue-item.mjs --repo <owner/repo> --item <n>`.
+   - The script is idempotent and returns `{ ok, item: { status, alreadyPresent } }`. Report the resulting Status column and whether it was already present, e.g. `#<n> is in "Backlog" (already on the board)` or `#<n> added to "Backlog"`.
+   - Exit `3` means the issue/PR was not found (`ITEM_NOT_FOUND` / `CONTENT_NOT_FOUND`): print `Error: issue/PR #<n> not found.` and stop. Do not retry with a guessed project.
+
+3. **Freeform path (quick-capture a new idea):** run these steps in order.
+   1. **Confirm first — no mutation before approval.** Print a one-line preview of the issue to be created (`About to create issue: "<concise title>"`) and STOP for approval. Do not create the issue, grill, or enqueue anything until the human approves.
+   2. **Create the issue.** After approval, create a minimal GitHub issue from the text. The repo has no dedicated create-issue wrapper under `scripts/github/`; the sanctioned create path in this codebase is `gh issue create --repo <owner/repo> --assignee @me --title "<concise title>" --body "<freeform text>"` (the same path used by `skills/docs/issue-intake-procedure.md` and permitted by `skills/docs/main-agent-contract.md`). Title = a concise summary of the text; body = the verbatim freeform text.
+   3. **Grill it.** Run `/loop-grill <n> --auto` (delegates to the `loop-grill` skill). The skill writes a `## Grill findings` section back into the issue body and flags any unresolved items there, so they are visible before pickup. Do not re-implement grilling.
+   4. **Enqueue.** Run `node scripts/projects/add-queue-item.mjs --repo <owner/repo> --item <n>` to add the grill-annotated issue to the board, then report its Status column as in the numeric path. The `strategy: local-first` default is set repo-wide in `.devloops` (`strategy.default: local-first`), so the new issue is already local-first — this repo has no per-issue local-first label or body tag to apply, and you must not invent one.

package/.claude/commands/loop-grill.md

@@ -0,0 +1,17 @@
+---
+description: "Run a structured Socratic Q&A grill session against an issue or plan file before the dev loop starts."
+argument-hint: "<issue-number> | <path/to/plan.md> [--auto]"
+---
+<!-- GENERATED from commands/loop-grill.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+
+Invoke the `loop-grill` skill with `$ARGUMENTS`. Parse the argument list before acting:
+
+1. **Argument parsing (fail-closed):**
+   - If `$ARGUMENTS` is empty, print `Error: missing argument — provide an issue number or a path to a plan file.` and stop without mutating anything.
+   - Split `$ARGUMENTS` into tokens. The first token is the target (`<issue-number>` or `<path/to/plan.md>`). Remaining tokens may include `--auto`. Any other flag produces `Error: unrecognized flag '<flag>' — only --auto is supported.` and stops.
+   - If the first token looks like an integer, treat it as a tracker-first issue number. Verify the issue exists via `gh issue view <n> --repo <owner/repo> --json number` (exit non-zero = not found); if not found, print `Error: issue #<n> not found.` and stop.
+   - If the first token is a path, resolve it relative to the repo root (or as absolute). If the file does not exist, print `Error: plan file not found: <path>` and stop.
+
+2. **Route to the `loop-grill` skill**, passing the resolved target and the `--auto` flag (if present). The skill owns all grilling logic: gap detection, interactive Q&A or auto-answer, write-back, and verdict emission.
+
+> **Note:** Interactive mode uses `AskUserQuestion` for bounded-choice gaps and plain text turns for open-ended gaps. `AskUserQuestion` is a Claude Code–native construct; use `--auto` as the portable fallback when running outside Claude Code.

package/.claude/commands/{info.md → loop-info.md}

@@ -2,6 +2,6 @@
 description: "Show the read-only dev-loop state summary for an issue or PR."
 argument-hint: "<issue|pr>"
 ---
-<!-- GENERATED from commands/info.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+<!-- GENERATED from commands/loop-info.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
 
-Resolve the read-only dev-loop state for `$ARGUMENTS` via the `loop info` shortcut — no full dev-loop run. If `$ARGUMENTS` is an issue number, run `npx dev-loops@0.6.0 loop info --issue $ARGUMENTS`; if it is a PR number, run `npx dev-loops@0.6.0 loop info --pr $ARGUMENTS`. Report the strategy, route, linked PR / branch, CI, and next action. Do not start implementation.
+Resolve the read-only dev-loop state for `$ARGUMENTS` via the `loop info` shortcut — no full dev-loop run. If `$ARGUMENTS` is an issue number, run `npx dev-loops@0.7.1 loop info --issue $ARGUMENTS`; if it is a PR number, run `npx dev-loops@0.7.1 loop info --pr $ARGUMENTS`. Report the strategy, route, linked PR / branch, CI, and next action. Do not start implementation.

package/.claude/commands/loop-queue-status.md

@@ -0,0 +1,24 @@
+---
+description: "Show the dev-loop queue board grouped by column."
+argument-hint: ""
+---
+<!-- GENERATED from commands/loop-queue-status.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+
+Show the dev-loop queue board. Takes no arguments; if `$ARGUMENTS` is non-empty, ignore it. `<owner/repo>` resolves from the git remote at invocation, same as the other loop commands, and the project is auto-resolved from `.devloops` — never pass `--project`.
+
+1. Run `node scripts/projects/list-queue-items.mjs --repo <owner/repo> --summary`. This is the sanctioned grouped-by-column path: it emits `{ ok, groups: { "<Status>": { count, items } } }` in board column order. Do not re-implement client-side grouping and do not pipe flat output through inline parsers.
+
+2. Render the result human-readably (not raw JSON). Walk `groups` in the order they are returned (board column order — Backlog, Next Up, In Progress, Done). For each column, print the column name with its count, then one line per item as `#<number> <title>`. Example:
+
+   ```
+   Backlog (2)
+     #1035 Add /loop-enqueue and /loop-queue-status commands
+     #1042 Fix article layout
+   Next Up (0)
+   In Progress (1)
+     #1041 Align nav/wrap/prose widths
+   Done (3)
+     ...
+   ```
+
+3. If every column is empty (all counts `0`), print `Queue is empty.` instead of a list.

package/.claude/commands/{start-spike.md → loop-start-spike.md}

@@ -2,7 +2,7 @@
 description: "Start a time-boxed dev-loop spike from a question (or a pre-authored findings file)."
 argument-hint: "<question> | --file <path>"
 ---
-<!-- GENERATED from commands/start-spike.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+<!-- GENERATED from commands/loop-start-spike.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
 
 Start a spike — a time-boxed exploration whose deliverable is a findings document. Two forms; both end in `loop startup --spike <path>` and hand the bundle to the `dev-loop` skill. Do NOT pick an internal strategy yourself, and do NOT invent new spike behavior — this wraps the shipped `--spike` intake (see `skills/docs/spike-mode-contract.md`).
 

package/.claude/commands/{start.md → loop-start.md}

@@ -2,6 +2,6 @@
 description: "Start a dev loop on a GitHub issue."
 argument-hint: "<issue>"
 ---
-<!-- GENERATED from commands/start.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+<!-- GENERATED from commands/loop-start.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
 
 Run the `dev-loop` skill with the public intent `start dev loop on issue $ARGUMENTS`. Resolve authoritative state first, then route through the deterministic internal strategy. Do not pick an internal strategy name yourself.

package/.claude/commands/{status.md → loop-status.md}

@@ -1,6 +1,6 @@
 ---
 description: "Report dev-loop readiness (gh auth, git repo, subagent availability)."
 ---
-<!-- GENERATED from commands/status.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+<!-- GENERATED from commands/loop-status.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
 
 Report dev-loop readiness for this environment. Check, in one pass: `gh` is installed (`command -v gh`), `gh` is authenticated (`gh auth status`), the working directory is inside a git repo (`git rev-parse --is-inside-work-tree`), and the `subagent`/`Agent` capability is available. Summarize which checks passed and the suggested next step. Read-only — do not start implementation.

package/.claude/hooks/_bash-command-classify.mjs

@@ -15,6 +15,53 @@ export const TARGET_REPO_SLUG = "mfittko/dev-loops";
 /** Flags known to take a value argument for `gh pr ready` (not boolean flags). */
 export const FLAGS_THAT_TAKE_VALUE = new Set(["-r", "--repo"]);
 
+/**
+ * Shell command separators that terminate one segment and begin the next.
+ * Newline (`\n`) and carriage return (`\r`) are full command terminators in bash
+ * (equivalent to `;`), and the Claude Code Bash tool accepts multi-line command
+ * strings — so a segment must break on them too, else `echo hi\ngh pr create` evades
+ * the gate. Used by all segment-splitting sites (DRY).
+ */
+const SHELL_SEGMENT_SEPARATOR = /\s*(?:&&|\|\||;|\||\n|\r)\s*/;
+
+/**
+ * Strip a single balanced surrounding quote pair (`'…'` or `"…"`) from a shell arg value.
+ * A repo flag value may reach us quoted (`--repo 'owner/name'`); the scope check compares against
+ * the bare slug, so quotes must be normalized or a quoted on-target repo evades the guard (#1074).
+ * ponytail: single balanced pair only — no full shell tokenization (mismatched/partial quotes stay).
+ * @param {string|null} value @returns {string|null}
+ */
+function stripSurroundingQuotes(value) {
+  if (value == null || value.length < 2) return value;
+  const first = value[0];
+  if ((first === "'" || first === '"') && value[value.length - 1] === first) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+/**
+ * Read an inline `GH_REPO=<value>` env-assignment prefix on a single command segment.
+ * `gh` resolves its target repo from the `GH_REPO` env var, and a segment may set it inline
+ * (`GH_REPO=owner/name gh issue create …`) — same targeting intent as `--repo owner/name`, so the
+ * scope check must treat it the same or an off-cwd redirect evades the guard (#1074). Only the
+ * FIRST leading env assignment matching `GH_REPO=` is read (env assignments precede the executable);
+ * the value is quote-normalized. Ambient `process.env.GH_REPO` is out of scope — this is a static
+ * command-string classifier, so only the inline assignment in the string is considered.
+ * @param {string} segment @returns {string|null}
+ */
+function extractGhRepoEnvAssignment(segment) {
+  if (!segment) return null;
+  for (const token of segment.trim().split(/\s+/)) {
+    const assign = token.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!assign) break; // first non-assignment token ends the env-assignment prefix
+    if (assign[1] === "GH_REPO") {
+      return trimToNull(stripSurroundingQuotes(assign[2]));
+    }
+  }
+  return null;
+}
+
 /** @param {string|null|undefined} value @returns {string|null} */
 export function trimToNull(value) {
   const trimmed = `${value ?? ""}`.trim();
@@ -51,7 +98,7 @@ export function normalizeGitHubRepoSlug(remoteUrl) {
   return null;
 }
 
-function isGhPrMergeCommand(segment) {
+function segmentIsGhPrMerge(segment) {
   if (!/^gh\s+pr\s+merge(?:\s|$)/i.test(segment)) {
     return false;
   }
@@ -82,36 +129,178 @@ export function isMergeCapableCommand(command) {
     return false;
   }
   return normalized
-    .split(/\s*(?:&&|\|\||;|\|)\s*/)
-    .some((segment) => isGhPrMergeCommand(segment) || isGitMergeCompletionCommand(segment));
+    .split(SHELL_SEGMENT_SEPARATOR)
+    .some((segment) => segmentIsGhPrMerge(segment) || isGitMergeCompletionCommand(segment));
 }
 
 /** @param {string} command @returns {string} */
 export function firstShellSegment(command) {
-  return command.trim().split(/\s*(?:&&|\|\||;|\|)\s*/)[0]?.trim() ?? "";
+  return command.trim().split(SHELL_SEGMENT_SEPARATOR)[0]?.trim() ?? "";
 }
 
-/** @param {string} command @returns {boolean} */
-export function isGhPrReadyCommand(command) {
-  const segment = firstShellSegment(command);
-  if (!segment || !/^gh\s+pr\s+ready(?:\s|$)/i.test(segment)) {
-    return false;
+/** Split a compound shell command into its individual segments. */
+function shellSegments(command) {
+  return command.trim().split(SHELL_SEGMENT_SEPARATOR).map((s) => s.trim()).filter(Boolean);
+}
+
+/**
+ * Leading prefix a `gh pr <verb>` segment may carry before the `gh` executable:
+ * a run of `NAME=value` env assignments, optional `command`/`env`/`exec` wrapper
+ * words, and an absolute/relative path on the gh binary (`/usr/bin/gh`).
+ *
+ * Note: this is a pragmatic normalizer, not a full shell tokenizer. Subshell
+ * `(gh pr create)`, `{ …; }` group, `-R=value` short-flag, and backslash-escaped
+ * `\gh` forms are deliberately out of scope.
+ */
+const GH_PR_VERB_PREFIX = "(?:[A-Za-z_][A-Za-z0-9_]*=\\S*\\s+)*(?:(?:command|env|exec)\\s+)*(?:\\S*/)?";
+
+/**
+ * Build the `gh <subcmd> <verb>` prefix matcher (subcmd = "pr" | "issue").
+ * Tolerates a leading env-assignment/wrapper/path prefix so `GH_TOKEN=x gh pr create`,
+ * `command gh issue create`, and `/usr/bin/gh pr create` are all matched. The same regex
+ * is reused to strip the matched prefix (`segment.replace(re, "")`), so remainder
+ * extraction stays consistent across all matcher/extractor call sites. The `gh` prefix
+ * requirement means node-wrapper commands (`node scripts/github/comment-issue.mjs …`) never
+ * match — their first token is `node`, not `gh`.
+ */
+function ghSubcmdVerbRegex(subcmd, verb) {
+  return new RegExp(`^${GH_PR_VERB_PREFIX}gh\\s+${subcmd}\\s+${verb}(?:\\s|$)`, "i");
+}
+
+/** Build the `gh pr <verb>` prefix matcher — delegates to the generic subcmd matcher (DRY). */
+function ghPrVerbRegex(verb) {
+  return ghSubcmdVerbRegex("pr", verb);
+}
+
+/**
+ * Return the first segment in the command that is a `gh <subcmd> <verb>` call (ignoring
+ * --help/-h), or null. Scans ALL segments so compound commands are caught.
+ */
+function findGhSubcmdVerbSegment(command, subcmd, verb) {
+  const re = ghSubcmdVerbRegex(subcmd, verb);
+  for (const segment of shellSegments(command)) {
+    if (!re.test(segment)) continue;
+    const remainder = segment.replace(re, "").trim();
+    if (!remainder) return segment;
+    const args = remainder.split(/\s+/).map((a) => a.toLowerCase());
+    if (!args.includes("--help") && !args.includes("-h")) return segment;
   }
-  const remainder = segment.replace(/^gh\s+pr\s+ready(?:\s|$)/i, "").trim();
-  if (!remainder) {
-    return true;
+  return null;
+}
+
+/**
+ * Extract the `--repo`/`-R` flag value from an already-isolated `gh <subcmd> <verb>` segment.
+ * @param {string} segment @param {string} subcmd @param {string} verb @returns {string|null}
+ */
+function extractRepoFlagFromSubcmdSegment(segment, subcmd, verb) {
+  const re = ghSubcmdVerbRegex(subcmd, verb);
+  if (!segment || !re.test(segment)) return null;
+  const remainder = segment.replace(re, "").trim();
+  if (!remainder) return null;
+  const tokens = remainder.split(/\s+/);
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    const lower = token.toLowerCase();
+    if (lower === "-r" || lower === "--repo") {
+      if (i + 1 < tokens.length && !tokens[i + 1].startsWith("-")) return stripSurroundingQuotes(tokens[i + 1]);
+    }
+    const repoEqMatch = token.match(/^(?:--repo|-R)=(.+)$/i);
+    if (repoEqMatch) return stripSurroundingQuotes(repoEqMatch[1]);
+  }
+  // No explicit --repo/-R flag: fall back to an inline GH_REPO= env assignment (flag wins,
+  // mirroring gh's own precedence). This closes the GH_REPO repo-targeting bypass (#1074).
+  return extractGhRepoEnvAssignment(segment);
+}
+
+/**
+ * Return one `{ segment, explicitRepo }` entry for EVERY `gh <subcmd> <verb>` segment (ignoring
+ * --help/-h). Mirrors `extractRepoFlagsFromGhPrCreateSegments`.
+ * @param {string} command @param {string} subcmd @param {string} verb
+ * @returns {{ segment: string, explicitRepo: string|null }[]}
+ */
+function extractRepoFlagsFromGhSubcmdVerbSegments(command, subcmd, verb) {
+  const re = ghSubcmdVerbRegex(subcmd, verb);
+  const out = [];
+  for (const segment of shellSegments(command)) {
+    if (!re.test(segment)) continue;
+    const remainder = segment.replace(re, "").trim();
+    if (remainder) {
+      const args = remainder.split(/\s+/).map((a) => a.toLowerCase());
+      if (args.includes("--help") || args.includes("-h")) continue;
+    }
+    out.push({ segment, explicitRepo: extractRepoFlagFromSubcmdSegment(segment, subcmd, verb) });
   }
+  return out;
+}
+
+/**
+ * The raw external-write verb forms that must be blocked when originating from a subagent:
+ * ad-hoc GitHub issue/PR creation and comments run directly via `gh` (not the sanctioned node
+ * wrappers). Each entry is `[subcmd, verb]`.
+ */
+const EXTERNAL_WRITE_VERB_FORMS = Object.freeze([
+  ["issue", "create"],
+  ["issue", "comment"],
+  ["pr", "comment"],
+]);
+
+/**
+ * Whether `command` contains a raw `gh issue create`, `gh issue comment`, or `gh pr comment`
+ * invocation in ANY shell segment (ignoring --help/-h). PreToolUse gate use only — the gate
+ * blocks these when they originate from a subagent context. Node-wrapper commands
+ * (`node scripts/github/comment-issue.mjs …`) never match (first token is `node`, not `gh`).
+ * @param {string} command @returns {boolean}
+ */
+export function commandContainsRawExternalWrite(command) {
+  return EXTERNAL_WRITE_VERB_FORMS.some(([subcmd, verb]) => findGhSubcmdVerbSegment(command, subcmd, verb) !== null);
+}
+
+/**
+ * Return `{ segment, explicitRepo }` for every raw external-write segment across all three verb
+ * forms (`gh issue create` / `gh issue comment` / `gh pr comment`). PreToolUse gate use only —
+ * lets the gate decide in-scope-ness per segment so a leading out-of-scope write can't shield a
+ * later in-scope one. `explicitRepo` is the segment's `--repo`/`-R` value or null.
+ * @param {string} command @returns {{ segment: string, explicitRepo: string|null }[]}
+ */
+export function extractRepoFlagsFromExternalWriteSegments(command) {
+  return EXTERNAL_WRITE_VERB_FORMS.flatMap(([subcmd, verb]) =>
+    extractRepoFlagsFromGhSubcmdVerbSegments(command, subcmd, verb),
+  );
+}
+
+/**
+ * Return the first segment in the command that is a `gh pr <verb>` call (ignoring --help/-h),
+ * or null. Scans ALL segments so compound commands (`echo ok && gh pr merge 1`) are caught.
+ */
+function findGhPrVerbSegment(command, verb) {
+  return findGhSubcmdVerbSegment(command, "pr", verb);
+}
+
+/**
+ * Generic `gh pr <verb>` detector — checks the FIRST shell segment only.
+ *
+ * Used by the Pi extension's post-execute handler (`onUserBash`) to record that `gh pr ready`
+ * actually ran. First-segment-only is correct for that use: `false && gh pr ready 42` short-
+ * circuits so ready never executes, and the extension should not record a spurious invocation.
+ *
+ * For the Claude Code PreToolUse gate (block before execution), use
+ * `commandContainsGhPrReady`/`commandContainsGhPrMerge` instead — those scan ALL segments.
+ */
+function isGhPrVerbCommand(command, verb) {
+  const re = ghPrVerbRegex(verb);
+  const segment = firstShellSegment(command);
+  if (!segment || !re.test(segment)) return false;
+  const remainder = segment.replace(re, "").trim();
+  if (!remainder) return true;
   const args = remainder.split(/\s+/).map((a) => a.toLowerCase());
   return !args.includes("--help") && !args.includes("-h");
 }
 
-/** @param {string} command @returns {number|null} */
-export function extractPrNumberFromGhPrReady(command) {
-  const segment = firstShellSegment(command);
-  if (!/^gh\s+pr\s+ready(?:\s|$)/i.test(segment)) {
-    return null;
-  }
-  const remainder = segment.replace(/^gh\s+pr\s+ready(?:\s|$)/i, "").trim();
+/** Extract PR number from a single already-isolated segment (shared by both first- and all-segment paths). */
+function extractPrNumberFromSegment(segment, verb) {
+  const re = ghPrVerbRegex(verb);
+  if (!segment || !re.test(segment)) return null;
+  const remainder = segment.replace(re, "").trim();
   if (!remainder) {
     return null;
   }
@@ -136,13 +325,11 @@ export function extractPrNumberFromGhPrReady(command) {
   return null;
 }
 
-/** @param {string} command @returns {string|null} */
-export function extractRepoFlagFromGhPrReady(command) {
-  const segment = firstShellSegment(command);
-  if (!/^gh\s+pr\s+ready(?:\s|$)/i.test(segment)) {
-    return null;
-  }
-  const remainder = segment.replace(/^gh\s+pr\s+ready(?:\s|$)/i, "").trim();
+/** Extract repo flag from a single already-isolated segment. */
+function extractRepoFlagFromSegment(segment, verb) {
+  const re = ghPrVerbRegex(verb);
+  if (!segment || !re.test(segment)) return null;
+  const remainder = segment.replace(re, "").trim();
   if (!remainder) {
     return null;
   }
@@ -152,13 +339,130 @@ export function extractRepoFlagFromGhPrReady(command) {
     const lower = token.toLowerCase();
     if (lower === "-r" || lower === "--repo") {
       if (i + 1 < tokens.length && !tokens[i + 1].startsWith("-")) {
-        return tokens[i + 1];
+        return stripSurroundingQuotes(tokens[i + 1]);
       }
     }
     const repoEqMatch = token.match(/^(?:--repo|-R)=(.+)$/i);
     if (repoEqMatch) {
-      return repoEqMatch[1];
+      return stripSurroundingQuotes(repoEqMatch[1]);
     }
   }
-  return null;
+  // No explicit --repo/-R flag: fall back to an inline GH_REPO= env assignment (flag wins,
+  // mirroring gh's own precedence). Applied here too so gh pr ready/merge/create scope checks get
+  // consistent GH_REPO handling — the root-cause fix, not just the external-write path (#1074).
+  return extractGhRepoEnvAssignment(segment);
+}
+
+/** First-segment extractor for `gh pr <verb>` PR number — Pi extension public API. */
+function extractPrNumberFromGhPrVerb(command, verb) {
+  return extractPrNumberFromSegment(firstShellSegment(command), verb);
+}
+
+/** First-segment extractor for `gh pr <verb>` --repo flag — Pi extension public API. */
+function extractRepoFlagFromGhPrVerb(command, verb) {
+  return extractRepoFlagFromSegment(firstShellSegment(command), verb);
+}
+
+/** @param {string} command @returns {boolean} */
+export function isGhPrReadyCommand(command) {
+  return isGhPrVerbCommand(command, "ready");
+}
+
+/** @param {string} command @returns {number|null} */
+export function extractPrNumberFromGhPrReady(command) {
+  return extractPrNumberFromGhPrVerb(command, "ready");
+}
+
+/** @param {string} command @returns {string|null} */
+export function extractRepoFlagFromGhPrReady(command) {
+  return extractRepoFlagFromGhPrVerb(command, "ready");
+}
+
+/**
+ * Whether `command` contains a `gh pr merge` invocation in the FIRST shell segment,
+ * ignoring `--help`/`-h`. Used by the Pi extension's post-execute handler.
+ * For the Claude Code PreToolUse gate, use `commandContainsGhPrMerge` instead.
+ * @param {string} command @returns {boolean}
+ */
+export function isGhPrMergeCommand(command) {
+  return isGhPrVerbCommand(command, "merge");
+}
+
+/**
+ * Whether `command` contains a `gh pr ready` invocation in ANY shell segment.
+ * For use in the Claude Code PreToolUse gate only — blocks the whole command pre-emptively
+ * regardless of shell short-circuit semantics (`false && gh pr ready 42` is still blocked).
+ * @param {string} command @returns {boolean}
+ */
+export function commandContainsGhPrReady(command) {
+  return findGhPrVerbSegment(command, "ready") !== null;
+}
+
+/**
+ * Whether `command` contains a `gh pr merge` invocation in ANY shell segment.
+ * For use in the Claude Code PreToolUse gate only — blocks the whole command pre-emptively.
+ * @param {string} command @returns {boolean}
+ */
+export function commandContainsGhPrMerge(command) {
+  return findGhPrVerbSegment(command, "merge") !== null;
+}
+
+/** Extract PR number from `gh pr ready` in any shell segment — PreToolUse gate use only. */
+export function extractPrNumberFromGhPrReadyAnywhere(command) {
+  return extractPrNumberFromSegment(findGhPrVerbSegment(command, "ready"), "ready");
+}
+
+/** @param {string} command @returns {string|null} */
+export function extractRepoFlagFromGhPrReadyAnywhere(command) {
+  return extractRepoFlagFromSegment(findGhPrVerbSegment(command, "ready"), "ready");
+}
+
+/** Extract PR number from `gh pr merge` in any shell segment — PreToolUse gate use only. */
+export function extractPrNumberFromGhPrMergeAnywhere(command) {
+  return extractPrNumberFromSegment(findGhPrVerbSegment(command, "merge"), "merge");
+}
+
+/** @param {string} command @returns {string|null} */
+export function extractRepoFlagFromGhPrMergeAnywhere(command) {
+  return extractRepoFlagFromSegment(findGhPrVerbSegment(command, "merge"), "merge");
+}
+
+/**
+ * Whether `command` contains a raw `gh pr create` invocation in ANY shell segment.
+ * PreToolUse gate use only — blocks raw `gh pr create` so PR creation flows through the
+ * canonical wrapper (`scripts/github/create-pr.mjs` / `dev-loops pr create`), which always
+ * creates a draft and self-assigns. The wrapper runs `gh pr create` inside a node child
+ * process, so its Bash command string (`node …/create-pr.mjs …`) never matches this — only a
+ * literal `gh pr create` in the agent's shell command does.
+ * @param {string} command @returns {boolean}
+ */
+export function commandContainsGhPrCreate(command) {
+  return findGhPrVerbSegment(command, "create") !== null;
+}
+
+/** Extract repo flag from `gh pr create` in any shell segment — PreToolUse gate use only. */
+export function extractRepoFlagFromGhPrCreateAnywhere(command) {
+  return extractRepoFlagFromSegment(findGhPrVerbSegment(command, "create"), "create");
+}
+
+/**
+ * Return one `{ segment, explicitRepo }` entry for EVERY `gh pr create` segment (ignoring
+ * --help/-h), not just the first. PreToolUse gate use only: the create-scope decision must
+ * consider every create segment, so a leading out-of-scope create can't shield a later
+ * in-scope raw create (`gh pr create --repo other/repo && gh pr create --fill`).
+ * `explicitRepo` is the segment's `--repo`/`-R` value or null when none is present.
+ * @param {string} command @returns {{ segment: string, explicitRepo: string|null }[]}
+ */
+export function extractRepoFlagsFromGhPrCreateSegments(command) {
+  return extractRepoFlagsFromGhSubcmdVerbSegments(command, "pr", "create");
+}
+
+/** @param {string} command @returns {number|null} */
+export function extractPrNumberFromGhPrMerge(command) {
+  return extractPrNumberFromGhPrVerb(command, "merge");
+}
+
+/** @param {string} command @returns {string|null} */
+export function extractRepoFlagFromGhPrMerge(command) {
+  return extractRepoFlagFromGhPrVerb(command, "merge");
 }