claude-dev-env 2.0.2 → 2.1.0

package/skills/autoconverge/reference/CLAUDE.md

@@ -7,6 +7,7 @@ Reference documentation for the `autoconverge` skill. The `converge.mjs` workflo
 | File | Role |
 |---|---|
 | `convergence.md` | Round shape: the static sweep, the three parallel internal lenses (code-review, bug-audit, self-review), deduplication, the fix commit step, the terminal Bugbot, Copilot, and Codex gates, and the definition of a clean convergence. |
+| `copilot-findings.md` | The Copilot gate tiering, per-finding verification, and the `userReview` return contract. |
 | `stop-conditions.md` | Every condition that ends the run short of ready: budget cap, iteration cap, blocker exit, static-sweep stall, Bugbot, Copilot, and Codex bypass. |
 | `gotchas.md` | Hard-won lessons from failed runs: PR title validation, conflicting PRs, worktree branch lock, resumed sessions rerooting, and minter issues. |
 | `closing-report.md` | The closing HTML convergence report the teardown step builds and publishes: data source, build steps, publishing. |

package/skills/autoconverge/reference/copilot-findings.md

@@ -0,0 +1,51 @@
+# Copilot findings — tier, verify, then route
+
+How the autoconverge Copilot gate handles each finding. The hub
+([`../SKILL.md`](../SKILL.md)) points here; the orchestrating session's
+user-review hold runs the [`copilot-finding-triage`](../../copilot-finding-triage/SKILL.md)
+skill.
+
+The Copilot gate tiers each finding: a **self-healing** finding (style, type
+hints, imports, formatting, magic-value extraction, test-only or doc-vs-code
+fixes — nothing that changes observable runtime behavior) flows into the fix
+round with no user notification. A **code-concern** finding (logic, security,
+data handling, error-handling semantics, concurrency — the tier whenever in
+doubt) goes to a verification stage before any routing.
+
+Each code-concern finding gets its own verifier agent, all in parallel, inside
+the workflow. A verdict is conclusive only when an actual check ran: the verifier
+executes a command against the flagged HEAD — running the code path with crafted
+inputs, forcing the claimed error condition, or running a purpose-built test —
+and captures its output. The verdict carries
+`{ verdict, checkCommand, checkOutput, evidence }`; a conclusive verdict with an
+empty `checkCommand` or `checkOutput` downgrades to inconclusive.
+
+- **confirmed** — the check reproduces the defect. The finding becomes
+  self-healing: it joins the fix round carrying its repro, and the fix re-runs
+  that same check, adds a regression test where the suite covers the surface,
+  lands in one commit, pushes, and replies on the thread with the fix SHA and the
+  before/after output. No page.
+- **refuted** — the check shows the code already behaves correctly in the exact
+  scenario the finding claims is broken. The workflow replies on the thread with
+  the command and output, resolves it, and counts it clean. No page.
+- **inconclusive** — everything else, and the verifier's default: no runnable
+  check exists, the check is infeasible here, the results are ambiguous, or the
+  fix needs a product decision. Any doubt sorts here. Only inconclusive findings
+  page the user.
+
+A round whose code concerns all confirm or refute never returns
+`blocker: "user-review"`. On one or more inconclusive findings, the workflow
+stops with `converged: false`, `blocker: "user-review"`, and a `userReview`
+field carrying
+`{ reviewUrl, findings: [{ file, line, severity, tier, title, evidence }] }` —
+`evidence` is the verifier's one-line note stating what check was attempted and
+why it was not decisive.
+
+A background workflow cannot hold for a human, so the wait belongs to the
+orchestrating session. On a `blocker: "user-review"` return, run the
+[`copilot-finding-triage`](../../copilot-finding-triage/SKILL.md) skill: send the
+ntfy notification (the per-finding summary and evidence note plus the `reviewUrl`
+Copilot review link), then hold with a 45-minute `ScheduleWakeup` for the user's
+response. When the user answers within the window, follow their direction. When
+the window closes with no response, run normal teardown and report the
+inconclusive findings un-reviewed.

package/skills/closeout/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: closeout
 description: >-
-  Harvests session obstacles into GitHub issues backed by quoted evidence at
-  session end, validates each draft with the user, dedupes against open and
-  closed issues, routes each to its repo, files children then a parent
-  checklist, and prints a computed cloud handoff prompt. Triggers: /closeout,
-  close out this session, close out the session, file the session obstacles,
-  session closeout, harvest session obstacles, end-of-session issue filing.
-  Near-miss: not session-log, which journals the session to the vault; closeout
-  files GitHub issues and prints a handoff prompt, and writes no session
-  journal.
+  Harvests session obstacles into GitHub issues backed by quoted evidence:
+  validates each draft with the user, dedupes against open and closed issues,
+  files children under a parent checklist, and prints a cloud handoff prompt.
+  Triggers: /closeout, close out this session, close out the session, file the
+  session obstacles, session closeout, harvest session obstacles, end-of-session
+  issue filing. Not session-log (vault journal) — closeout files issues and
+  writes no journal.
 ---
 
 # Closeout

package/skills/copilot-finding-triage/SKILL.md

@@ -1,13 +1,11 @@
 ---
 name: copilot-finding-triage
 description: >-
-  Sorts each Copilot gate finding from a converge run into one of two tiers, then
-  verifies each code concern with an executed check before routing it: a
-  self-healing finding is auto-fixed, pushed, and counted toward convergence with
-  no user page; a confirmed or refuted code concern is handled by the run with its
-  check evidence; only a code concern the check leaves inconclusive pages the user
-  over ntfy and holds the run behind a 45-minute gate. Triggers: 'copilot finding
-  triage', 'user review gate', 'tier copilot findings', 'triage the copilot gate'.
+  Tiers each Copilot gate finding from a converge run, verifies each code concern
+  with an executed check, then routes it — auto-fix a self-healing finding,
+  resolve a refuted one, page the user only for an inconclusive one. Triggers:
+  'copilot finding triage', 'user review gate', 'tier copilot findings', 'triage
+  the copilot gate'.
 ---
 
 # Copilot Finding Triage

package/skills/copilot-review/CLAUDE.md

@@ -6,11 +6,12 @@ Spawns a background subagent that polls the GitHub Copilot reviewer on the curre
 
 The main session gathers PR context (number, HEAD SHA, owner/repo, branch), spawns a self-terminating background subagent with a fully filled-in prompt, and returns control at once. The subagent loops on a 6-minute `ScheduleWakeup` cadence: fetch Copilot's latest review, TDD-fix any inline findings, push a commit, reply inline, resolve each addressed thread, re-request review. It stops on convergence, a persistent blocker, `TaskStop`, three consecutive ticks with no Copilot review at the current HEAD, or after 20 ticks.
 
-## Key file
+## Key files
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Four-step orchestration (opt-out check, gather PR context, spawn subagent, report to user), the verbatim subagent prompt template with all placeholders, fix protocol, stop conditions, and ground rules (one commit per tick, honor hooks, preserve draft state, use `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix). |
+| `SKILL.md` | Four-step orchestration (opt-out check, gather PR context, spawn subagent, report to user), fix protocol, stop conditions, and ground rules (one commit per tick, honor hooks, preserve draft state, use `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix). |
+| `templates/subagent-prompt.md` | The background watcher prompt Step 3 passes to the subagent word for word, with placeholders for PR number, owner, repo, branch, and HEAD SHA. |
 
 ## Environment opt-out
 

package/skills/copilot-review/SKILL.md

@@ -1,155 +1,119 @@
----
-name: copilot-review
-description: >-
-  Spawns a background subagent that babysits the GitHub Copilot reviewer on the
-  current PR: each tick it fixes unaddressed findings against HEAD, re-requests
-  review, and exits on convergence. Triggers: '/copilot-review', 'watch
-  copilot', 'babysit copilot review', 'keep re-requesting copilot'.
----
-
-# Copilot Review
-
-Delegates Copilot babysitting to a background subagent so the main session stays free. The subagent loops internally and closes itself on convergence.
-
-## Transport check (before any GitHub step)
-
-Run `command -v gh`; when it succeeds, run `gh auth status`; once the PR scope is resolved, run `gh api repos/<owner>/<repo> --jq .permissions.push` and take `true` as the pass. When any check fails, run the `pr-loop-cloud-transport` skill first, route every `gh` operation in this skill through its substitution matrix, and carry the same routing into the subagent prompt so the spawned watcher inherits it.
-
-## When this skill applies
-
-The user is on a PR branch, wants Copilot (the GitHub Copilot reviewer bot) to keep re-reviewing after each push, and wants findings auto-addressed between ticks — but does not want the main conversation consumed by polling.
-
-## The Process
-
-### Step 0: Opt-out check
-
-Before any other work, run:
-
-```bash
-python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer copilot
-```
-
-Exit 0 — Copilot reviews are disabled: respond with the literal line
-`/copilot-review is disabled via CLAUDE_REVIEWS_DISABLED.` and stop — do not
-spawn the subagent, do not call the Copilot reviewer API, do not run any
-other step of this skill. Exit 1 — continue. Gate semantics live in the
-`reviewer-gates` skill ([../reviewer-gates/SKILL.md](../reviewer-gates/SKILL.md)).
-
-### Step 1: Gather PR context
-
-From the current repo:
-
-```bash
-# MCP: pull_request_read(method="get") returns {number, url, head.sha, base.ref, head.ref, isDraft}
-```
-
-Capture `number`, `head.sha`, owner/repo (from `url`), and branch name. Pass these to the subagent so it does not rediscover them.
-
-### Step 2: Spawn the background subagent
-
-Invoke the `Agent` tool with:
-
-- `subagent_type: "general-purpose"`
-- `run_in_background: true`
-- `description: "Copilot review loop for PR #<N>"`
-- `prompt`: the full instructions in **Step 3 (Subagent prompt template)**, with placeholders filled in from Step 1.
-
-Record the returned agent ID. Report to the user in one or two lines:
-
-- The subagent is running in the background.
-- It self-terminates on convergence.
-- To stop it early, the user says "stop the copilot loop" and you call `TaskStop <agent_id>`.
-- The main session stays free; completion arrives as a notification.
-
-Let the subagent own the cadence. The skill's job in the main session ends once the subagent is spawned and reported.
-
-### Step 3: Subagent prompt template
-
-Pass this verbatim to the subagent (substituting the bracketed values):
-
-> You are babysitting the GitHub Copilot reviewer on PR **#[NUMBER]** at **[OWNER]/[REPO]** (branch `[BRANCH]`, current HEAD `[HEAD_SHA]`). Your job: keep the loop running until Copilot returns a clean review against the current HEAD, then stop.
->
-> **Per-tick work** (do this now, then on each wakeup):
->
-> 1. Resolve current HEAD: `pull_request_read(method="get", pullNumber=[NUMBER], owner="[OWNER]", repo="[REPO]")` and extract `.head.sha`.
-> 2. Fetch latest Copilot review via `pull_request_read(method="get_reviews", pullNumber=[NUMBER], owner="[OWNER]", repo="[REPO]")`.
->    Capture `commit_id`, `state`, `submitted_at`, `id`.
-> 3. Decide the branch:
->    - **No review exists:** increment `no_review_count` (see escalation rule below), re-request (step 4), schedule next wakeup, return.
->    - **Latest review's `commit_id` != current HEAD:** increment `no_review_count`, re-request (step 4), schedule next wakeup, return.
->    - **Latest review's `commit_id` == current HEAD with unresolved inline findings:** reset `no_review_count` to 0, TDD-fix them, push, reply inline on each thread, resolve each addressed thread, re-request (step 4), schedule next wakeup, return.
->    - **Latest review's `commit_id` == current HEAD and clean:** report convergence to the parent with a one-sentence summary and terminate. The loop is done; skip the ScheduleWakeup call.
->
->    **Escalation rule:** `no_review_count` starts at 0, counts consecutive ticks where no Copilot review exists at the current HEAD, and resets to 0 on every push and every review sighted at HEAD. When it reaches 3, Copilot is not delivering reviews — report the stall to the parent with the count and the last request timestamp, then terminate without scheduling another wakeup.
-> 4. Re-request Copilot via `request_copilot_review(owner="[OWNER]", repo="[REPO]", pullNumber=[NUMBER])`.
->    The reviewer ID **must** be `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix — empirically verified: `Copilot`, `copilot`, and `github-copilot` all return `requested_reviewers: []` with no error, silently no-op.
-> 5. Schedule the next wakeup with `ScheduleWakeup`:
->    - `delaySeconds: 360`
->    - `reason`: one short sentence on what you are waiting for.
->    - `prompt`: the literal sentinel `<<autonomous-loop-dynamic>>` so the next firing re-enters these instructions.
->
-> **Fix protocol** (step 3, third branch):
->
-> - Read `$HOME/.claude/skills/pr-fix-protocol/SKILL.md` and apply it — it carries the shared fix sequence, the reply-and-resolve unit, and the unresolved-thread sweep.
-> - Read each referenced file:line.
-> - Write a failing test first when the finding has behavior to test. For pure doc or comment nits that have no behavior, go straight to the fix.
-> - Stage the fix and create one new commit on the existing branch: `git add <files> && git commit -m "fix(review): ..."`.
-> - Push the new commit: `git push origin [BRANCH]`.
-> - Reply inline via `add_reply_to_pull_request_comment(owner="[OWNER]", repo="[REPO]", pullNumber=[NUMBER], body="...", commentId=<comment_id>)`, referencing the new commit SHA; then resolve each addressed thread via `pull_request_review_write(method="resolve_thread", pullNumber=[NUMBER], owner="[OWNER]", repo="[REPO]", threadId="<PRRT id>")`, harvesting the `PRRT_…` id from `pull_request_read(method="get_review_comments", ...)`. Reply first, then resolve — atomic per thread, per the protocol.
->
-> When a pre-push, pre-commit, or other hook rejects the change, solve it. Read the hook's error message, diagnose the root cause in the code or test, and fix that. Then rerun the commit or push. Hooks exist to catch real problems; treat each rejection as new evidence to act on.
->
-> **Stop conditions:**
->
-> - Convergence (clean review against HEAD): report one-sentence summary to parent and terminate.
-> - Blocker you have exhausted fix attempts on (API auth failure persists, CI regression whose root cause falls outside this PR, a hook you have investigated and cannot resolve in one commit): report the specific blocker and its diagnosis to the parent, then terminate without scheduling another wakeup.
-> - Parent sends `TaskStop`: terminate immediately.
-> - `no_review_count` reaches 3 (escalation rule above): report the stall and terminate.
->
-> **Safety cap:** after 20 ticks without convergence, stop and report. This is the total-tick runaway guard, distinct from the 3-consecutive-no-review escalation; that many rounds means something structural is wrong with the loop.
-
-### Step 4: Report back to the user
-
-After spawning, tell the user in one or two lines: subagent ID, PR URL, that it will notify on convergence or blocker. Nothing else.
-
-## Stopping the subagent
-
-- Convergence → subagent stops itself.
-- Blocker → subagent reports and stops.
-- User says stop → `TaskStop <agent_id>`.
-- User asks what loops are running → `TaskList`.
-
-## Ground rules (for the subagent)
-
-- **Append commits.** Each tick adds one new commit on the existing branch with `git commit` and `git push origin [BRANCH]`.
-- **Honor pre-push and pre-commit hooks.** When a hook rejects the change, read its output, fix the underlying issue (the failing test, the missing constant, the broken import), and retry. Solve, do not punt.
-- **Respect the PR's current state.** Whatever draft-vs-ready state the PR has when the loop starts is the state the subagent preserves. The user decides when to flip it.
-- **One fix commit per tick.** Batch all of the current tick's findings into a single commit; the next tick handles the next review round.
-- **Use `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix for the reviewer ID.** That exact spelling is load-bearing — it is the only form the API accepts.
-
-## Examples
-
-<example>
-User: `/copilot-review`
-Claude: [reads PR context, spawns background subagent with the Step 3 template, reports "subagent X watching PR #123; will notify on convergence"]
-</example>
-
-<example>
-User: "babysit copilot on this PR until it's clean"
-Claude: [same as above]
-</example>
-
-<example>
-Subagent tick fires, latest Copilot review is against an older commit.
-Subagent: [re-requests review, schedules next wakeup, returns]
-</example>
-
-<example>
-Subagent tick fires, Copilot has 2 unaddressed inline findings on HEAD.
-Subagent: [TDD-fixes both, one commit, pushes, replies inline on both threads, resolves both threads, re-requests review, schedules next wakeup]
-</example>
-
-<example>
-Subagent tick fires, latest review is clean against HEAD.
-Subagent: [reports convergence to parent, terminates — no further wakeups]
-</example>
+---
+name: copilot-review
+description: >-
+  Spawns a background subagent that babysits the GitHub Copilot reviewer on the
+  current PR: each tick it fixes unaddressed findings against HEAD, re-requests
+  review, and exits on convergence. Triggers: '/copilot-review', 'watch
+  copilot', 'babysit copilot review', 'keep re-requesting copilot'.
+---
+
+# Copilot Review
+
+Delegates Copilot babysitting to a background subagent so the main session stays free. The subagent loops internally and closes itself on convergence.
+
+## Transport check (before any GitHub step)
+
+Run `command -v gh`; when it succeeds, run `gh auth status`; once the PR scope is resolved, run `gh api repos/<owner>/<repo> --jq .permissions.push` and take `true` as the pass. When any check fails, run the `pr-loop-cloud-transport` skill first, route every `gh` operation in this skill through its substitution matrix, and carry the same routing into the subagent prompt so the spawned watcher inherits it.
+
+## When this skill applies
+
+The user is on a PR branch, wants Copilot (the GitHub Copilot reviewer bot) to keep re-reviewing after each push, and wants findings auto-addressed between ticks — but does not want the main conversation consumed by polling.
+
+## The Process
+
+### Step 0: Opt-out check
+
+Before any other work, run:
+
+```bash
+python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer copilot
+```
+
+Exit 0 — Copilot reviews are disabled: respond with the literal line
+`/copilot-review is disabled via CLAUDE_REVIEWS_DISABLED.` and stop — do not
+spawn the subagent, do not call the Copilot reviewer API, do not run any
+other step of this skill. Exit 1 — continue. Gate semantics live in the
+`reviewer-gates` skill ([../reviewer-gates/SKILL.md](../reviewer-gates/SKILL.md)).
+
+### Step 1: Gather PR context
+
+From the current repo:
+
+```bash
+# MCP: pull_request_read(method="get") returns {number, url, head.sha, base.ref, head.ref, isDraft}
+```
+
+Capture `number`, `head.sha`, owner/repo (from `url`), and branch name. Pass these to the subagent so it does not rediscover them.
+
+### Step 2: Spawn the background subagent
+
+Invoke the `Agent` tool with:
+
+- `subagent_type: "general-purpose"`
+- `run_in_background: true`
+- `description: "Copilot review loop for PR #<N>"`
+- `prompt`: the full instructions in **Step 3 (Subagent prompt template)**, with placeholders filled in from Step 1.
+
+Record the returned agent ID. Report to the user in one or two lines:
+
+- The subagent is running in the background.
+- It self-terminates on convergence.
+- To stop it early, the user says "stop the copilot loop" and you call `TaskStop <agent_id>`.
+- The main session stays free; completion arrives as a notification.
+
+Let the subagent own the cadence. The skill's job in the main session ends once the subagent is spawned and reported.
+
+### Step 3: Subagent prompt template
+
+Pass the prompt in
+[`templates/subagent-prompt.md`](templates/subagent-prompt.md) to the subagent
+word for word, filling in the bracketed values ([NUMBER], [OWNER], [REPO],
+[BRANCH], [HEAD_SHA]) from Step 1. It carries the per-tick work, the escalation
+rule (three consecutive no-review ticks), the fix protocol, the stop conditions,
+and the 20-tick safety cap.
+
+### Step 4: Report back to the user
+
+After spawning, tell the user in one or two lines: subagent ID, PR URL, that it will notify on convergence or blocker. Nothing else.
+
+## Stopping the subagent
+
+- Convergence → subagent stops itself.
+- Blocker → subagent reports and stops.
+- User says stop → `TaskStop <agent_id>`.
+- User asks what loops are running → `TaskList`.
+
+## Ground rules (for the subagent)
+
+- **Append commits.** Each tick adds one new commit on the existing branch with `git commit` and `git push origin [BRANCH]`.
+- **Honor pre-push and pre-commit hooks.** When a hook rejects the change, read its output, fix the underlying issue (the failing test, the missing constant, the broken import), and retry. Solve, do not punt.
+- **Respect the PR's current state.** Whatever draft-vs-ready state the PR has when the loop starts is the state the subagent preserves. The user decides when to flip it.
+- **One fix commit per tick.** Batch all of the current tick's findings into a single commit; the next tick handles the next review round.
+- **Use `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix for the reviewer ID.** That exact spelling is load-bearing — it is the only form the API accepts.
+
+## Examples
+
+<example>
+User: `/copilot-review`
+Claude: [reads PR context, spawns background subagent with the Step 3 template, reports "subagent X watching PR #123; will notify on convergence"]
+</example>
+
+<example>
+User: "babysit copilot on this PR until it's clean"
+Claude: [same as above]
+</example>
+
+<example>
+Subagent tick fires, latest Copilot review is against an older commit.
+Subagent: [re-requests review, schedules next wakeup, returns]
+</example>
+
+<example>
+Subagent tick fires, Copilot has 2 unaddressed inline findings on HEAD.
+Subagent: [TDD-fixes both, one commit, pushes, replies inline on both threads, resolves both threads, re-requests review, schedules next wakeup]
+</example>
+
+<example>
+Subagent tick fires, latest review is clean against HEAD.
+Subagent: [reports convergence to parent, terminates — no further wakeups]
+</example>

package/skills/copilot-review/templates/subagent-prompt.md

@@ -0,0 +1,49 @@
+# Copilot-review subagent prompt template
+
+The background watcher prompt for the `copilot-review` skill. The hub
+([`../SKILL.md`](../SKILL.md) Step 3) passes the fenced block below to the
+subagent word for word, with the bracketed values ([NUMBER], [OWNER], [REPO],
+[BRANCH], [HEAD_SHA]) filled in from Step 1.
+
+```text
+You are babysitting the GitHub Copilot reviewer on PR **#[NUMBER]** at **[OWNER]/[REPO]** (branch `[BRANCH]`, current HEAD `[HEAD_SHA]`). Your job: keep the loop running until Copilot returns a clean review against the current HEAD, then stop.
+
+**Per-tick work** (do this now, then on each wakeup):
+
+1. Resolve current HEAD: `pull_request_read(method="get", pullNumber=[NUMBER], owner="[OWNER]", repo="[REPO]")` and extract `.head.sha`.
+2. Fetch latest Copilot review via `pull_request_read(method="get_reviews", pullNumber=[NUMBER], owner="[OWNER]", repo="[REPO]")`.
+   Capture `commit_id`, `state`, `submitted_at`, `id`.
+3. Decide the branch:
+   - **No review exists:** increment `no_review_count` (see escalation rule below), re-request (step 4), schedule next wakeup, return.
+   - **Latest review's `commit_id` != current HEAD:** increment `no_review_count`, re-request (step 4), schedule next wakeup, return.
+   - **Latest review's `commit_id` == current HEAD with unresolved inline findings:** reset `no_review_count` to 0, TDD-fix them, push, reply inline on each thread, resolve each addressed thread, re-request (step 4), schedule next wakeup, return.
+   - **Latest review's `commit_id` == current HEAD and clean:** report convergence to the parent with a one-sentence summary and terminate. The loop is done; skip the ScheduleWakeup call.
+
+   **Escalation rule:** `no_review_count` starts at 0, counts consecutive ticks where no Copilot review exists at the current HEAD, and resets to 0 on every push and every review sighted at HEAD. When it reaches 3, Copilot is not delivering reviews — report the stall to the parent with the count and the last request timestamp, then terminate without scheduling another wakeup.
+4. Re-request Copilot via `request_copilot_review(owner="[OWNER]", repo="[REPO]", pullNumber=[NUMBER])`.
+   The reviewer ID **must** be `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix — empirically verified: `Copilot`, `copilot`, and `github-copilot` all return `requested_reviewers: []` with no error, silently no-op.
+5. Schedule the next wakeup with `ScheduleWakeup`:
+   - `delaySeconds: 360`
+   - `reason`: one short sentence on what you are waiting for.
+   - `prompt`: the literal sentinel `<<autonomous-loop-dynamic>>` so the next firing re-enters these instructions.
+
+**Fix protocol** (step 3, third branch):
+
+- Read `$HOME/.claude/skills/pr-fix-protocol/SKILL.md` and apply it — it carries the shared fix sequence, the reply-and-resolve unit, and the unresolved-thread sweep.
+- Read each referenced file:line.
+- Write a failing test first when the finding has behavior to test. For pure doc or comment nits that have no behavior, go straight to the fix.
+- Stage the fix and create one new commit on the existing branch: `git add <files> && git commit -m "fix(review): ..."`.
+- Push the new commit: `git push origin [BRANCH]`.
+- Reply inline via `add_reply_to_pull_request_comment(owner="[OWNER]", repo="[REPO]", pullNumber=[NUMBER], body="...", commentId=<comment_id>)`, referencing the new commit SHA; then resolve each addressed thread via `pull_request_review_write(method="resolve_thread", pullNumber=[NUMBER], owner="[OWNER]", repo="[REPO]", threadId="<PRRT id>")`, harvesting the `PRRT_…` id from `pull_request_read(method="get_review_comments", ...)`. Reply first, then resolve — atomic per thread, per the protocol.
+
+When a pre-push, pre-commit, or other hook rejects the change, solve it. Read the hook's error message, diagnose the root cause in the code or test, and fix that. Then rerun the commit or push. Hooks exist to catch real problems; treat each rejection as new evidence to act on.
+
+**Stop conditions:**
+
+- Convergence (clean review against HEAD): report one-sentence summary to parent and terminate.
+- Blocker you have exhausted fix attempts on (API auth failure persists, CI regression whose root cause falls outside this PR, a hook you have investigated and cannot resolve in one commit): report the specific blocker and its diagnosis to the parent, then terminate without scheduling another wakeup.
+- Parent sends `TaskStop`: terminate immediately.
+- `no_review_count` reaches 3 (escalation rule above): report the stall and terminate.
+
+**Safety cap:** after 20 ticks without convergence, stop and report. This is the total-tick runaway guard, distinct from the 3-consecutive-no-review escalation; that many rounds means something structural is wrong with the loop.
+```

package/skills/fresh-branch/CLAUDE.md

@@ -1,15 +1,12 @@
 # fresh-branch
 
-Creates a new branch from `origin/main` (always fresh-fetched). Triggered by `fresh branch`, `new branch from main`, `/fresh-branch`, or `start fresh`.
+Creates a new branch from fresh-fetched `origin/main` inside an isolated worktree under `Temp/<agent>/<branch-name>`. Does not push, open a PR, or run `checkout -b` in the caller tree.
 
-## Purpose
-
-A shared primitive used by other skills and directly by the user. Fetches `origin/main`, suggests 2–4 branch names via `AskUserQuestion` when a topic is available (polling recent branch naming patterns from `git branch -r`), then creates and checks out the branch with `git checkout -b <name> origin/main`.
-
-Does not push the branch. Does not create a PR. Does not switch an existing branch. Callers that need the new branch name (for example, to open a PR) receive it as a return value.
-
-## Key file
+## Key files
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Four-phase instructions: fetch `origin/main`, pick branch name (suggest or prompt), create branch, report. Includes gotchas discovered during use. |
+| `SKILL.md` | Phases, checklist, execute-vs-read for the CLI, gotchas |
+| `scripts/create_fresh_branch.py` | Deterministic CLI: fetch base, `git worktree add -b`, JSON stdout |
+| `scripts/test_create_fresh_branch.py` | Behavioral tests with temporary git repos |
+| `scripts/fresh_branch_scripts_constants/` | Constants package (`fresh_branch_cli_constants`) for the CLI |