claude-dev-env 2.12.0 → 2.14.0

package/skills/pr-converge/pr_converge_skill_constants/AGENTS.md

@@ -0,0 +1,26 @@
+# pr_converge_skill_constants
+
+Importable Python constants module for the `pr-converge` skill. Script-specific constants (CLI args, markdown patterns, reflow settings) live in `scripts/pr_converge_scripts_constants/` and import from here.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `__init__.py` | Package marker |
+| `constants.py` | All runtime and API constants: bot logins, review states, GH API path templates, bugbot/bugteam detection patterns, exit codes |
+
+## Exported constants (selected)
+
+| Constant | Purpose |
+|---|---|
+| `CURSOR_BOT_LOGIN` | Login string for the Cursor bugbot reviewer |
+| `COPILOT_REVIEWER_LOGIN` | Login string for the Copilot reviewer bot |
+| `ALL_COPILOT_CLEAN_REVIEW_STATES` | Tuple of review states that count as clean for Copilot |
+| `BUGBOT_DIRTY_BODY_REGEX` | Regex that matches a bugbot review body reporting findings |
+| `GH_REVIEWS_PATH_TEMPLATE` | `gh api` path template for PR reviews |
+| `GH_INLINE_COMMENTS_PATH_TEMPLATE` | `gh api` path template for PR inline comments |
+
+## Conventions
+
+- All path templates use `str.format(**kwargs)` with keys `owner`, `repo`, `number`.
+- `packages/claude-dev-env/skills/pr-converge/scripts/pr_converge_scripts_constants/pr_converge_constants.py` re-exports everything here via `from pr_converge_skill_constants.constants import ...` so scripts can import from either location.

package/skills/pr-converge/pr_converge_skill_constants/CLAUDE.md

@@ -1,26 +1 @@
-# pr_converge_skill_constants
-
-Importable Python constants module for the `pr-converge` skill. Script-specific constants (CLI args, markdown patterns, reflow settings) live in `scripts/pr_converge_scripts_constants/` and import from here.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `__init__.py` | Package marker |
-| `constants.py` | All runtime and API constants: bot logins, review states, GH API path templates, bugbot/bugteam detection patterns, exit codes |
-
-## Exported constants (selected)
-
-| Constant | Purpose |
-|---|---|
-| `CURSOR_BOT_LOGIN` | Login string for the Cursor bugbot reviewer |
-| `COPILOT_REVIEWER_LOGIN` | Login string for the Copilot reviewer bot |
-| `ALL_COPILOT_CLEAN_REVIEW_STATES` | Tuple of review states that count as clean for Copilot |
-| `BUGBOT_DIRTY_BODY_REGEX` | Regex that matches a bugbot review body reporting findings |
-| `GH_REVIEWS_PATH_TEMPLATE` | `gh api` path template for PR reviews |
-| `GH_INLINE_COMMENTS_PATH_TEMPLATE` | `gh api` path template for PR inline comments |
-
-## Conventions
-
-- All path templates use `str.format(**kwargs)` with keys `owner`, `repo`, `number`.
-- `packages/claude-dev-env/skills/pr-converge/scripts/pr_converge_scripts_constants/pr_converge_constants.py` re-exports everything here via `from pr_converge_skill_constants.constants import ...` so scripts can import from either location.
+@AGENTS.md

package/skills/pr-converge/reference/AGENTS.md

@@ -0,0 +1,28 @@
+# pr-converge/reference
+
+Reference documents for the `pr-converge` skill. These files define the per-tick step sequence, convergence gates, fix protocol, stop conditions, state schema, multi-PR orchestration, and examples.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `progress-checklist.md` | The per-tick eleven-step checklist (Step 0 open → Step 11 report), each step pointing to its spoke file |
+| `per-tick.md` | Step-by-step procedure for one tick (resolve HEAD, run the internal CODE_REVIEW and BUGTEAM phases, then the terminal BUGBOT and COPILOT_WAIT gates, schedule next wakeup) |
+| `convergence-gates.md` | Six gates that must all pass before the PR is marked ready for review |
+| `fix-protocol.md` | pr-converge deltas on the `pr-fix-protocol` skill: multi-PR teammate obligations and the same-tick bugbot re-trigger rule |
+| `ground-rules.md` | Non-negotiable constraints for the convergence loop |
+| `stop-conditions.md` | Conditions that end the loop without convergence (cap reached, stuck, user stop) |
+| `state-schema.md` | Fields in `pr-converge-state.json` and their meanings |
+| `multi-pr-orchestration.md` | How to run the loop across multiple PRs in parallel |
+| `examples.md` | Worked examples of tick sequences |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `obstacles/` | Per-obstacle runbooks for known failure modes in the convergence loop |
+
+## Conventions
+
+- `per-tick.md` is the primary reference loaded during each tick. The pacing workflow lives in `../workflows/schedule-wakeup-loop.md`.
+- Every gate in `convergence-gates.md` must produce evidence before the next gate runs.

package/skills/pr-converge/reference/CLAUDE.md

@@ -1,28 +1 @@
-# pr-converge/reference
-
-Reference documents for the `pr-converge` skill. These files define the per-tick step sequence, convergence gates, fix protocol, stop conditions, state schema, multi-PR orchestration, and examples.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `progress-checklist.md` | The per-tick eleven-step checklist (Step 0 open → Step 11 report), each step pointing to its spoke file |
-| `per-tick.md` | Step-by-step procedure for one tick (resolve HEAD, run the internal CODE_REVIEW and BUGTEAM phases, then the terminal BUGBOT and COPILOT_WAIT gates, schedule next wakeup) |
-| `convergence-gates.md` | Six gates that must all pass before the PR is marked ready for review |
-| `fix-protocol.md` | pr-converge deltas on the `pr-fix-protocol` skill: multi-PR teammate obligations and the same-tick bugbot re-trigger rule |
-| `ground-rules.md` | Non-negotiable constraints for the convergence loop |
-| `stop-conditions.md` | Conditions that end the loop without convergence (cap reached, stuck, user stop) |
-| `state-schema.md` | Fields in `pr-converge-state.json` and their meanings |
-| `multi-pr-orchestration.md` | How to run the loop across multiple PRs in parallel |
-| `examples.md` | Worked examples of tick sequences |
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `obstacles/` | Per-obstacle runbooks for known failure modes in the convergence loop |
-
-## Conventions
-
-- `per-tick.md` is the primary reference loaded during each tick. The pacing workflow lives in `../workflows/schedule-wakeup-loop.md`.
-- Every gate in `convergence-gates.md` must produce evidence before the next gate runs.
+@AGENTS.md

package/skills/pr-converge/reference/obstacles/AGENTS.md

@@ -0,0 +1,23 @@
+# pr-converge/reference/obstacles
+
+Per-obstacle runbooks for known failure modes in the `pr-converge` convergence loop. Each file covers one specific obstacle: what causes it, how to detect it, and how to recover.
+
+## Files
+
+| File | Obstacle |
+|---|---|
+| `fix-post-replies.md` | Posting inline review replies fails or posts to the wrong thread |
+| `fix-publish-summary.md` | Publishing the bugteam summary comment fails |
+| `fix-push.md` | `git push` fails during a fix commit |
+| `fix-read-filelines.md` | Reading file line ranges for a fix fails |
+| `fix-reset-state.md` | State JSON becomes corrupt or inconsistent between ticks |
+| `fix-resolve-threads.md` | Resolving inline comment threads via GraphQL fails |
+| `fix-spawn-clean-coder.md` | Spawning the `clean-coder` subagent fails or produces no output |
+| `fix-stage-commit.md` | Staging or committing a fix fails |
+| `fix-trigger-bugbot.md` | Triggering Cursor Bugbot via an issue comment fails |
+| `fix-write-test.md` | Writing a failing test before a fix fails |
+
+## Conventions
+
+- Each runbook is loaded on demand when the convergence loop hits that specific obstacle.
+- Runbooks do not overlap with `per-tick.md`; they cover edge cases and recovery paths that fall outside the normal tick flow.

package/skills/pr-converge/reference/obstacles/CLAUDE.md

@@ -1,23 +1 @@
-# pr-converge/reference/obstacles
-
-Per-obstacle runbooks for known failure modes in the `pr-converge` convergence loop. Each file covers one specific obstacle: what causes it, how to detect it, and how to recover.
-
-## Files
-
-| File | Obstacle |
-|---|---|
-| `fix-post-replies.md` | Posting inline review replies fails or posts to the wrong thread |
-| `fix-publish-summary.md` | Publishing the bugteam summary comment fails |
-| `fix-push.md` | `git push` fails during a fix commit |
-| `fix-read-filelines.md` | Reading file line ranges for a fix fails |
-| `fix-reset-state.md` | State JSON becomes corrupt or inconsistent between ticks |
-| `fix-resolve-threads.md` | Resolving inline comment threads via GraphQL fails |
-| `fix-spawn-clean-coder.md` | Spawning the `clean-coder` subagent fails or produces no output |
-| `fix-stage-commit.md` | Staging or committing a fix fails |
-| `fix-trigger-bugbot.md` | Triggering Cursor Bugbot via an issue comment fails |
-| `fix-write-test.md` | Writing a failing test before a fix fails |
-
-## Conventions
-
-- Each runbook is loaded on demand when the convergence loop hits that specific obstacle.
-- Runbooks do not overlap with `per-tick.md`; they cover edge cases and recovery paths that fall outside the normal tick flow.
+@AGENTS.md

package/skills/pr-converge/reference/progress-checklist.md

@@ -70,7 +70,7 @@ round as converged. This rule holds every tick, every loop, every PR.
       - [ ] **clean on `current_head`** → zero unresolved threads (else fix + resolve first)
             → `bugbot_clean_at = current_head` → Step 7
       - [ ] **no review / commit_id mismatch** → `reviewer-gates` Bugbot flow (Gate 3):
-            silent pass → stamp + Step 7; queued/triggered → 360s wakeup → Step 4;
+            silent pass → Step 7; queued/triggered → 360s wakeup → Step 4;
             down → `bugbot_down = true` → Step 7
 
 - [ ] **Step 5: CODE-REVIEW — static sweep, review, fix, advance**
@@ -110,9 +110,10 @@ round as converged. This rule holds every tick, every loop, every PR.
       See: [`per-tick.md` § Step 2 BUGTEAM](per-tick.md);
       [`../../bugteam/SKILL.md`](../../bugteam/SKILL.md).
       Pre-condition: `code_review_clean_at == current_head`.
-      Mandatory: `Skill({skill: "bugteam", args: "<PR URL>"})` this tick
-      (enforcer-blocked otherwise; `qbug` is not a substitute). Scope: FULL
-      `origin/main...HEAD` diff. Re-resolve HEAD after bugteam.
+      Mandatory: `Skill({skill: "bugteam", args: "<PR URL>"})` this tick.
+      Use the [review guide](../../reviews/SKILL.md#review-workflow) for its
+      judgment. `qbug` is not a substitute. Scope: FULL `origin/main...HEAD`
+      diff. Re-resolve HEAD after bugteam.
 
       - [ ] **bugteam pushed** → verify threads replied + resolved → reset markers
             → `phase = CODE_REVIEW` → 360s wakeup → Step 5
@@ -129,7 +130,7 @@ round as converged. This rule holds every tick, every loop, every PR.
       before these gates run. Count unresolved threads before each gate.
       Every gate records evidence; gate (f) cites evidence from (a)–(e).
 
-      - [ ] **(a) Copilot findings** — fetch Copilot on `current_head`; dirty → fix + return to Step 5; clean → stamp `copilot_clean_at`; absent → continue; when `copilot_down`, skip
+      - [ ] **(a) Copilot findings** — fetch Copilot on `current_head`; dirty → fix + return to Step 5; clean → record `copilot_clean_at`; absent → continue; when `copilot_down`, skip
       - [ ] **(b) Claude reviewer** — fetch Claude on `current_head`; dirty → fix + return to Step 5; clean or absent → continue
       - [ ] **(c) Mergeability** — `mergeable_state == "clean"` and `mergeable == true`; dirty → rebase + return to Step 1; blocked/behind/unknown/unstable → hard blocker
       - [ ] **(d) Post-convergence Copilot request** — request Copilot when not pending and not `copilot_down`; enter `COPILOT_WAIT` (Step 7a); when `copilot_down`, skip to (e)

package/skills/pr-converge/reference/state-schema.md

@@ -13,10 +13,7 @@ Single-PR `/pr-converge` writes loop state to
 `$CLAUDE_JOB_DIR/pr-converge-state.json`; that file is the source of truth
 for `phase`, heads, counters, status. Multi-PR mode additionally maintains
 `<TMPDIR>/pr-converge-<session_id>/state.json` for orchestrator coordination
-across PRs. Both files share most of the fields below; the
-`bugteam_skill_invoked_at_head` and `bugteam_skill_invoked_at_tick` fields
-live ONLY in the single-PR `$CLAUDE_JOB_DIR/pr-converge-state.json` file
-(see those field entries below for details).
+across PRs. Both files share the fields below.
 
 ## Fields
 
@@ -94,29 +91,6 @@ live ONLY in the single-PR `$CLAUDE_JOB_DIR/pr-converge-state.json` file
   (c) reads this field to decide between "schedule next wakeup" and
   "escalate to bugbot-down".
 - `tick_count`: integer, init `0`. Increment every tick.
-- `bugteam_skill_invoked_at_head`: HEAD SHA (string) at which the formal
-  `Skill({skill: "bugteam"})` was last invoked, or `null`. Stamped by the
-  `pr_converge_bugteam_skill_tracker` hook on every formal bugteam Skill
-  invocation. **On-disk location:** the tracker writes this field to
-  `$CLAUDE_JOB_DIR/pr-converge-state.json` (single-PR mode); it is NOT
-  mirrored into the multi-PR `<TMPDIR>/pr-converge-<session_id>/state.json`
-  file. Operators inspecting these stamps must read the single-PR
-  `pr-converge-state.json` under `$CLAUDE_JOB_DIR`. Reset by overwrite on
-  the next bugteam Skill invocation; staleness is detected by the head/tick
-  equality check rather than by explicit reset. The
-  `pr_converge_bugteam_enforcer` hook reads this field together with
-  `current_head` to confirm the formal Skill registered at the current HEAD
-  before allowing follow-on clean-coder audit-shaped Agent spawns. `qbug`
-  invocations deliberately do NOT update this field.
-- `bugteam_skill_invoked_at_tick`: integer tick number at which the formal
-  bugteam Skill was last invoked, or `null`. Companion to
-  `bugteam_skill_invoked_at_head` and persisted to the same
-  `$CLAUDE_JOB_DIR/pr-converge-state.json` file (single-PR mode only).
-  Reset by overwrite on the next bugteam Skill invocation; staleness is
-  detected by the head/tick equality check rather than by explicit reset.
-  The enforcer requires this value to equal the current `tick_count` so a
-  Skill invocation from a prior tick cannot wave through clean-coder
-  audit-shaped Agent spawns on a later tick at the same HEAD.
 - `agents_session_id`: string or `null`, init `null`. The session id that
   spawned the persistent per-step agents recorded in `persistent_agents`.
   On tick entry, compare it to the current session id: when they differ,

package/skills/pr-converge/scripts/AGENTS.md

@@ -0,0 +1,46 @@
+# pr-converge/scripts
+
+Python helper scripts for the `pr-converge` skill, plus their tests and a PowerShell/AutoHotkey toolset for advancing Cursor agents.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `check_bugbot_ci.py` | Checks bugbot CI check-run status on a given SHA |
+| `check_convergence.py` | Evaluates whether all convergence gates pass on the current HEAD |
+| `check_convergence_availability.py` | Resolves reviewer waivers from flag, disk-authoritative settings (env fallback), and the availability/quota probe, with waived / enforced / probe_error_reason states |
+| `check_convergence_gates.py` | GitHub REST leaf checks (review and Bugbot) the convergence gates call |
+| `check_convergence_thread_gates.py` | GitHub GraphQL and REST leaf checks (review threads and pending reviewers) the convergence gates call |
+| `check_pending_reviews.py` | Fetches pending review requests and reviewer states |
+| `fetch_copilot_reviews.py` | Fetches Copilot reviewer reviews filtered to the current HEAD |
+| `post_fix_reply.py` | Posts an inline reply to a review comment thread |
+| `reflow_skill_md.py` | Reformats `SKILL.md` to enforce a line width limit |
+| `README.md` | MCP tool reference for PR operations used by the scripts |
+| `_pr_converge_path_setup.py` | Adds the scripts directory to `sys.path` for direct script imports |
+| `conftest.py` | Puts the scripts directory on `sys.path` so pytest collects the suite |
+| `test_check_bugbot_ci.py` | Tests for `check_bugbot_ci.py` |
+| `test_check_convergence.py` | Tests for `check_convergence.py` |
+| `test_check_convergence_availability.py` | Tests for `check_convergence_availability.py` |
+| `test_check_convergence_contract.py` | Contract pins for `check_convergence.py` gate wiring |
+| `test_check_convergence_gates.py` | Tests for `check_convergence_gates.py` |
+| `test_check_convergence_thread_gates.py` | Tests for `check_convergence_thread_gates.py` |
+| `test__pr_converge_path_setup.py` | Tests for `_pr_converge_path_setup.py` |
+| `test_cursor_agents_continue.py` | Tests for the cursor-agents-continue toolset |
+| `test_reflow_skill_md.py` | Tests for `reflow_skill_md.py` |
+| `caller-window-pid.ps1` | Gets the PID of the calling terminal window |
+| `cursor-agents-continue.ahk` | AutoHotkey script to advance Cursor agent prompts |
+| `cursor-agents-continue.cmd` | CMD wrapper for the AHK script |
+| `cursor-agents-continue-stop-others.ps1` | Stops other Cursor agents before advancing one |
+| `cursor-agents-continue-caller.cmd` | Caller-side CMD wrapper |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `pr_converge_scripts_constants/` | Script-specific constants (re-exports skill constants plus adds reflow/CLI constants) |
+
+## Conventions
+
+- Scripts import constants from `pr_converge_scripts_constants.pr_converge_constants`, which re-exports everything from `pr_converge_skill_constants.constants`.
+- Run scripts as `python ~/.claude/skills/pr-converge/scripts/<script>.py --owner <O> --repo <R> --pr-number <N>`.
+- The `reflow_skill_md.py` script targets `SKILL.md` in the parent skill directory (resolved via `TARGET_SKILL_PATH` in `pr_converge_scripts_constants/reflow_skill_md_constants.py`).

package/skills/pr-converge/scripts/CLAUDE.md

@@ -1,46 +1 @@
-# pr-converge/scripts
-
-Python helper scripts for the `pr-converge` skill, plus their tests and a PowerShell/AutoHotkey toolset for advancing Cursor agents.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `check_bugbot_ci.py` | Checks bugbot CI check-run status on a given SHA |
-| `check_convergence.py` | Evaluates whether all convergence gates pass on the current HEAD |
-| `check_convergence_availability.py` | Resolves reviewer waivers from flag, disk-authoritative settings (env fallback), and the availability/quota probe, with waived / enforced / probe_error_reason states |
-| `check_convergence_gates.py` | GitHub REST leaf checks (review and Bugbot) the convergence gates call |
-| `check_convergence_thread_gates.py` | GitHub GraphQL and REST leaf checks (review threads and pending reviewers) the convergence gates call |
-| `check_pending_reviews.py` | Fetches pending review requests and reviewer states |
-| `fetch_copilot_reviews.py` | Fetches Copilot reviewer reviews filtered to the current HEAD |
-| `post_fix_reply.py` | Posts an inline reply to a review comment thread |
-| `reflow_skill_md.py` | Reformats `SKILL.md` to enforce a line width limit |
-| `README.md` | MCP tool reference for PR operations used by the scripts |
-| `_pr_converge_path_setup.py` | Adds the scripts directory to `sys.path` for direct script imports |
-| `conftest.py` | Puts the scripts directory on `sys.path` so pytest collects the suite |
-| `test_check_bugbot_ci.py` | Tests for `check_bugbot_ci.py` |
-| `test_check_convergence.py` | Tests for `check_convergence.py` |
-| `test_check_convergence_availability.py` | Tests for `check_convergence_availability.py` |
-| `test_check_convergence_contract.py` | Contract pins for `check_convergence.py` gate wiring |
-| `test_check_convergence_gates.py` | Tests for `check_convergence_gates.py` |
-| `test_check_convergence_thread_gates.py` | Tests for `check_convergence_thread_gates.py` |
-| `test__pr_converge_path_setup.py` | Tests for `_pr_converge_path_setup.py` |
-| `test_cursor_agents_continue.py` | Tests for the cursor-agents-continue toolset |
-| `test_reflow_skill_md.py` | Tests for `reflow_skill_md.py` |
-| `caller-window-pid.ps1` | Gets the PID of the calling terminal window |
-| `cursor-agents-continue.ahk` | AutoHotkey script to advance Cursor agent prompts |
-| `cursor-agents-continue.cmd` | CMD wrapper for the AHK script |
-| `cursor-agents-continue-stop-others.ps1` | Stops other Cursor agents before advancing one |
-| `cursor-agents-continue-caller.cmd` | Caller-side CMD wrapper |
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `pr_converge_scripts_constants/` | Script-specific constants (re-exports skill constants plus adds reflow/CLI constants) |
-
-## Conventions
-
-- Scripts import constants from `pr_converge_scripts_constants.pr_converge_constants`, which re-exports everything from `pr_converge_skill_constants.constants`.
-- Run scripts as `python ~/.claude/skills/pr-converge/scripts/<script>.py --owner <O> --repo <R> --pr-number <N>`.
-- The `reflow_skill_md.py` script targets `SKILL.md` in the parent skill directory (resolved via `TARGET_SKILL_PATH` in `pr_converge_scripts_constants/reflow_skill_md_constants.py`).
+@AGENTS.md

package/skills/pr-converge/scripts/pr_converge_scripts_constants/AGENTS.md

@@ -0,0 +1,18 @@
+# pr_converge_scripts_constants
+
+Constants module for the `pr-converge` skill's Python scripts. Re-exports all runtime/API constants from the skill-level module and adds script-specific constants for CLI arguments, markdown patterns, and reflow settings.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `__init__.py` | Package marker |
+| `pr_converge_constants.py` | Re-exports all constants from `pr_converge_skill_constants.constants` plus adds script-specific values |
+| `reflow_skill_md_constants.py` | Constants for `reflow_skill_md.py`: line width limit, list item patterns, `TARGET_SKILL_PATH` |
+| `convergence_gate_constants.py` | Constants for `check_convergence_gates.py`: short-SHA length, join separators, and the review-threads GraphQL query |
+
+## Conventions
+
+- `pr_converge_constants.py` uses `from pr_converge_skill_constants.constants import ...` (with `# noqa: F401`) to re-export everything so script files can import from one location.
+- `reflow_skill_md_constants.py` resolves `TARGET_SKILL_PATH` from its own `__file__` path, pointing to `SKILL.md` three directories up.
+- Script-specific regex patterns (ordered list items, bullet list items, unfinished markdown link targets, markdown reference definitions) live in `reflow_skill_md_constants.py`.

package/skills/pr-converge/scripts/pr_converge_scripts_constants/CLAUDE.md

@@ -1,18 +1 @@
-# pr_converge_scripts_constants
-
-Constants module for the `pr-converge` skill's Python scripts. Re-exports all runtime/API constants from the skill-level module and adds script-specific constants for CLI arguments, markdown patterns, and reflow settings.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `__init__.py` | Package marker |
-| `pr_converge_constants.py` | Re-exports all constants from `pr_converge_skill_constants.constants` plus adds script-specific values |
-| `reflow_skill_md_constants.py` | Constants for `reflow_skill_md.py`: line width limit, list item patterns, `TARGET_SKILL_PATH` |
-| `convergence_gate_constants.py` | Constants for `check_convergence_gates.py`: short-SHA length, join separators, and the review-threads GraphQL query |
-
-## Conventions
-
-- `pr_converge_constants.py` uses `from pr_converge_skill_constants.constants import ...` (with `# noqa: F401`) to re-export everything so script files can import from one location.
-- `reflow_skill_md_constants.py` resolves `TARGET_SKILL_PATH` from its own `__file__` path, pointing to `SKILL.md` three directories up.
-- Script-specific regex patterns (ordered list items, bullet list items, unfinished markdown link targets, markdown reference definitions) live in `reflow_skill_md_constants.py`.
+@AGENTS.md

package/skills/pr-converge/workflows/AGENTS.md

@@ -0,0 +1,16 @@
+# pr-converge/workflows
+
+Pacing workflow specification for the `pr-converge` loop.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `schedule-wakeup-loop.md` | Specifies `ScheduleWakeup` call parameters, delays, and stop/convergence conditions for each tick |
+
+## Conventions
+
+- `per-tick.md` (in `../reference/`) references this file for Step 4 (schedule next wakeup). Read it before running Step 4.
+- Default delay: `delaySeconds: 360`. Exception: BUGBOT inline-lag branch uses `delaySeconds: 90`.
+- On convergence or a hard stop condition, omit the `ScheduleWakeup` call entirely.
+- The `reason` field in each `ScheduleWakeup` call names what is being awaited, including the current `phase` and `bugbot_clean_at` SHA when set.

package/skills/pr-converge/workflows/CLAUDE.md

@@ -1,16 +1 @@
-# pr-converge/workflows
-
-Pacing workflow specification for the `pr-converge` loop.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `schedule-wakeup-loop.md` | Specifies `ScheduleWakeup` call parameters, delays, and stop/convergence conditions for each tick |
-
-## Conventions
-
-- `per-tick.md` (in `../reference/`) references this file for Step 4 (schedule next wakeup). Read it before running Step 4.
-- Default delay: `delaySeconds: 360`. Exception: BUGBOT inline-lag branch uses `delaySeconds: 90`.
-- On convergence or a hard stop condition, omit the `ScheduleWakeup` call entirely.
-- The `reason` field in each `ScheduleWakeup` call names what is being awaited, including the current `phase` and `bugbot_clean_at` SHA when set.
+@AGENTS.md

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

@@ -89,7 +89,7 @@ Skip the `gh api copilot_internal/user` quota read; treat Copilot quota as unkno
 The `gh`-text hooks read risk from literal `gh ...` command text, and an MCP post carries none, so those checks go quiet in cloud. Before each MCP post, check by hand:
 
 - No volatile scratch path in a post body (job dirs, temp roots, worktrees).
-- A proof-of-work comment carries all five parts the proof standard names.
+- Review comments follow the [comment guide](../comments/SKILL.md#writing-useful-review-comments).
 - A PR title follows Conventional Commits.
 - Markdown bodies go through the structured `body` parameter so backticks show as formatting.
 

package/skills/pr-loop-cloud-transport/reference/identity-and-hooks.md

@@ -26,14 +26,14 @@ Author-keyed logic accounts for the split: a self-PR check keys on the login tha
 
 ## Hooks that still gate a cloud run
 
-The commit and push gates read git commands, which a cloud run still issues through Bash, so they fire normally and the run follows them: `verified_commit_gate`, `session_edit_stage_gate`, `block_main_commit`, `precommit_code_rules_gate`, `test_preflight_check`, and the pre-push base-ref check that needs `origin/HEAD` set (SKILL.md Step 2).
+The commit and push gates read git commands, which a cloud run still issues through Bash, so they fire normally and the run follows them: `session_edit_stage_gate`, `block_main_commit`, `precommit_code_rules_gate`, `test_preflight_check`, and the pre-push base-ref check that needs `origin/HEAD` set (SKILL.md Step 2).
 
 ## Hooks that go quiet on the MCP path
 
-The `gh`-text hooks read risk from literal `gh ...` command text: `pr_description_enforcer`, `gh_body_arg_blocker`, `conventional_pr_title_gate`, `gh_pr_author_enforcer`, the `gh` branch of `volatile_path_in_post_blocker`, and the `gh pr ready` branch of `convergence_gate_blocker`. An MCP post carries no `gh` text, so these checks see nothing to gate while the settings matchers name only the local tool prefix. The run covers the gap by hand before each MCP post — the Step 6 self-check in SKILL.md:
+The `gh`-text hooks read risk from literal `gh ...` command text: `gh_body_arg_blocker`, `conventional_pr_title_gate`, `gh_pr_author_enforcer`, and the `gh` branch of `volatile_path_in_post_blocker`. An MCP post carries no `gh` text, so these checks see nothing to gate while the settings matchers name only the local tool prefix. The run covers the gap by hand before each MCP post — the Step 6 self-check in SKILL.md:
 
 - No volatile scratch path in a post body (job dirs, temp roots, worktrees).
-- A proof-of-work comment carries all five parts the proof standard names.
+- Review comments follow the [review guide](../../reviews/SKILL.md#review-workflow).
 - A PR title follows Conventional Commits.
 - Markdown bodies go through the structured `body` parameter so backticks show as formatting.
 

package/skills/pr-loop-lifecycle/SKILL.md

@@ -44,7 +44,7 @@ Run these in order from the lead session on EVERY exit — converged, cap reache
    ```
    Tolerates already-removed worktrees and missing directories; removal is Windows-safe per `~/.claude/rules/windows-filesystem-safe.md`.
 3. **Clean the working tree.** Return to the session worktree, remove run-scoped scratch files, and leave `git status` clean of run artifacts.
-4. **Rewrite the PR description.** Follow [`reference/teardown-publish-permissions.md` § Publish the final PR description](reference/teardown-publish-permissions.md): capture the cumulative diff and original body, compose the new body directly against `docs/PR_DESCRIPTION_GUIDE.md`, publish via `update_pull_request`, remove the scratch files. On failure, report it and continue — the revoke still runs.
+4. **Update the PR description.** Follow [`reference/teardown-publish-permissions.md` § Publish the final PR description](reference/teardown-publish-permissions.md): capture the cumulative diff and original body, compose it against the [description guide](../descriptions/SKILL.md#required-content), publish via `update_pull_request`, then remove the scratch files.
 5. **Revoke project permissions (always):**
    `python "$HOME/.claude/_shared/pr-loop/scripts/revoke_project_claude_permissions.py"`
    Non-negotiable, including on error exits: leaving the grant in place lets future sessions inherit elevated `.claude/**` access without an explicit opt-in. Run revoke even when earlier close steps partially failed; log cleanup errors separately.

package/skills/pr-loop-lifecycle/reference/teardown-publish-permissions.md

@@ -35,7 +35,7 @@ When the run exits (any reason), run these steps in order from **this** session
 
 After teardown and before permission revoke, the lead rewrites the PR body to the PR's **final cumulative state** — what the change delivers, not the loop's process. This is the **only** PR-write the lead performs (audit and fix comments stay with the agents that produced them).
 
-The lead composes the body text directly against `docs/PR_DESCRIPTION_GUIDE.md` — no agent spawn — so the body passes the `pr_description_enforcer` hook's style audit on the `gh pr edit` that follows.
+The lead composes the body against the [description guide](../../descriptions/SKILL.md#required-content) and publishes it through the GitHub client.
 
 **Steps:**
 

package/skills/prototype/SKILL.md

@@ -10,8 +10,8 @@ description: >-
 
 Give a build the freedom to move fast, then make it earn the right to ship. Two phases, one hard wall between them:
 
-- **Sandbox** — an isolated worktree where an agent runs under `claude --bare`, so none of the standards gates (TDD, code rules, verified-commit, plain-language, stage) fire. The agent builds a proof-of-concept with zero friction.
-- **Promotion** — back in the normal, fully-hooked session, the successful POC goes through a clean-room re-verification before it becomes a commit and a pull request. Nothing from the sandbox rides along un-checked.
+- **Sandbox** — an isolated worktree where an agent runs under `claude --bare`, so the normal TDD, code-rules, plain-language, and stage hooks do not run. The agent builds a proof-of-concept with zero friction.
+- **Promotion** — back in the normal, fully-hooked session, the successful POC receives clean-room review and verification under the [review guide](../reviews/SKILL.md#review-workflow) before it becomes a commit and a pull request.
 
 Two safety gates stay live even in the sandbox: personal-data blocking and destructive-command blocking. A worktree shares the real repo's `.git` store and `rm` reaches the whole disk, so these are containment, not the "delays" the sandbox is meant to shed.
 
@@ -45,7 +45,7 @@ Follow `workflows/sandbox.md`. In short:
 
 ### Phase 2 — Promotion
 
-Run only in the normal, fully-hooked session — never inside the sandbox. Follow `workflows/promotion.md`, which drives the clean-room task seeds in `reference/promotion-tasks.md`: fresh branch off live `origin/main`, POC content as an uncommitted diff, cleanup and privacy sweep, `code-verifier` in a fresh context, then `/commit` and a draft PR handed to a PR-loop skill. State the two honest limitations from `reference/honest-limitations.md`.
+Run only in the normal, fully-hooked session — never inside the sandbox. Follow `workflows/promotion.md`, which drives the clean-room task seeds in `reference/promotion-tasks.md`: fresh branch off live `origin/main`, POC content as an uncommitted diff, cleanup and privacy sweep, review and verification under the [review guide](../reviews/SKILL.md#review-workflow), then `/commit` and a draft PR handed to a PR-loop skill. State the two honest limitations from `reference/honest-limitations.md`.
 
 ## Task seeding
 
@@ -57,7 +57,7 @@ At the start of Phase 2, register every item in `reference/promotion-tasks.md` a
 |---|---|---|---|
 | `fresh-branch` | Sandbox step 1; Promotion step 2 | isolated worktree JSON (`worktree_path`, `base_commit`, `repo_root`) | Refuse — see refusal cases |
 | `privacy-hygiene` | Promotion step 5 | personal-data and secret sweep of the diff | Warn; do a manual review before continuing |
-| `code-verifier` (agent) | Promotion step 6 | fresh-context verdict against the real diff; mints the commit-gate verdict | Stop; the commit gate will block anyway |
+| [Review guide](../reviews/SKILL.md#review-workflow) | Promotion step 6 | review and verification of the real diff | Stop and report the incomplete promotion |
 | `/commit` (command) | Promotion step 7 | conventional commit + push | Commit and push by hand per `git-workflow` |
 | `autoconverge` (default; `pr-converge` or `bugteam` as alternatives) | Promotion step 9 | the PR converged to ready | Stop after the draft PR; tell the user to converge manually |
 

package/skills/prototype/reference/honest-limitations.md

@@ -6,11 +6,11 @@ State both of these to the user, in these terms, whenever a proof-of-concept is
 
 `code_rules_enforcer` is a Write/Edit gate: it checks content as it is written. Prototype code is built under `--bare`, so that gate never fired, and content brought into promotion as a git diff (apply, checkout, cherry-pick) does not pass through it either.
 
-Standards re-engage on promotion through three surfaces that stand in for the write-time hook:
+Promotion records the controls applied to the real diff:
 
-- the `code-verifier` agent, in a fresh context, deriving and running the named gates against the real diff;
+- review and verification under the [review guide](../../reviews/SKILL.md#review-workflow);
 - the `privacy-hygiene` sweep for personal data and secrets;
-- the pull-request review (AGENTS.md criteria and any PR-loop reviewers).
+- the pull-request review criteria and any PR-loop reviewers.
 
 Say plainly: the write-time rule engine did not see this code; the verifier and review are what cover it.
 
@@ -18,6 +18,6 @@ Say plainly: the write-time rule engine did not see this code; the verifier and
 
 The sandbox agent wrote code first and tests, if any, after. Red-green-refactor ordering did not happen. So the honest claim on promoted prototype code is exactly this, and nothing more:
 
-> code-verifier passed, privacy swept, review passed — TDD ordering waived.
+> Review and verification completed, privacy swept — TDD ordering waived.
 
-Do not claim red-green compliance on these lines. A prototype is a reference build, not a test-first build. Fred Brooks: plan to throw one away. Promotion re-verifies the code and often rewrites it to standard; expect real work in the verifier repair loop, not a rubber stamp.
+Do not claim red-green compliance on these lines. A prototype is a reference build, not a test-first build. Promotion reviews and verifies the code against the current standards.

package/skills/prototype/reference/promotion-tasks.md

@@ -14,9 +14,9 @@ Promotion runs in the **normal, fully-hooked session** — never inside the `--b
 
 5. **Privacy sweep.** Run the `privacy-hygiene` skill over the full applied working tree, not only the diff — a POC that pulled live data can leave a secret in a file the diff view hides. Evidence: its clean report, or the leak it found and how it was removed. If the skill is missing, do a manual PII and secret review and say so.
 
-6. **Verify in a fresh context.** Spawn the `code-verifier` agent against the real diff. Expect findings and a repair loop — the code was un-TDD'd. Evidence: the verifier's clean verdict, and a note of what it made you fix. Do not skip this on the belief that the sandbox agent already tested it.
+6. **Review and verify the real diff.** Apply the [review guide](../../reviews/SKILL.md#review-workflow). Evidence: the checks run and each required finding repaired. Do not rely on sandbox testing as promotion evidence.
 
-7. **Commit and open a draft PR.** Only on a clean verdict, run `/commit` (which mints the commit-gate verdict and pushes), then open a draft PR per the `git-workflow` rule. Evidence: the commit hash and the PR URL.
+7. **Commit and open a draft PR.** After the review and verification record is complete, run `/commit`, then open a draft PR per the `git-workflow` rule. Evidence: the commit hash and the PR URL.
 
 8. **State the honest limitations.** Post the two statements from `reference/honest-limitations.md` — write-time rules never ran; TDD ordering waived — in the PR body or to the user. Evidence: the text was included.
 

package/skills/prototype/workflows/promotion.md

@@ -4,7 +4,7 @@ Turn a successful proof-of-concept into a real, verified change. Run every step
 
 ## Seed the task list first
 
-Register every item in `reference/promotion-tasks.md` as a session task (`TaskCreate`, or `TodoWrite` if that is the host tool). Work only from the task list. Mark each complete with evidence — a command result, a path, a verdict, or a skill's return.
+Register every item in `reference/promotion-tasks.md` as a session task (`TaskCreate`, or `TodoWrite` if that is the host tool). Work only from the task list. Mark each complete with evidence — a command result, a path, a review record, or a skill's return.
 
 ## The clean-room protocol
 
@@ -15,13 +15,11 @@ The task seeds carry the full ordered detail. The shape:
 3. **Bring content as an uncommitted diff.** Copy the POC's file changes into the new branch's working tree. Do not cherry-pick or merge the sandbox commits; the sandbox history stays behind.
 4. **Cleanup.** Remove scratch files, debug dumps, and temp helpers the POC created (`cleanup-temp-files` rule).
 5. **Privacy sweep** via `privacy-hygiene` over the diff.
-6. **Verify** with the `code-verifier` agent — `model: sonnet`, worker-model routing per [`skills/orchestrator/SKILL.md`](../../orchestrator/SKILL.md#workflow-agent-routing); resolver-supplied sonnet-equivalent on third-party hosts — in a fresh context. This is where standards re-engage. Expect findings and a repair loop — the POC was un-TDD'd.
-7. **Commit and PR.** Only on a clean verdict, run `/commit`, then open a draft PR per the `git-workflow` rule.
+6. **Review and verify** the real diff against the [review guide](../../reviews/SKILL.md#review-workflow). Record the checks run and repair every required finding.
+7. **Commit and PR.** After the review and verification record is complete, run `/commit`, then open a draft PR per the `git-workflow` rule.
 8. **State the honest limitations** from `reference/honest-limitations.md` in the PR body or to the user.
 9. **Converge** by handing the PR to `autoconverge` by default; use `pr-converge` for paced ticks or `bugteam` for an open-loop audit.
 
 ## Why the clean room, not a push
 
-`code_rules_enforcer` is a write-time Write/Edit gate. Content that lands through `git apply`, `git checkout`, or cherry-pick never passes through it, so pushing the sandbox branch would ship code the rule engine never saw, carrying sandbox scratch along with it. Standards re-engage through the `code-verifier` agent, the `privacy-hygiene` sweep, and the PR review — not through a write-time hook. Steps 4-6 are hard gates: the honest claim on promoted POC code is code-verifier-passed, privacy-swept, review-passed, with TDD ordering waived.
-
-The `verified_commit_gate` hook is the backstop under all of this — it refuses a commit or push with no minted verdict — but the clean-room steps are the mechanism, not the gate firing.
+`code_rules_enforcer` is a write-time Write/Edit gate. Content that lands through `git apply`, `git checkout`, or cherry-pick receives the clean-room controls in steps 4–6: cleanup, privacy review, and review and verification under the [review guide](../../reviews/SKILL.md#review-workflow). The promotion record states the checks run and the remaining TDD limitation.

package/skills/rebase/AGENTS.md

@@ -0,0 +1,32 @@
+# rebase
+
+Rebase a branch onto its base ref with verification gates that catch logically broken results before pushing.
+
+**Trigger:** `/rebase`, "rebase this branch", "PR has merge conflicts", "rebase onto main", force-push to update remote branch history.
+
+## Purpose
+
+The default failure mode for a rebase is shipping code that compiled but does not run. This skill prevents that by running real import checks, test collection, and symbol scans after every rebase — not just syntax validation.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — four phases (pre-rebase analysis, during rebase, verification gates, push). No companion files. |
+
+## Four phases
+
+| Phase | Key actions |
+|---|---|
+| 1 — Pre-rebase analysis | Resolve base via `gh pr view`, classify scenario (stacked/squash/long-lived), fetch fresh, scan commit messages for deleted/renamed symbols |
+| 2 — During rebase | Verify `--skip` with a diff, audit auto-merged files with `git diff --name-only --diff-filter=M ORIG_HEAD` |
+| 3 — Verification gates | `python -m compileall`, `pytest --collect-only -q`, targeted test run, reference scan for removals |
+| 4 — Push | Explicit authorization required; `--force-with-lease=<branch>:<sha>` only; verify mergeability after push |
+
+## Conventions
+
+- Force-push requires explicit operator authorization every time — auto mode does not bypass this.
+- `--force-with-lease=<branch>:<sha>` only; bare `--force` is refused.
+- Never force-push `main`, `master`, `release/*`, `production`, or any multi-author branch.
+- Symbol scans prefer Serena (`find_referencing_symbols`) then the Grep tool, then shell grep as a last resort.
+- `ORIG_HEAD` is the correct ref for auto-merged file audits mid-rebase; `HEAD@{1}` shifts per step.