Improve PPL bugfix command: permission modes, parallel dispatch, file reorg

- Add --safe/--yolo permission mode flags (default: bypassPermissions)
- Support multiple issue/PR references for parallel processing
- Move harness files to .claude/harness/ directory
- Add ppl-bugfix-followup.md for post-PR follow-up workflow
- Add .claude/settings.json with pre-approved tool permissions
- Add CLAUDE_GUIDE.md documenting all slash commands

Signed-off-by: Heng Qian <qianheng@amazon.com>

Author: qianheng-aws

.claude/commands/ppl-bugfix.md

@@ -3,17 +3,44 @@ allowed-tools: Agent, Read, Bash(gh:*), Bash(git:*)
 description: Run the PPL bugfix harness for a GitHub issue or follow up on an existing PR
 ---
 
-Fix a PPL bug or follow up on an existing PR using the harness in `ppl-bugfix-harness.md`.
+Fix a PPL bug or follow up on an existing PR using the harness in `.claude/harness/ppl-bugfix-harness.md`.
 
 ## Input
 
-- `/ppl-bugfix #1234` or `/ppl-bugfix 1234` — issue number
-- `/ppl-bugfix PR#5678` or `/ppl-bugfix pr 5678` — PR number
+Accepts one or more issue/PR references. Multiple references are processed in parallel (each gets its own subagent + worktree).
+
+- `/ppl-bugfix #1234` — single issue
+- `/ppl-bugfix PR#5678` — single PR
+- `/ppl-bugfix #1234 #5678 PR#9012` — multiple in parallel
 - `/ppl-bugfix https://github.com/opensearch-project/sql/issues/1234` — URL
 
+Optional mode flag (append to any of the above):
+- `--safe` — `acceptEdits` mode. Auto-approve file edits only, Bash commands require manual approval. (Most conservative)
+- `--yolo` — `bypassPermissions` mode. Fully trusted, no prompts. Subagent runs in an isolated worktree so this is safe. (Default)
+
+Examples:
+- `/ppl-bugfix #1234` — single issue, defaults to yolo
+- `/ppl-bugfix #1234 #5678 --yolo` — two issues in parallel
+- `/ppl-bugfix PR#5293 PR#5300` — two PRs in parallel
+- `/ppl-bugfix #1234 PR#5678 --safe` — mix of issue and PR
+
 If no argument given, ask for an issue or PR number.
 
-## Step 1: Resolve Issue ↔ PR
+## Step 0: Resolve Permission Mode
+
+Parse the mode flag from the input arguments:
+
+| Flag | Mode |
+|------|------|
+| `--safe` | `acceptEdits` |
+| `--yolo` | `bypassPermissions` |
+| _(no flag)_ | `bypassPermissions` (default) |
+
+Use the resolved mode as the `mode` parameter when dispatching the subagent in Step 2A/2B.
+
+## Step 1: Resolve Each Reference
+
+For each issue/PR reference in the input, resolve its state. Run these lookups in parallel when there are multiple references.
 
 ```bash
 # Issue → PR
@@ -29,64 +56,44 @@ gh pr view <pr_number> --json body | jq -r '.body' | grep -oP 'Resolves #\K[0-9]
 | Issue exists, open PR found | **Follow-up** (Step 2B) |
 | PR provided directly | **Follow-up** (Step 2B) |
 
-## Step 2A: Initial Fix
+## Step 2: Dispatch Subagents
 
-1. `gh issue view <issue_number>`
-2. `Read ppl-bugfix-harness.md`
-3. Dispatch subagent:
+Dispatch one subagent per reference. When there are multiple references, dispatch all subagents in a single message (parallel execution).
+
+### 2A: Initial Fix
 
 ```
 Agent(
-  mode: "acceptEdits",
+  mode: "<resolved_mode>",
   isolation: "worktree",
   name: "bugfix-<issue_number>",
   description: "PPL bugfix #<issue_number>",
-  prompt: "<FULL harness content> + <issue details>
+  prompt: "Read .claude/harness/ppl-bugfix-harness.md and follow it to fix GitHub issue #<issue_number>.
            Follow Phase 0 through Phase 3 in order.
            Phase 0.3 defines TDD execution flow. Do NOT skip any phase.
            Post the Decision Log (Phase 3.4) before completing."
 )
 ```
 
-The `isolation: "worktree"` creates a temporary git worktree branched from the current HEAD. The agent works in a clean, isolated copy of the repo — no interference with the user's working directory. If the agent makes changes, the worktree path and branch are returned in the result.
-
-4. Report back: classification, fix summary, PR URL, **worktree branch name**, items needing human attention.
-
-## Step 2B: Follow-up
-
-1. Load PR state:
-```bash
-gh pr view <pr_number> --json title,body,state,reviews,comments,statusCheckRollup,mergeable
-gh pr checks <pr_number>
-```
-
-2. Categorize:
-
-| Signal | Type |
-|--------|------|
-| `statusCheckRollup` has failures | CI failure |
-| `reviews` has CHANGES_REQUESTED | Review feedback |
-| `mergeable` is CONFLICTING | Merge conflict |
-| All pass + approved | Ready — run `gh pr ready` |
-
-3. `Read ppl-bugfix-harness.md`
-4. Dispatch follow-up subagent:
+### 2B: Follow-up
 
 ```
 Agent(
-  mode: "acceptEdits",
+  mode: "<resolved_mode>",
   isolation: "worktree",
-  name: "bugfix-<issue_number>-followup",
+  name: "bugfix-<issue_number>",
   description: "PPL bugfix #<issue_number> followup",
-  prompt: "<Phase 3.5 content from harness>
+  prompt: "Read .claude/harness/ppl-bugfix-followup.md and follow it.
            PR: <pr_number> (<pr_url>), Issue: #<issue_number>
-           Follow-up type: <CI failure / review feedback / merge conflict>
-           Read the Decision Log PR comment FIRST before making any changes.
-           Checkout the PR branch before starting: git checkout <pr_branch>"
+           Follow-up type: <CI failure / review feedback / merge conflict>"
 )
 ```
 
-5. Report back: what was addressed, current PR state, whether another round is needed.
+## Step 3: Report Back
+
+After all subagents complete, report a summary for each:
+- Classification, fix summary, PR URL, worktree path and branch, items needing human attention (2A)
+- What was addressed, current PR state, whether another round is needed (2B)
 
 ## Subagent Lifecycle
 
@@ -106,6 +113,8 @@ Context is preserved across agents via:
 
 ## Rules
 
-- Always inline harness content in the subagent prompt — subagents cannot read skill files
+- Subagent reads `.claude/harness/ppl-bugfix-harness.md` and fetches issue/PR details itself — do NOT inline content into the prompt
 - If bug is not reproducible (Phase 0.1), stop and report — do not proceed
 - Issue ↔ PR auto-resolution means the user never needs to track PR numbers manually
+- **Do NOT use `mode: "auto"` for subagents** — `auto` mode does not work for subagents; Bash commands still require manual approval. Only `bypassPermissions` reliably skips permission checks.
+- **Always dispatch subagent** — even for trivial follow-ups (remove co-author, force push). Do NOT run commands directly in the main session; subagents with `bypassPermissions` skip permission prompts, the main session does not.

.claude/harness/ppl-bugfix-followup.md

@@ -0,0 +1,70 @@
+# PPL Bugfix Follow-up
+
+---
+
+## Reconstruct Context
+
+The follow-up agent runs in a fresh worktree. First checkout the PR branch, then load state:
+
+```bash
+# Checkout the PR branch in this worktree
+gh pr checkout <pr_number>
+
+# Load PR state and Decision Log
+gh pr view <pr_number> --json title,body,state,reviews,comments,statusCheckRollup,mergeable
+gh pr checks <pr_number>
+# Read the Decision Log comment FIRST — contains rejected alternatives and pitfalls
+gh api repos/<owner>/<repo>/pulls/<pr_number>/comments
+```
+
+## Handle Review Feedback
+
+For each comment, **cross-check against the Decision Log first**:
+
+| Type | Action |
+|------|--------|
+| Code change | If already rejected in Decision Log, reply with reasoning. Otherwise make the change, new commit, push |
+| Question | Reply with explanation — Decision Log often has the answer |
+| Nit | Fix if trivial |
+| Disagreement | Reply with Decision Log reasoning; if reviewer insists, escalate to user |
+
+```bash
+git add <files> && git commit -s -m "Address review feedback: <description>"
+git push <your_fork_remote> <branch_name>
+```
+
+## Clean Up Commit History
+
+When you need to amend a commit (e.g. remove Co-Authored-By, reword message) and the branch has a merge commit on top, don't try `git reset --soft origin/main` — it will include unrelated changes if main has moved. Instead cherry-pick the fix onto latest main:
+
+```bash
+git checkout -B clean-branch origin/main
+git cherry-pick <fix_commit_sha>
+git commit --amend -s -m "<updated message>"
+git push <your_fork_remote> clean-branch:<pr_branch> --force
+```
+
+## Handle CI Failures
+
+```bash
+gh pr checks <pr_number>                  # Identify failures
+gh run view <run_id> --log-failed         # Read logs
+# Test failure → fix locally, push new commit
+# Spotless → ./gradlew spotlessApply, push
+# Flaky → gh run rerun <run_id> --failed
+```
+
+## Handle Merge Conflicts
+
+```bash
+git fetch origin && git merge origin/main  # Resolve conflicts
+./gradlew spotlessApply && ./gradlew test && ./gradlew :integ-test:integTest  # Re-verify
+git commit -s -m "Resolve merge conflicts with main"
+git push <your_fork_remote> <branch_name>
+```
+
+## Mark Ready
+
+```bash
+gh pr ready <pr_number>
+```

ppl-bugfix-harness.md .claude/harness/ppl-bugfix-harness.mdppl-bugfix-harness.md renamed to .claude/harness/ppl-bugfix-harness.md

@@ -1,11 +1,17 @@
 # PPL Bugfix Harness
 
-> Systematic bugfix workflow distilled from 15+ historical commits. Invoke via `/ppl-bugfix #<issue_number>`.
-
 ---
 
 ## Phase 0: Triage & Classification
 
+### 0.0 Load Issue Context
+
+```bash
+gh issue view <issue_number> --repo opensearch-project/sql
+```
+
+Read the issue title, description, and any reproduction steps before proceeding.
+
 ### 0.1 Reproduce the Bug
 
 ```bash
@@ -221,10 +227,8 @@ teardown:
 
 ### 3.2 Commit & Push
 
-The subagent runs in an isolated **git worktree** branched from HEAD. All changes are on a dedicated branch that does not affect the user's working directory.
-
 ```bash
-# Commit with DCO sign-off
+# Commit with DCO sign-off — do NOT add Co-Authored-By lines
 git add <changed_files>
 git commit -s -m "[BugFix] Fix <description> (#<issue_number>)"
 
@@ -277,68 +281,6 @@ EOF
 
 ---
 
-## Phase 3.5: Post-PR Follow-up
-
-Runs as a **separate subagent** invocation — the original agent has completed. Invoke via `/ppl-bugfix #<issue>` or `/ppl-bugfix PR#<pr>` (auto-detects follow-up mode when a PR exists).
-
-### 3.5.1 Reconstruct Context
-
-The follow-up agent runs in a fresh worktree. First checkout the PR branch, then load state:
-
-```bash
-# Checkout the PR branch in this worktree
-gh pr checkout <pr_number>
-
-# Load PR state and Decision Log
-gh pr view <pr_number> --json title,body,state,reviews,comments,statusCheckRollup,mergeable
-gh pr checks <pr_number>
-# Read the Decision Log comment FIRST — contains rejected alternatives and pitfalls
-gh api repos/<owner>/<repo>/pulls/<pr_number>/comments
-```
-
-### 3.5.2 Handle Review Feedback
-
-For each comment, **cross-check against the Decision Log first**:
-
-| Type | Action |
-|------|--------|
-| Code change | If already rejected in Decision Log, reply with reasoning. Otherwise make the change, new commit, push |
-| Question | Reply with explanation — Decision Log often has the answer |
-| Nit | Fix if trivial |
-| Disagreement | Reply with Decision Log reasoning; if reviewer insists, escalate to user |
-
-```bash
-git add <files> && git commit -s -m "Address review feedback: <description>"
-git push <your_fork_remote> <branch_name>
-```
-
-### 3.5.3 Handle CI Failures
-
-```bash
-gh pr checks <pr_number>                  # Identify failures
-gh run view <run_id> --log-failed         # Read logs
-# Test failure → fix locally, push new commit
-# Spotless → ./gradlew spotlessApply, push
-# Flaky → gh run rerun <run_id> --failed
-```
-
-### 3.5.4 Handle Merge Conflicts
-
-```bash
-git fetch origin && git merge origin/main  # Resolve conflicts
-./gradlew spotlessApply && ./gradlew test && ./gradlew :integ-test:integTest  # Re-verify
-git commit -s -m "Resolve merge conflicts with main"
-git push <your_fork_remote> <branch_name>
-```
-
-### 3.5.5 Mark Ready
-
-```bash
-gh pr ready <pr_number>
-```
-
----
-
 ## Phase 4: Retrospective
 
 After each bugfix, check if the harness itself needs updating:
@@ -381,3 +323,4 @@ Regex/function extraction offset                  → Path B: ordinal vs named r
 | `734394d` | Grammar rule typo | Grammar | — |
 | `246ed0d` | Float precision flaky test | Test Infra | — |
 | `d56b8fa` | Wildcard index type conflict | Value Parsing | 3 UT + 1 IT + 1 YAML |
+| `5a78b78` | Boolean coercion from numeric in wildcard queries | Value Parsing | 3 UT + 1 IT + 1 YAML |

.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(./gradlew *)",
+      "Bash(gh issue:*)",
+      "Bash(gh pr:*)",
+      "Bash(gh api:*)",
+      "Bash(gh search:*)",
+      "Bash(gh run:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git stash:*)",
+      "Bash(git show:*)",
+      "Bash(git diff:*)",
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git branch:*)",
+      "Bash(git remote:*)",
+      "Bash(git fetch:*)",
+      "Bash(git checkout:*)",
+      "Bash(git push:*)",
+      "Bash(git cherry-pick:*)",
+      "Bash(git reset:*)"
+    ]
+  }
+}

.gitignore

@@ -56,6 +56,7 @@ http-client.env.json
 .claude/*
 !.claude/settings.json
 !.claude/commands/
+!.claude/harness/
 .claude/settings.local.json
 .clinerules
 memory-bank

CLAUDE.md

@@ -125,7 +125,7 @@ plugin (OpenSearch plugin entry point, Guice DI wiring)
 
 ## Fixing PPL Bugs
 
-Use the `/ppl-bugfix #<issue_number>` slash command to fix PPL bugs. It dispatches a subagent with scoped permissions that follows all phases in `ppl-bugfix-harness.md` — from Phase 0 (Triage & Classification) through Phase 4 (Retrospective & Improvement). The full harness content is inlined into the subagent prompt to guarantee compliance. If a user asks to fix a PPL bug without using the slash command, remind them to use `/ppl-bugfix` or invoke it on their behalf.
+Use the `/ppl-bugfix #<issue_number>` slash command to fix PPL bugs. It dispatches a subagent in an isolated worktree that reads `.claude/harness/ppl-bugfix-harness.md` and follows all phases — from Phase 0 (Triage & Classification) through Phase 4 (Retrospective & Improvement). If a user asks to fix a PPL bug without using the slash command, remind them to use `/ppl-bugfix` or invoke it on their behalf.
 
 ## Adding New PPL Commands