claude-dev-env 1.94.0 → 2.0.0

package/skills/pr-fix-protocol/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: pr-fix-protocol
+description: >-
+  Applies reviewer findings to a PR as verified fixes and drives unresolved
+  review threads to zero. Invoked by PR-loop orchestrators (pr-converge,
+  autoconverge, bugteam, qbug, copilot-review) when a reviewer reports
+  findings; not for ad-hoc 'fix this bug' requests outside a PR loop.
+---
+
+# PR Fix Protocol
+
+**Core principle:** a finding is addressed only when the fix is pushed, the thread carries a reply, and the thread is resolved — as one unit of work. Anything short of all three leaves a convergence gate stalled.
+
+## How callers invoke this
+
+- **Skill-capable contexts** (a lead session that holds the `Skill` tool): `Skill({skill: "pr-fix-protocol", args: "--skill <caller> --pr <URL> --worktree <path> [findings payload or 'sweep']"})`.
+- **Fallback** (a subagent or teammate without the `Skill` tool): the caller's spawn prompt says to read `~/.claude/skills/pr-fix-protocol/SKILL.md` and apply it with the parameters below.
+
+The caller passes: its identity, the PR scope, the PR worktree path, this round's findings (or `sweep` for a thread sweep with no fresh findings), and its post-push obligations — which clean-SHA state fields to reset and which reviewers to re-trigger.
+
+## Executor choice
+
+- **Single-PR loops** (no shared `state.json`): the lead spawns `Agent(subagent_type: "clean-coder")` to write the fix. Stop when `Agent` is unavailable. A spawned clean-coder starts in its own working directory, so its prompt names the PR worktree path and directs it to edit, stage, and commit there.
+- **Multi-PR orchestration** (shared `state.json`): a per-PR clean-coder teammate owns edits, replies, and state writes; the orchestrator holds back from inline edits. The teammate obligations — reply before writing state, which state fields to set, idle handoff — live in the calling skill's multi-PR reference.
+
+Run every git command in the PR worktree. `git add`, `git commit`, and `git push` act on the repo of the current working directory, so a cross-repo PR's fix lands in the PR's repo only when the working directory is its worktree.
+
+## The fix sequence
+
+Follow the shared 13-step sequence in [`_shared/pr-loop/fix-protocol.md`](../../_shared/pr-loop/fix-protocol.md) exactly: read each file:line, capture the pre-fix SHA and contents, write a failing test first where the finding has behavior, apply the fix narrowly, `py_compile`, run the post-fix self-audit, stage by explicit path, make one commit, fast-forward push, then reply and resolve atomically per thread. Its Constraints section — narrow scope, keep the commit hooks, preserve helpers — binds every executor.
+
+**Reply transport:** the GitHub MCP `add_reply_to_pull_request_comment` is primary. For a script-only context or a multi-PR teammate, the fallback is `python "$HOME/.claude/skills/pr-converge/scripts/post_fix_reply.py" --owner <O> --repo <R> --pr-number <N> --in-reply-to <COMMENT_ID> --body "Fixed in <SHA> — <what changed>"`. Both carry the body shape from [`_shared/pr-loop/audit-reply-template.md`](../../_shared/pr-loop/audit-reply-template.md). For a body-only finding with no inline thread, post a top-level review reply that cites the new HEAD SHA.
+
+**Thread resolution:** call `pull_request_review_write(method="resolve_thread", threadId=<PRRT node id>)` right after each reply. Harvest the thread node ids (`PRRT_…`) from `get_review_comments` at fetch time.
+
+## The unresolved-thread sweep (hard gate)
+
+A caller advances a phase, records a clean SHA, or marks a PR ready only when the PR carries zero unresolved review threads.
+
+```
+pull_request_read(method="get_review_comments") → filter threads where is_resolved == false
+```
+
+- The filter is purely `is_resolved == false`. Author, anchor commit, and `is_outdated` play no part in the count.
+- `is_outdated` is informational, not a skip flag. GitHub marks a thread outdated when its anchor line changes, yet the concern can still apply to current HEAD — the fix may have moved rather than landed. Verify each outdated thread against current HEAD like any other.
+- Per unresolved thread: verify the concern against current HEAD. The concern holds → fix (this protocol) → reply → resolve. The concern does not hold on current HEAD → reply with a note that explains why → resolve.
+- Code changed during the sweep → push and hand control back to the caller's re-entry phase. Only resolutions and no code → re-run the sweep and keep the caller's state.
+
+## Post-push obligations
+
+Every push through this protocol:
+
+1. Re-resolve `current_head` — `git rev-parse HEAD` locally, and the PR `get` call for API-visible state.
+2. Reset the caller-named clean-SHA fields to null (`bugbot_clean_at`, `code_review_clean_at`, `copilot_clean_at` — whichever the caller tracks). A new HEAD invalidates every prior clean.
+3. Re-trigger reviewers per the caller's parameter — for Cursor Bugbot the `reviewer-gates` Bugbot flow, for Copilot the caller's request step. Audit-family callers (`bugteam`, `qbug`) skip re-triggering, since their next loop iteration is the reviewer.
+
+## Gotchas
+
+- **Reply, then resolve, atomic per thread.** Batching every reply ahead of any resolve, or yielding to the orchestrator between the two, leaves threads half-addressed when a run dies mid-loop.
+- **An unchanged HEAD after step 11 means no commit landed.** Exit `stuck — could not address findings` rather than report the findings as fixed.
+- **A resolved thread with no reply reads as dismissed.** Reviewers and the humans reading the PR need the one-paragraph explanation the template carries.
+
+## Folder map
+
+- `SKILL.md` — this file. The step sequence, reply template, and payload shapes live in `_shared/pr-loop/` (`fix-protocol.md`, `audit-reply-template.md`, `gh-payloads.md`); the reply fallback script lives in `pr-converge/scripts/`.

package/skills/pr-loop-cloud-transport/SKILL.md

@@ -20,6 +20,8 @@ Three checks, in order; the first failure routes to the cloud transport:
 
 A read-scoped account passes checks 1 and 2 and fails check 3 — the PR-loop skills push fix commits, so `push: false` means the local path stalls at its first push while the MCP transport carries the run.
 
+GitHub MCP substitution covers `gh` operations only. It does not make Claude-only slash commands (for example `/code-review`) runnable. Those steps go through the chain-spawn helper documented in [`worker-spawn.md`](../../_shared/pr-loop/worker-spawn.md#code-review-host-routing) (`detect_host_profile` + `invoke_code_review`). Transport (`gh` vs MCP) and harness (Claude vs third-party) are separate axes.
+
 ## Cloud transport workflow
 
 Copy this checklist and check off items as you complete them:

package/skills/reviewer-gates/SKILL.md

@@ -20,23 +20,24 @@ Every invocation carries the caller's identity (`--skill <caller>`, e.g. `pr-con
 
 ## Gate 1: Reviewer opt-out (`CLAUDE_REVIEWS_DISABLED`)
 
-The `CLAUDE_REVIEWS_DISABLED` environment variable is a comma-separated token list (case-insensitive, whitespace-tolerant). Three tokens exist:
+The `CLAUDE_REVIEWS_DISABLED` environment variable is a comma-separated token list (case-insensitive, whitespace-tolerant). Four tokens exist:
 
 | Token | Disables |
 |---|---|
 | `bugteam` | The whole bug-audit family: `/bugteam`, `/qbug`, `/findbugs`, and audit dispatch in `/monitor-open-prs` |
 | `bugbot` | Cursor Bugbot triggering and polling |
 | `copilot` | GitHub Copilot review requests and polling |
+| `codex` | Codex reviewer requests and polling |
 
 Cursor Bugbot is off by default: it runs only when `CLAUDE_REVIEWS_ENABLED` lists `bugbot`, and a `bugbot` token in `CLAUDE_REVIEWS_DISABLED` keeps it off even when the opt-in lists it.
 
 Run the shared parser — never an inline shell parse:
 
 ```bash
-python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer <bugbot|bugteam|copilot>
+python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer <bugbot|bugteam|copilot|codex>
 ```
 
-- **Exit 0** — the named reviewer is disabled for this run (opted out, or, for Bugbot, off by default without the `CLAUDE_REVIEWS_ENABLED` opt-in). A skill whose whole run depends on that reviewer responds with its refusal line and stops. A copilot- or bugteam-dependent caller names the opt-out: `/<caller> is disabled via CLAUDE_REVIEWS_DISABLED.` A Bugbot-dependent caller off by default names the opt-in the run needs: `/<caller> is disabled: Cursor Bugbot needs a bugbot token in CLAUDE_REVIEWS_ENABLED.` A loop that merely includes the reviewer as one gate marks the reviewer down (`bugbot_down = true`, `copilot_down = true`) and continues on its remaining signals.
+- **Exit 0** — the named reviewer is disabled for this run (opted out, or, for Bugbot, off by default without the `CLAUDE_REVIEWS_ENABLED` opt-in). A skill whose whole run depends on that reviewer responds with its refusal line and stops. A copilot- or bugteam-dependent caller names the opt-out: `/<caller> is disabled via CLAUDE_REVIEWS_DISABLED.` A Bugbot-dependent caller off by default names the opt-in the run needs: `/<caller> is disabled: Cursor Bugbot needs a bugbot token in CLAUDE_REVIEWS_ENABLED.` A loop that merely includes the reviewer as one gate marks the reviewer down (`bugbot_down = true`, `copilot_down = true`, `codex_down = true`) and continues on its remaining signals.
 - **Exit 1** — the reviewer is available; continue.
 
 ## Gate 2: Copilot quota pre-check (once per run)
@@ -93,11 +94,12 @@ When a reviewer is down, `check_convergence.py` must skip that reviewer's gate s
 |---|---|---|
 | Bugbot down or off | `--bugbot-down` | `bugbot` |
 | Copilot down or opted out | `--copilot-down` | `copilot` |
+| Codex down or opted out | `--codex-down` | `codex` |
 | Bugteam CLEAN post blocked | `--bugteam-post-blocked` | `bugteam` |
 
-The caller passes the flag on its own `check_convergence.py` run. The flag alone does not reach the independent mark-ready blocker hook, which re-runs `check_convergence.py` with no flags on `gh pr ready`. Each flag also honors its token: `check_convergence.py` reads the same bypass from `CLAUDE_REVIEWS_DISABLED`. So export the matching token in the same shell before `gh pr ready`, and the hook's no-flag re-check inherits the bypass through the env. Combine tokens with commas when more than one reviewer is down (`CLAUDE_REVIEWS_DISABLED="copilot,bugteam"`).
+The caller passes the flag on its own `check_convergence.py` run. The flag alone does not reach the independent mark-ready blocker hook, which re-runs `check_convergence.py` with no flags on `gh pr ready`. Each flag also honors its token: `check_convergence.py` reads the same bypass from `CLAUDE_REVIEWS_DISABLED`. So export the matching token in the same shell before `gh pr ready`, and the hook's no-flag re-check inherits the bypass through the env. Combine tokens with commas when more than one reviewer is down (`CLAUDE_REVIEWS_DISABLED="copilot,bugteam,codex"`).
 
-The `bugteam` token here means the bugteam CLEAN-review gate is skipped for this convergence check. It does not disable the bugbot or copilot gates: each token is scoped to its own reviewer.
+The `bugteam` token here means the bugteam CLEAN-review gate is skipped for this convergence check. It does not disable the bugbot, copilot, or codex gates: each token is scoped to its own reviewer.
 
 ## Gotchas
 

package/skills/skill-builder/references/skill-modularity.md

@@ -84,7 +84,7 @@ In Process or a dedicated **Sub-skills** section:
 
 | Skill | When | Produces |
 |---|---|---|
-| `/pr-scope-resolve` | Step 1 — resolve the PR target | owner, repo, PR number, head ref |
+| `/reviewer-gates` | Step 1 — gate external reviewers | opt-out, Copilot quota, Bugbot trigger decisions |
 | `/skill-writer` | Step 4 — author SKILL.md | skill package files |
 
 If a listed skill is not installed, respond: `[exact refusal or degrade line]`.

package/skills/team-advisor/SKILL.md

@@ -17,7 +17,7 @@ One warm, addressable advisor available at the strongest model tier the session
 
 **Detect the host profile first** (Host profiles in
 [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)
-— e.g. `ADVISOR_HOST_PROFILE` or `GROK_BUILD`). Do not start a model-floor
+— e.g. `ADVISOR_HOST_PROFILE` or `THIRD_PARTY`). Do not start a model-floor
 walk until the host is known.
 
 This session is the shared advisor's sole consumer, so its model floor is
@@ -29,21 +29,25 @@ the CLI fallback — using `team-advisor-agent` as the name and this session as
 the only consumer (skip the "who you are and your assignment" opener in each
 consult; a single-consumer session doesn't need it).
 
-**Grok host:** use the self-as-advisor path in the shared protocol: this
-session answers ENDORSE / CORRECTION / PLAN / STOP itself. Do not spawn a
-Claude `session-advisor` subagent and do not walk the Claude multi-tier
-ladder.
+**Third-party host:** bind a max-tier Claude advisor through the shared CLI Claude-chain
+in the protocol (Fable max, then Opus max; `claude_chain_runner.py` walks
+`~/.claude/claude-chain.json` for account usage failover). Consult via
+`--resume <session_id>` on that bind. This session is the sole consumer of that
+CLI advisor; skip the multi-consumer opener. When the chain cannot bind or
+reply, fail closed and report to the user — do **not** answer ENDORSE /
+CORRECTION / PLAN / STOP as this third-party session.
 
 ## Constraints
 
-- One `team-advisor-agent` per session, owned by this session for its whole
-  lifecycle (spawn, drift-respawn, shutdown) — see
+- One advisor bind per session (`team-advisor-agent` on Claude; one CLI
+  `session_id` on a third-party host), owned by this session for its whole lifecycle
+  (spawn or CLI bind, drift re-bind, shutdown) — see
   [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md).
-- Never spawn the warm agent, or its CLI fallback, at a tier below this
-  session's own tier.
-- The warm agent (or its CLI equivalent) only answers. It never edits a
-  file, never runs a build or test, and never posts anything on the
-  session's behalf.
+- Never bind the advisor, or its CLI path, at a tier below the protocol floor
+  for this host (Claude: this session's own tier; a third-party host: Opus floor
+  with Fable first).
+- The advisor only answers. It never edits a file, never runs a build or
+  test, and never posts anything on the session's behalf.
 
 ## File Index
 

package/system-prompts/software-engineer.xml

@@ -140,7 +140,8 @@
   Apply an outside-in BDD reasoning protocol before writing any code. Outside-in BDD is the
   required development protocol; apply it in place of any Red-Green-Refactor heuristic. The
   full anti-pattern catalog, Example Mapping algorithm, and solo-developer guidance live in
-  the bdd-protocol skill; this section carries the core four-phase sequence.
+  the long-form BDD references (`~/.claude/docs/BDD_DISCOVERY_PROTOCOL.md`,
+  `~/.claude/docs/BDD_SCENARIO_QUALITY.md`); this section carries the core four-phase sequence.
 
   Deliberate Discovery. Before writing any specification or code, reason explicitly about
   what the code should do, what constraints apply, and what concrete examples demonstrate the
@@ -159,8 +160,9 @@
   it pass. Assess each green state for structural improvement; refactor when a specific
   naming, cohesion, or duplication problem is identified.
 
-  Reference the bdd-protocol skill for Smart and Molak §7.6 patterns, the Example Mapping
-  algorithm, and guidance on applying this protocol in a solo-developer context.
+  Reference `~/.claude/docs/BDD_SCENARIO_QUALITY.md` and `~/.claude/docs/BDD_DISCOVERY_PROTOCOL.md`
+  for Smart and Molak §7.6 patterns, the Example Mapping algorithm, and guidance on applying this
+  protocol in a solo-developer context.
 </behavior_protocol>
 
 <scope_discipline>
@@ -231,11 +233,10 @@
 </agent_workflow>
 
 <code_review_response>
-  When responding to GitHub PR review feedback, follow this mandatory protocol using the
-  pr-review-responder skill.
+  When responding to GitHub PR review feedback, follow this mandatory protocol.
 
   Fetch all reviewer comments before making any fixes. Obtain the full comment set from the
-  PR using `gh pr view --comments` or the pr-review-responder skill.
+  PR using `gh pr view --comments`.
 
   Create a TodoWrite checklist with one item per comment.
 

package/hooks/validators/test_verify_paths.py

@@ -1,32 +0,0 @@
-"""Tests for validator path verification script."""
-
-import pytest
-
-from .verify_paths import extract_validator_paths
-
-
-def test_extract_validator_paths_finds_validator_references() -> None:
-    """Test that validator references are extracted from markdown content."""
-    content = """
-    **Validator:** `validators/import_checks.py`
-    Some text here.
-    **Validator:** `validators/style_checks.py`
-    """
-
-    result = extract_validator_paths(content)
-
-    assert "import_checks.py" in result
-    assert "style_checks.py" in result
-
-
-def test_extract_validator_paths_deduplicates() -> None:
-    """Test that duplicate validator references are deduplicated."""
-    content = """
-    **Validator:** `validators/import_checks.py`
-    **Validator:** `validators/import_checks.py`
-    **Validator:** `validators/import_checks.py`
-    """
-
-    result = extract_validator_paths(content)
-
-    assert result.count("import_checks.py") == 1

package/hooks/validators/verify_paths.py

@@ -1,57 +0,0 @@
-"""Verify all validator paths referenced in SKILL.md exist."""
-
-import re
-import sys
-from pathlib import Path
-
-
-SKILL_MD_PATH = Path(__file__).parent.parent.parent / "skills" / "pr-review-responder" / "SKILL.md"
-VALIDATORS_DIR = Path(__file__).parent
-
-
-def extract_validator_paths(content: str) -> list[str]:
-    """Extract validator file paths from SKILL.md content."""
-    pattern = r"validators[/\\](\w+\.py)"
-    matches = re.findall(pattern, content)
-    return list(set(matches))
-
-
-def verify_validators() -> int:
-    """Verify all referenced validators exist.
-
-    Returns:
-        Exit code: 0 if all exist, 1 if any missing
-    """
-    if not SKILL_MD_PATH.exists():
-        print(f"ERROR: SKILL.md not found at {SKILL_MD_PATH}")
-        return 1
-
-    content = SKILL_MD_PATH.read_text(encoding="utf-8")
-    referenced_validators = extract_validator_paths(content)
-
-    print(f"Found {len(referenced_validators)} validator references in SKILL.md")
-    print()
-
-    missing = []
-    for validator_file in sorted(referenced_validators):
-        validator_path = VALIDATORS_DIR / validator_file
-        if validator_path.exists():
-            print(f"  [OK] {validator_file}")
-        else:
-            print(f"  [MISSING] {validator_file}")
-            missing.append(validator_file)
-
-    print()
-
-    if missing:
-        print(f"ERROR: {len(missing)} validator(s) missing:")
-        for validator_file in missing:
-            print(f"  - {validator_file}")
-        return 1
-
-    print("All referenced validators exist.")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(verify_validators())