claude-dev-env 1.38.1 → 1.40.0

package/skills/pr-consistency-audit/reference/detection-rules.md

@@ -0,0 +1,96 @@
+# Detection Rules
+
+All 10 rules. Run every rule against every file. Do not skip. Do not combine. Rules are independent — a file can trigger multiple rules.
+
+## Rule 1: Canonical-source cross-reference
+
+For every canonical source, scan every other file for usages of the concepts it defines. The canonical source is the ground truth. Flag every mismatch.
+
+How: Take the canonical MCP payload doc. Extract every tool name and its parameter names. Scan every markdown file for calls to those tools. Compare each call's parameter names against the canonical form.
+
+How: Take the canonical config file. Extract every constant name and value. Scan every other file. Flag any file that hardcodes the value. Flag any file that uses a different value for the same concept.
+
+This rule caught 20 of Copilot's 43 findings. It is the highest-signal rule. Run it first.
+
+## Rule 2: Parameter naming convention
+
+Group all MCP tool calls by tool name. Check whether all call sites use the same parameter naming convention.
+
+How: Extract every parameter name from every tool call. Group by tool. If `add_issue_comment` appears in 10 files and 8 use `issueNumber` while 2 use `issue_number`, flag the 2.
+
+Conventions are per-tool. `issue_read` uses `issue_number` (snake_case). `add_issue_comment` uses `issueNumber` (camelCase). Snake_case for `add_issue_comment` is wrong.
+
+Also: check for two different parameter names that mean the same thing. `--number` vs `--pr-number` for a script that expects `--pr-number`.
+
+## Rule 3: Code vs docstring behavior
+
+For every function whose docstring makes a claim about return values or error handling, read the implementation.
+
+How: Find docstrings that say "returns X when Y" or "raises Z on error." Trace the code path. If the docstring says returns 0 when path missing but the code catches OSError and returns failure, flag it.
+
+How: Find docstrings that claim a side effect. Check whether the code does it unconditionally. Flag missing precondition checks.
+
+How: Find error handling claims like "tolerates already-removed worktrees." Read the except blocks. Read the conditionals. Verify every claim.
+
+## Rule 4: Nonexistent reference
+
+Every file path, script name, function name, tool name, or import referenced in a doc must resolve to something real.
+
+How: Extract every backtick-quoted identifier. Try to resolve it against the diff and the repo. Flag anything that cannot be found. A reference to `fetch_copilot_inline_comments.py` when no such file exists is P0. A reference to `EnterWorktree(path=...)` when no MCP tool by that name exists is P0.
+
+## Rule 5: Placeholder detection
+
+Scan for text that looks like a template never filled in. This is text that cannot be executed as written.
+
+Patterns to search for:
+- Double spaces where a value should be: "Spawn  — brief it: check  for"
+- Angle-bracket placeholders outside the standard `<O>` `<R>` `<N>` `<SHA>` set
+- Ellipsis as placeholder: "...", "…"
+- "TODO", "FIXME", "HACK", "XXX" in production documentation
+- "TKTK", "TK", "placeholder"
+- Missing arguments after a flag: `--flag` with no value following
+- Sentences that trail off: text ending in ", or", "like", "such as" without completing
+
+Severity: unexecutable placeholder is P0. Incomplete but still directionally useful is P1.
+
+## Rule 6: Cross-file contradiction
+
+When two files describe the same operation, they must agree.
+
+How: Group descriptions by topic — "how to post a review," "how to trigger bugbot," "who owns PR posting." For each topic, extract the description from every file. Compare who performs the action, what API is used, what parameters are passed, what the workflow order is. Flag any contradiction.
+
+Flag both files. Do not assume which is correct unless a canonical source resolves it.
+
+## Rule 7: Stale reference
+
+When a doc describes a feature, branch, phase, or pattern by name, verify the implementation still contains it.
+
+How: Extract named concepts from decision branches and gotcha sections. Search implementation files for each concept. If a doc describes an "inline_lag" branch but no implementation file contains "inline_lag" or "inline_lag_streak," the doc references a removed feature.
+
+P1: doc mentions something absent from implementation. P0: doc decision tree includes a branch whose predicate can never be reached because the implementation was removed.
+
+## Rule 8: Cross-platform assumption
+
+Code that handles platform-specific behavior must not break on other platforms.
+
+When you see Windows-specific patterns (`os.chmod` with `stat.S_IWRITE`, backslash paths, ReadOnly attribute handling), check: Does it run on Linux without crashing? Does `os.chmod(path, stat.S_IWRITE)` produce the right permissions on POSIX? It sets write-only, stripping read and execute from directories.
+
+Flag anything that would fail on a non-Windows system. Flag the reverse: POSIX-only code that would fail on Windows.
+
+## Rule 9: Script invocation correctness
+
+Every `python scripts/foo.py --*` in docs must match the script's actual argparse interface.
+
+From your manifest, compare each documented invocation against the script's `add_argument` definitions. Check every flag name matches exactly. Check every `required=True` argument is present. Check no argument appears that the script does not accept.
+
+Missing required args = P0. Wrong flag names = P0. Missing optional args = P2.
+
+argparse converts `--pr-number` to `pr_number`. The invocation flag is `--pr-number`, not `--pr_number` or `--number`.
+
+## Rule 10: Value consistency
+
+When the same named concept has a numeric value in multiple files, all files must agree.
+
+How: Group constants, thresholds, and timeouts by semantic concept. "Bugbot post-trigger wakeup" vs "inline-lag retry delay" are different concepts. Values that represent the same thing must match. Flag any file whose value differs from the majority or from the canonical config.
+
+Values that legitimately differ by context are not conflicts. Group by full semantic meaning before comparing.

package/skills/pr-consistency-audit/reference/illustrations.md

@@ -0,0 +1,78 @@
+# Illustrations
+
+Concrete examples of findings with why-they-matter explanations.
+
+## Wrong argument name in script invocation
+
+```
+file_path: SKILL.md
+line_number: 100
+rule_id: 9
+severity: P0
+what_is_wrong: check_bugbot_ci.py --check-active --sha <SHA>
+what_it_should_be: check_bugbot_ci.py --owner <O> --repo <R> --check-active --sha <SHA>
+evidence_path: scripts/check_bugbot_ci.py
+evidence_detail: lines 134-136 define add_argument("--owner", required=True) and add_argument("--repo", required=True). Both required args are missing from the documented invocation.
+```
+
+Why this matters: If an agent copies the command from the doc, the script fails with "the following arguments are required: --owner, --repo." The agent cannot trigger bugbot.
+
+## Parameter naming convention mismatch across tool family
+
+```
+file_path: SKILL.md
+line_number: 162
+rule_id: 2
+severity: P0
+what_is_wrong: add_issue_comment(owner="OWNER", repo="REPO", issue_number=NUMBER, body="bugbot run")
+what_it_should_be: add_issue_comment(owner="OWNER", repo="REPO", issueNumber=NUMBER, body="bugbot run")
+evidence_path: _shared/pr-loop/gh-payloads.md
+evidence_detail: lines 67-72 document add_issue_comment with issueNumber (camelCase). issue_read uses issue_number (snake_case) — the two tools have different conventions.
+```
+
+Why this matters: The tool call fails at runtime. Twenty files had this same bug because they copied from each other.
+
+## Docstring claim contradicts implementation
+
+```
+file_path: scripts/remove_tree.py
+line_number: 15
+rule_id: 3
+severity: P0
+what_is_wrong: Docstring says "returns 0 when the path never existed." Implementation calls shutil.rmtree(target_path) which raises FileNotFoundError, caught as OSError, returning EXIT_CODE_REMOVE_TREE_FAILURE.
+what_it_should_be: Check Path(target_path).exists() before rmtree and return 0 when absent, or update the docstring.
+evidence_path: scripts/remove_tree.py
+evidence_detail: line 15 docstring claim vs lines 22-28 implementation — the except OSError handler returns EXIT_CODE_REMOVE_TREE_FAILURE for FileNotFoundError.
+```
+
+Why this matters: Teardown scripts calling remove_tree() on an already-cleaned temp directory get a failure return. The orchestrator treats this as a real error.
+
+## Stale feature reference in gotcha section
+
+```
+file_path: SKILL.md
+line_number: 34
+rule_id: 7
+severity: P1
+what_is_wrong: Gotcha describes "inline_lag" with its own streak counter and 90s wait. The decision branch for inline_lag is still present in per-tick.md lines 102-106 — the feature was supposed to be removed but both the gotcha and the branch remain.
+what_it_should_be: Remove the gotcha and the inline_lag decision branch from per-tick.md.
+evidence_path: reference/per-tick.md
+evidence_detail: lines 102-106 still contain the fourth BUGBOT decision branch for inline_lag.
+```
+
+Why this matters: An agent reading the gotcha thinks inline_lag is real and may misclassify a dirty review as transient lag, waiting rather than fixing.
+
+## Placeholder text in template file
+
+```
+file_path: bugteam/obstacles/self-population.md
+line_number: 5
+rule_id: 5
+severity: P1
+what_is_wrong: "Spawn  — brief it: check  for an open PR  " contains double spaces where an agent invocation, repo, and PR number should be.
+what_it_should_be: Fill in the concrete Agent call or remove the section until populated.
+evidence_path: bugteam/obstacles/self-population.md
+evidence_detail: Template has placeholder spacing with no variable substitutions defined.
+```
+
+Why this matters: Obstacle files are reference material for agents. An obstacle with "Spawn — brief it: check for" and no target wastes context and confuses.

package/skills/pr-converge/SKILL.md

@@ -17,8 +17,28 @@ until all three are clean on the same `HEAD` and mergeable.
 
 ## Pre-flight
 
-`ScheduleWakeup` not in this turn's tool registry → abort. Report
-`pr-converge requires ScheduleWakeup; aborting` and return.
+Pause and physically scan the tool list at the top of this conversation
+for the literal string `ScheduleWakeup`. If you see it, proceed. If the
+string is absent after scanning, report `pr-converge requires
+ScheduleWakeup; aborting` and stop.
+
+Call `EnterWorktree` with no arguments before any API call, file read, or
+edit. Agent-view sessions start in the shared checkout. While Write/Edit
+tools auto-isolate on first use, Bash calls (`gh`, `git`) do not trigger
+isolation and will modify shared state. This step is mandatory — do not
+proceed to any state-modifying operation until the working directory
+contains `.claude/worktrees/`. If `EnterWorktree` fails, report the failure
+and stop; do not continue in place.
+
+## State persistence
+
+Single-PR mode persists loop state to `$CLAUDE_JOB_DIR/pr-converge-state.json`.
+On tick entry, read this file if it exists to restore phase, tick_count, and
+clean-at SHAs. On tick exit, write updated state before calling ScheduleWakeup
+so the next tick resumes with accurate state.
+
+Fields: `phase`, `tick_count`, `bugbot_clean_at`, `bugteam_clean_at`,
+`copilot_clean_at`, `current_head`, `bugbot_acknowledged_at`, `bugbot_down`.
 
 ## Gotchas
 
@@ -30,42 +50,228 @@ post a fresh PR in a fresh branch based on origin main to the user.
 - **`ScheduleWakeup` not in subagent tool registries** — background
   `general-purpose` tick cannot schedule re-entry; only parent session
   with `ScheduleWakeup` in registry can call it.
-- **Review body and inline comments desync for same `commit_id`** —
-  "dirty body, zero inline rows at `current_head`" is **`inline_lag`**,
-  not **`dirty`**. Bump `inline_lag_streak`, wait 90s, retry fetch.
 - **`state.json` without §Concurrency lock loses merges** when teammates
   finish in same wall-clock window.
 - **`tick_count` must not double-increment** — conversation state line
   only when **no** `state.json`; with `state.json`, only the
   orchestrator bump increments.
-- **Duplicate `bugbot run` while review queued** — skip Step 3 when the
-  latest `bugbot run` PR comment has an `:eyes:` or `:+1:` reaction;
-  wait for review or HEAD change before re-triggering.
+- **Bugbot trigger and detection** — CI check-run based. Full flow at
+  [`per-tick.md` Step 3](reference/per-tick.md); see also
+  `~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --help`.
 - **Bot login fields differ by endpoint** — `get_reviews` returns
   `.user.login` (object), but `get_review_comments` returns `.author`
-  (string, not an object). Threads use `is_outdated` (not `commit_id`) to
-  indicate staleness. Always check the correct fields and use
+  (string, not an object). Always check the correct fields and use
   case-insensitive substring matching on login values, never strict
   equality.
+- **`is_outdated` is informational, not a skip flag** — GitHub marks a
+  thread `is_outdated=true` when the line it anchors to has changed since
+  the comment was posted. The original concern can still apply to current
+  code (the fix may have moved, not landed). The convergence gate counts
+  every thread with `is_resolved == false` regardless of `is_outdated`.
+  Outdated threads must be verified against current HEAD and either
+  fix-and-resolved or just resolved (with an inline reply explaining why
+  the concern no longer applies).
+- **Tilde paths fail on Windows Git Bash** — `~/.claude/skills/...`
+  resolves to the wrong home directory in Bash-tool contexts. Use
+  `$HOME/.claude/skills/...` in shell invocations or `Path.home() /
+  ".claude/skills/..."` in Python scripts. Script invocations through
+  Bash that reference `~` produce "file not found" errors
+  indistinguishable from actual script failures.
+- **PowerShell cmdlets fail in Bash tool** — `.ps1` scripts and
+  `pwsh` calls run through the PowerShell tool, not Bash. Bash on
+  Windows is Git Bash which cannot execute PowerShell cmdlets. Route all
+  PowerShell work through the PowerShell tool or `pwsh -NoProfile -File`.
+
+## Progress checklist
+
+State variables (`phase`, `bugbot_clean_at`, `copilot_clean_at`, counters) are
+defined in [`reference/state-schema.md`](reference/state-schema.md). Ground rules
+in [`reference/ground-rules.md`](reference/ground-rules.md).
+
+Each step references its spoke file for full procedural detail — MCP calls,
+script invocations, decision criteria. Every "return to Step N" means the next
+tick starts fresh from that step.
+
+**Hard gate: do not advance from any step while ANY unresolved review
+thread exists on the PR.** The thread-count filter is purely
+`is_resolved == false` — author, commit anchor, and `is_outdated` are
+all irrelevant. After every fix, reply to each finding comment and
+resolve the thread via `pull_request_review_write(method="resolve_thread")`.
+For each unresolved thread, verify the concern against current HEAD;
+either fix-and-resolve, or reply-with-note-and-resolve when the concern
+no longer applies.
+
+- [ ] **Step 0: Grant project permissions**
+      `python "$HOME/.claude/skills/bugteam/scripts/grant_project_claude_permissions.py"`
+
+- [ ] **Step 1: Resolve PR scope**
+      Capture owner, repo, number, head SHA, branch.
+      See: [`reference/per-tick.md` § Step 1](reference/per-tick.md)
+
+- [ ] **Step 2: Initialize loop state**
+      `phase = BUGBOT`; all counters at zero; `run_name` resolved.
+
+- [ ] **Step 3: Mergeability check**
+      See: [`reference/convergence-gates.md` § (c)](reference/convergence-gates.md)
+
+      ```
+      pull_request_read(method="get") → .mergeable_state, .mergeable
+      ```
+
+      - [ ] mergeable → advance to Step 4
+      - [ ] not mergeable → rebase → force-push → return to Step 1
+
+- [ ] **Step 4: BUGBOT — fetch, decide, fix, reply, resolve**
+      See: [`reference/per-tick.md` § Step 2 BUGBOT + Step 3](reference/per-tick.md)
+
+      Fetch bugbot reviews + inline comments on `current_head`.
+
+      - [ ] **dirty** (findings on `current_head`) →
+            - [ ] Fix each finding (spawn `clean-coder`)
+            - [ ] Reply to each finding comment via `python ~/.claude/skills/pr-converge/scripts/post_fix_reply.py`
+            - [ ] Resolve each addressed thread via `pull_request_review_write(method="resolve_thread")`
+            - [ ] Push → return to Step 4
+      - [ ] **clean** (no findings on `current_head`) →
+            - [ ] Count ALL unresolved threads on PR (`is_resolved == false`) → zero? advance; >0? fix + resolve first
+            - [ ] `bugbot_clean_at = current_head`
+            - [ ] Advance to Step 5
+      - [ ] **no review yet / commit_id mismatch** →
+            - [ ] Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --owner <O> --repo <R> --check-clean --sha <current_head>`
+            - [ ] Exit 0 (bugbot CI completed with success/neutral conclusion and no review = silent pass) → `bugbot_clean_at = current_head` → advance to Step 5
+            - [ ] Exit 1 (not a silent pass) or Exit 2 (gh CLI error — silent pass not confirmable) → Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --owner <O> --repo <R> --check-active --sha <current_head>`
+            - [ ] Exit 0 (already queued) → schedule 360s wakeup → return to Step 4 next tick
+            - [ ] Exit 1 → post exactly `bugbot run` via `add_issue_comment` (no `@cursor[bot]` mention, no other text), wait 8s
+            - [ ] Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --owner <O> --repo <R> --sha <current_head>`
+            - [ ] Exit non-zero → `bugbot_down = true` → advance to Step 5 (bypass)
+            - [ ] Exit 0 → record `bugbot_acknowledged_at`, schedule 360s wakeup → return to Step 4
+- [ ] **Step 5: BUGTEAM — run, decide, fix, reply, resolve**
+      See: [`reference/per-tick.md` § Step 2 BUGTEAM](reference/per-tick.md);
+      [`../../bugteam/SKILL.md`](../../bugteam/SKILL.md)
+
+      Pre-condition: `bugbot_clean_at == current_head` (or `bugbot_down == true`).
+
+      Run `Skill({skill: "bugteam", args: "<PR URL>"})`.
+      After bugteam completes, re-resolve HEAD.
+
+      - [ ] **bugteam pushed new commits** →
+            - [ ] Verify all bugteam review threads replied + resolved
+            - [ ] Re-trigger bugbot (Step 4 "no review yet" checklist)
+            - [ ] `phase = BUGBOT` → schedule 360s wakeup → return to Step 4
+      - [ ] **converged (zero findings) + `bugbot_clean_at == current_head`** →
+            - [ ] Count ALL unresolved threads on PR (`is_resolved == false`) → zero? advance; >0? fix + resolve first
+            - [ ] Advance to Step 6
+      - [ ] **converged + `bugbot_clean_at ≠ current_head`** →
+            `phase = BUGBOT` → schedule 360s wakeup → return to Step 4
+      - [ ] **findings without committed fixes** →
+            - [ ] Fix each finding (spawn `clean-coder`)
+            - [ ] Reply to each finding comment via `python ~/.claude/skills/pr-converge/scripts/post_fix_reply.py`
+            - [ ] Resolve each addressed thread via `pull_request_review_write(method="resolve_thread")`
+            - [ ] Push → `phase = BUGBOT` → return to Step 4
+
+- [ ] **Step 6: Convergence gates**
+      See: [`reference/convergence-gates.md`](reference/convergence-gates.md)
+
+      Pre-condition: Step 5 converged AND `bugbot_clean_at == current_head`.
+      Count unresolved threads before each gate.
+
+      **(a) Universal unresolved-thread sweep**
+      - [ ] Fetch ALL unresolved threads on the PR:
+            ```
+            pull_request_read(method="get_review_comments")
+              → filter threads where is_resolved == false
+            ```
+      - [ ] Any unresolved? → For each: verify concern against current HEAD;
+            if still applies → Fix (spawn `clean-coder`) → reply → resolve;
+            if no longer applies → reply-with-note → resolve. Push if any code changed → return to Step 4
+      - [ ] Fetch Copilot review on `current_head` (top-level review state — uses get_reviews, identifies by reviewer):
+            ```
+            python ~/.claude/skills/pr-converge/scripts/fetch_copilot_reviews.py --owner <O> --repo <R> --pr-number <N>
+            ```
+      - [ ] dirty → Fix (spawn `clean-coder`) → reply → resolve threads → push → return to Step 4
+      - [ ] clean (no findings) → `copilot_clean_at = current_head` → gate (b)
+      - [ ] no review yet → gate (b)
+
+      **(b) Mergeability re-check**
+      ```
+      pull_request_read(method="get") → .mergeable_state, .mergeable
+      ```
+      - [ ] mergeable → gate (c)
+      - [ ] not mergeable → rebase → push → return to Step 1
+
+      **(c) Request Copilot review**
+      - [ ] Check for pending Copilot review:
+            ```
+            python ~/.claude/skills/pr-converge/scripts/check_pending_reviews.py --owner <O> --repo <R> --pr-number <N>
+              → filter by copilot user
+            ```
+      - [ ] Pending review already exists → skip request → gate (d)
+      - [ ] No pending review → request:
+            ```
+            gh api --method POST repos/<O>/<R>/pulls/<N>/requested_reviewers \
+              -f 'reviewers[]=copilot-pull-request-reviewer[bot]'
+            ```
+      - [ ] `phase = COPILOT_WAIT` → schedule 360s wakeup → return to Step 6a next tick
+
+      **(d) Thread resolution — author-agnostic, outdated-agnostic**
+      ```
+      pull_request_read(method="get_review_comments")
+        → count threads where is_resolved == false
+      ```
+      - [ ] zero unresolved → gate (e)
+      - [ ] unresolved → For each: verify against HEAD;
+            still applies → Fix (spawn `clean-coder`) → reply → resolve;
+            no longer applies → reply-with-note → resolve.
+            Push if code changed → return to Step 4
+
+      **(e) Mark ready**
+      - [ ] Run automated convergence check:
+            ```
+            python $HOME/.claude/skills/pr-converge/scripts/check_convergence.py \
+              --owner <O> --repo <R> --pr-number <N>
+            ```
+      - [ ] Exit 0 (all pass) → `update_pull_request(draft=false)` → advance to Step 7
+      - [ ] Exit 1 (FAIL lines) → address each failure → return to Step 4
+      - [ ] Exit 2 (gh error) → retry once; persistent → stop
+
+- [ ] **Step 6a: COPILOT_WAIT — fetch Copilot, decide**
+      See: [`reference/per-tick.md` § Step 2 COPILOT_WAIT](reference/per-tick.md)
+
+      Fetch Copilot reviews + inline comments on `current_head`.
+
+      - [ ] **clean (no findings)** →
+            `copilot_clean_at = current_head` → return to Step 6 (re-validate gates b, d, e)
+      - [ ] **dirty (findings present)** →
+            - [ ] Fix each finding (spawn `clean-coder`)
+            - [ ] Reply to each finding comment via `python ~/.claude/skills/pr-converge/scripts/post_fix_reply.py`
+            - [ ] Resolve each addressed thread via `pull_request_review_write(method="resolve_thread")`
+            - [ ] Push → `phase = BUGBOT` → return to Step 4
+      - [ ] **no review yet** →
+            increment `copilot_wait_count` → ≥ 3 = hard blocker → stop
+            schedule 360s wakeup → return to Step 6a next tick
+
+- [ ] **Step 7: Clean working tree**
+      See: [`bugteam/reference/teardown-publish-permissions.md` § Step 4](../../bugteam/reference/teardown-publish-permissions.md)
+
+- [ ] **Step 8: Rewrite PR description**
+      See: [`bugteam/reference/teardown-publish-permissions.md` § Step 4.5](../../bugteam/reference/teardown-publish-permissions.md)
 
-## First tick of a session
+- [ ] **Step 9: Revoke project permissions**
+      `python "$HOME/.claude/skills/bugteam/scripts/revoke_project_claude_permissions.py"`
 
-Read [`reference/state-schema.md`](reference/state-schema.md),
-[`reference/ground-rules.md`](reference/ground-rules.md), then
-[`reference/per-tick.md`](reference/per-tick.md).
+- [ ] **Step 10: Print final report**
+      ```
+      /pr-converge exit: converged
+      Loops: <N>
+      Final commit: <SHA>
+      ```
 
-## Match situation, read spoke
+## Edge cases
 
 | Situation | Read |
 |---|---|
-| Starting any tick | [`reference/per-tick.md`](reference/per-tick.md) |
-| Bugbot or audit finding to fix and push | [`reference/fix-protocol.md`](reference/fix-protocol.md) |
-| Bugteam reports `convergence (zero findings)` AND `bugbot_clean_at == current_head` | [`reference/convergence-gates.md`](reference/convergence-gates.md) |
-| Multi-PR session — `state.json` exists at `<TMPDIR>/pr-converge-<session_id>/` | [`reference/multi-pr-orchestration.md`](reference/multi-pr-orchestration.md) |
-| Scheduling the next wakeup | [`workflows/schedule-wakeup-loop.md`](workflows/schedule-wakeup-loop.md) |
-| Hard blocker, convergence reached, or user stops loop | [`reference/stop-conditions.md`](reference/stop-conditions.md) |
-| All GitHub interactions use `plugin:github:github` MCP tools | [`reference/per-tick.md`](reference/per-tick.md) |
-| Tick is ambiguous against the spokes above | [`reference/examples.md`](reference/examples.md) |
+| Multi-PR session (`state.json` exists) | [`reference/multi-pr-orchestration.md`](reference/multi-pr-orchestration.md) |
+| Hard blocker or user stops loop | [`reference/stop-conditions.md`](reference/stop-conditions.md) |
+| Tick is ambiguous against the steps above | [`reference/examples.md`](reference/examples.md) |
 
 ## Folder map
 

package/skills/pr-converge/config/constants.py

@@ -0,0 +1,63 @@
+"""Constants for the pr-converge skill.
+
+All runtime and API constants live here. Script-specific constants
+(CLI args, markdown patterns, reflow settings) stay in
+``scripts/config/pr_converge_constants.py``, which imports from here.
+"""
+
+CURSOR_BOT_LOGIN = "cursor[bot]"
+CURSOR_LOGIN_FILTER_SUBSTRING = "cursor"
+COPILOT_REVIEWER_LOGIN = "copilot-pull-request-reviewer[bot]"
+COPILOT_COMMENT_LOGIN = "Copilot"
+COPILOT_REVIEWER_REQUEST_ID = COPILOT_REVIEWER_LOGIN
+COPILOT_LOGIN_FILTER_SUBSTRING = "copilot"
+CLAUDE_REVIEWER_LOGIN = "claude[bot]"
+CLAUDE_REVIEWER_REQUEST_ID = CLAUDE_REVIEWER_LOGIN
+CLAUDE_LOGIN_FILTER_SUBSTRING = "claude"
+
+ALL_COPILOT_CLEAN_REVIEW_STATES = ("APPROVED", "COMMENTED")
+ALL_COPILOT_DIRTY_REVIEW_STATES = ("CHANGES_REQUESTED",)
+COPILOT_SOFT_DIRTY_REVIEW_STATE = "COMMENTED"
+ALL_CLAUDE_CLEAN_REVIEW_STATES = ("APPROVED",)
+ALL_CLAUDE_DIRTY_REVIEW_STATES = ("CHANGES_REQUESTED", "COMMENTED")
+CLAUDE_SOFT_DIRTY_REVIEW_STATE = "COMMENTED"
+
+BUGBOT_DIRTY_BODY_REGEX = (
+    r"Cursor Bugbot has reviewed your changes and found \d+ potential issue"
+)
+BUGBOT_CHECK_RUN_NAME_SUBSTRING = "bugbot"
+ALL_BUGBOT_CHECK_RUN_ACTIVE_STATUSES = ("queued", "in_progress")
+BUGBOT_CHECK_RUN_COMPLETED_STATUS = "completed"
+ALL_BUGBOT_CHECK_RUN_COMPLETE_CONCLUSIONS = ("success", "neutral")
+BUGBOT_RUN_TRIGGER_PHRASE = "bugbot run\n"
+BUGBOT_RUN_TRIGGER_WAIT_SECONDS = 8
+
+GH_INLINE_COMMENTS_PATH_TEMPLATE = "repos/{owner}/{repo}/pulls/{number}/comments"
+GH_REVIEW_COMMENTS_PATH_TEMPLATE = (
+    "repos/{owner}/{repo}/pulls/{number}/reviews/{review_id}/comments"
+)
+GH_REVIEWS_PATH_TEMPLATE = "repos/{owner}/{repo}/pulls/{number}/reviews"
+GH_CHECK_RUNS_PATH_TEMPLATE = "repos/{owner}/{repo}/commits/{sha}/check-runs"
+GH_INLINE_COMMENT_CREATE_PATH_TEMPLATE = (
+    "repos/{owner}/{repo}/pulls/{number}/comments"
+)
+GH_INLINE_COMMENT_REPLY_PATH_TEMPLATE = (
+    "repos/{owner}/{repo}/pulls/{number}/comments/{comment_id}/replies"
+)
+GH_ISSUE_COMMENT_CREATE_PATH_TEMPLATE = (
+    "repos/{owner}/{repo}/issues/{number}/comments"
+)
+GH_PR_OBJECT_PATH_TEMPLATE = "repos/{owner}/{repo}/pulls/{number}"
+GH_REQUESTED_REVIEWERS_PATH_TEMPLATE = (
+    "repos/{owner}/{repo}/pulls/{number}/requested_reviewers"
+)
+GH_REQUESTED_REVIEWERS_FIELD_TEMPLATE = "reviewers[]={reviewer_id}"
+
+CHECK_RUNS_PER_PAGE = 20
+REVIEWS_PER_PAGE = 100
+
+GRAPHQL_REVIEW_THREADS_PAGE_SIZE = 100
+UNRESOLVED_THREAD_DETAIL_MAX = 5
+
+EXIT_CODE_GH_ERROR = 2
+EXIT_CODE_NOT_FOUND = 1