@codedrifters/configulator 0.0.222 → 0.0.224

package/lib/index.mjs

@@ -4236,7 +4236,10 @@ var issueWorkerSubAgent = {
     "",
     "## Invocation Mode",
     "",
-    "You operate in one of two modes:",
+    "You operate in one of two **invocation modes** (interactive vs scheduled)",
+    "and one of two **work modes** (normal vs feedback).",
+    "",
+    "### Interactive vs Scheduled",
     "",
     "- **Interactive mode (default):** A human invoked you directly. You must",
     "  pause and request explicit user approval before committing code (Phase 6).",
@@ -4249,11 +4252,52 @@ var issueWorkerSubAgent = {
     "doubt, treat the session as interactive \u2014 pausing for approval is always",
     "safe; committing without approval is not.",
     "",
+    "### Normal vs Feedback",
+    "",
+    "- **Normal mode (default):** You select an issue from the queue (or use a",
+    "  provided issue number), create a new branch, implement the change, and",
+    "  open a new PR. Phases 1\u20139 all run.",
+    "- **Feedback mode:** You are given an existing PR number and asked to",
+    "  apply reviewer-requested fixes to the PR's existing branch. You do",
+    "  **not** create a new branch and you do **not** open a new PR \u2014 you",
+    "  push additional commits to the same branch.",
+    "",
+    "**You are in feedback mode if and only if the invocation prompt that",
+    "started this session contains the literal phrase `feedback mode: PR #<n>`",
+    "(where `<n>` is the PR number).** This mirrors the `scheduled mode` /",
+    "`non-interactive` string-match convention above. Otherwise, default to",
+    "normal mode.",
+    "",
+    "Interactive vs scheduled and normal vs feedback are independent axes.",
+    "Feedback mode can run interactively (a human asks you to fix a PR) or",
+    "on a schedule (the pr-reviewer hands off the PR). The interactive",
+    "pause-before-commit rule (Phase 6) applies in either work mode.",
+    "",
+    "When in feedback mode, the per-phase behaviour changes as documented",
+    "in each phase below. In summary:",
+    "",
+    "| Phase | Normal mode | Feedback mode |",
+    "|-------|-------------|---------------|",
+    "| 1. Select an Issue | Pick from queue or use provided issue number | **Skip.** Use the PR number from the invocation prompt. |",
+    "| 2. Claim the Issue | Toggle status labels on the issue | **Skip.** The issue is already `status:in-progress`. |",
+    "| 3. Set Up | Checkout default branch, create new branch | Checkout the existing PR branch via `gh pr view` and `git checkout <headRefName>`. |",
+    "| 4. Implement | Read issue AC, implement | Read most-recent reviewer-authored fix-list comment on the PR, parse JSON, apply each item. |",
+    "| 5. Verify | Unchanged | Unchanged. |",
+    "| 6. Commit and Push | Conventional commit, interactive pause | Commit message `fix(review): <summary> (PR #<n>)`. Pause behaviour unchanged. `git push` (no `-u`). |",
+    "| 7. Open a PR | Open a new PR | **Skip.** |",
+    "| 8. Update Status | Set issue to `status:ready-for-review` | **Skip.** PR is still open; issue stays `status:in-progress`. |",
+    "| 9. Branch Cleanup | Poll for merge, delete branch | **Skip.** Return control to the pr-reviewer without polling. |",
+    "",
     "---",
     "",
     ...PROJECT_CONTEXT_READER_SECTION,
     "## Phase 1: Select an Issue",
     "",
+    "**Feedback mode:** Skip this phase entirely. Extract the PR number from",
+    "the `feedback mode: PR #<n>` phrase in your invocation prompt and use",
+    "it for the rest of the workflow.",
+    "",
+    "**Normal mode:**",
     "If an issue number was provided in your instructions, use that issue.",
     "Otherwise, find the next issue to work on:",
     "",
@@ -4270,6 +4314,12 @@ var issueWorkerSubAgent = {
     "",
     "## Phase 2: Claim the Issue",
     "",
+    "**Feedback mode:** Skip this phase entirely. The issue linked to the PR",
+    "is already in `status:in-progress` from when the original PR was opened.",
+    "Do not toggle any status labels on the issue.",
+    "",
+    "**Normal mode:**",
+    "",
     "```bash",
     'gh issue edit <number> --remove-label "status:ready" --add-label "status:in-progress"',
     "```",
@@ -4281,6 +4331,31 @@ var issueWorkerSubAgent = {
     "",
     "## Phase 3: Set Up",
     "",
+    "**Feedback mode:** Do **not** check out the default branch and do **not**",
+    "create a new branch. Instead, look up the PR's head branch and check it out:",
+    "",
+    "```bash",
+    "gh pr view <pr-number> --json state,headRefName,baseRefName,author",
+    "```",
+    "",
+    "First verify the PR `state` is `OPEN`. If the state is `MERGED` or",
+    "`CLOSED`, abort immediately \u2014 do not modify the branch. Report the",
+    "state to the caller and stop.",
+    "",
+    "Then fetch and check out the existing branch:",
+    "",
+    "```bash",
+    "git fetch origin",
+    "git checkout <headRefName>",
+    "git pull --rebase origin <headRefName>",
+    "```",
+    "",
+    "If the rebase produces a conflict, abort and report failure \u2014 do not",
+    "force-push and do not attempt to resolve conflicts in feedback mode.",
+    "Skip the remainder of this phase (no new branch, no status comment).",
+    "",
+    "**Normal mode:**",
+    "",
     "```bash",
     "git checkout {{repository.defaultBranch}} && git pull origin {{repository.defaultBranch}}",
     "```",
@@ -4312,6 +4387,52 @@ var issueWorkerSubAgent = {
     "",
     "## Phase 4: Implement",
     "",
+    "**Feedback mode:** Read PR comments and apply the reviewer's fix list.",
+    "",
+    "1. List the PR's issue comments newest-first and pick the **most recent**",
+    "   comment authored by the reviewer account that contains a fenced",
+    "   code block with the language tag `fix-list`:",
+    "",
+    "   ```bash",
+    "   gh pr view <pr-number> --json comments",
+    "   ```",
+    "",
+    "2. Extract the JSON body of the ` ```json fix-list ` block. The reviewer",
+    "   writes the comment in this exact shape:",
+    "",
+    "   ````markdown",
+    "   ## Reviewer: fix list for @issue-worker",
+    "",
+    "   - [ ] @<author> \u2014 <instruction summary> (<file>:<line>)",
+    "",
+    "   ```json fix-list",
+    "   {",
+    '     "pr": 123,',
+    '     "branch": "feat/42-add-foo",',
+    '     "generated_at": "2026-04-16T14:02:00Z",',
+    '     "items": [',
+    '       {"comment_id": "IC_abc", "author": "alice", "file": "src/foo.ts", "line": 42, "instruction": "rename getFoo to fetchFoo"},',
+    '       {"comment_id": "IC_def", "author": "bob",   "file": "src/foo.test.ts", "instruction": "add a test for the null branch"}',
+    "     ]",
+    "   }",
+    "   ```",
+    "   ````",
+    "",
+    "   The JSON block is the **authoritative** list of work \u2014 the checkbox",
+    "   summary above it is for humans only and must be ignored. If multiple",
+    "   reviewer-authored fix-list comments exist, use the most recent one.",
+    "   If the JSON cannot be parsed, abort and report failure.",
+    "",
+    "3. Apply each `items[].instruction` in order. Each item references a",
+    "   `file` (and optional `line`). Track `comment_id` per item so you can",
+    "   report which items were handled and which (if any) failed.",
+    "",
+    "4. When complete, prepare a short structured report (PR number, commit",
+    "   SHAs you will push, items handled by `comment_id`, items that failed",
+    "   to apply) \u2014 you will return this after Phase 6.",
+    "",
+    "**Normal mode:**",
+    "",
     "Read the issue body carefully. Understand the acceptance criteria.",
     "",
     "Implement the change following these guidelines based on issue type:",
@@ -4353,7 +4474,23 @@ var issueWorkerSubAgent = {
     "",
     "**If you are in scheduled mode, skip the pause and proceed directly.**",
     "",
-    "Use conventional commit messages:",
+    "**Feedback mode:** Use a `fix(review)` commit message that references",
+    "the PR number, and push to the existing branch **without** `-u` (the",
+    "branch is already tracking origin). Before pushing, re-run",
+    "`git pull --rebase origin <branch-name>` to incorporate any commits",
+    "that landed on the branch while you were working. **Never force-push.**",
+    "If the rebase conflicts, abort and report failure.",
+    "",
+    "```bash",
+    "git add <files>",
+    'git commit -m "fix(review): <summary> (PR #<pr-number>)"',
+    "git pull --rebase origin <branch-name>",
+    "git push origin <branch-name>",
+    "```",
+    "",
+    "**Normal mode:** Use conventional commit messages and push with `-u`",
+    "to set up branch tracking:",
+    "",
     "```bash",
     "git add <files>",
     'git commit -m "<type>: <description>"',
@@ -4362,6 +4499,12 @@ var issueWorkerSubAgent = {
     "",
     "## Phase 7: Open a PR",
     "",
+    "**Feedback mode:** Skip this phase entirely. The PR already exists; you",
+    "have pushed additional commits to its existing branch. Do not open a new",
+    "PR.",
+    "",
+    "**Normal mode:**",
+    "",
     "Every PR you open must carry the `origin:issue-worker` label so downstream",
     "agents can identify bot-authored PRs. Always include",
     "`--label 'origin:issue-worker'` in the `gh pr create` invocation:",
@@ -4383,6 +4526,12 @@ var issueWorkerSubAgent = {
     "",
     "## Phase 8: Update Status",
     "",
+    "**Feedback mode:** Skip this phase entirely. The linked issue stays in",
+    "`status:in-progress` while the PR is still open \u2014 do not toggle any",
+    "labels.",
+    "",
+    "**Normal mode:**",
+    "",
     "After the PR is created, transition the issue to the review phase:",
     "```bash",
     'gh issue edit <number> --remove-label "status:in-progress" --add-label "status:ready-for-review"',
@@ -4393,6 +4542,13 @@ var issueWorkerSubAgent = {
     "",
     "## Phase 9: Branch Cleanup",
     "",
+    "**Feedback mode:** Skip this phase entirely. Do not poll the PR state",
+    "and do not delete the local branch. Return control to the pr-reviewer",
+    "with the structured report from Phase 4 (PR number, commit SHAs pushed,",
+    "items handled by `comment_id`, items that failed to apply).",
+    "",
+    "**Normal mode:**",
+    "",
     "The PR will not auto-merge until the `pr-reviewer` enables it. Poll the PR",
     "state up to 10 times, waiting 30 seconds between polls, until it either",
     "merges, closes, or the timeout is reached:",
@@ -4430,7 +4586,23 @@ var issueWorkerSubAgent = {
     "   ```bash",
     '   gh issue edit <number> --remove-label "status:in-progress" --add-label "status:needs-attention"',
     '   gh issue comment <number> --body "Worker could not complete: <reason>"',
-    "   ```"
+    "   ```",
+    "8. **Never force-push in feedback mode.** If a `git pull --rebase`",
+    "   produces conflicts, abort and report failure. Do not pass",
+    "   `--force` or `--force-with-lease` to `git push`.",
+    "9. **Abort if the PR is not OPEN in feedback mode.** Before checking",
+    "   out the head branch, verify `gh pr view <pr> --json state` returns",
+    "   `OPEN`. If the state is `MERGED` or `CLOSED`, stop immediately \u2014",
+    "   do not modify the branch.",
+    "10. **Use the most-recent reviewer-authored fix-list comment.** If",
+    "    multiple `fix-list` comments exist on the PR, use the most recent",
+    "    one authored by the reviewer account. Ignore older fix-list",
+    "    comments and any fix-list comments authored by other accounts.",
+    "11. **Never create a new branch in feedback mode.** Always check out",
+    "    the existing PR head branch returned by `gh pr view`. Do not run",
+    "    `git checkout -b` while in feedback mode.",
+    "12. **Never `git push -u` in feedback mode.** The existing PR branch",
+    "    already tracks origin. Use plain `git push origin <branch-name>`."
   ].join("\n")
 };
 var orchestratorBundle = {
@@ -5377,6 +5549,81 @@ var prReviewerSubAgent = {
     "gh issue view <issue-number> --json number,title,body,labels,state,issueType",
     "```",
     "",
+    "## Phase 2.5: Gather Comments",
+    "",
+    "Before deciding review mode, collect every human comment on the PR so",
+    "that Phase 3.5 can classify each one and Phase 4.5 can render the",
+    "sticky **Reviewer notes** summary. GitHub exposes PR comments across",
+    "three distinct endpoints; the reviewer merges all three into a single",
+    "queue.",
+    "",
+    "### Step 1: Fetch all three comment sources",
+    "",
+    "```bash",
+    "# PR-level issue comments (top-level discussion thread)",
+    "gh pr view <pr-number> --json comments",
+    "",
+    "# Inline code-review comments (line-anchored in the diff)",
+    "gh api repos/{{repository.owner}}/{{repository.name}}/pulls/<pr-number>/comments",
+    "",
+    "# Formal review bodies and their APPROVED / CHANGES_REQUESTED / COMMENTED state",
+    "gh api repos/{{repository.owner}}/{{repository.name}}/pulls/<pr-number>/reviews",
+    "```",
+    "",
+    "For each item, capture: the comment id, author login, body, creation",
+    "time, the URL, and any reactions already present (including which",
+    "reactions the reviewer itself has previously applied). For inline",
+    "review comments, also capture the thread / conversation resolution",
+    "state so Step 2 can drop resolved threads.",
+    "",
+    "### Step 2: Apply filtering rules",
+    "",
+    "Drop a comment from classification when **any** of the following hold:",
+    "",
+    "1. **Reviewer's own comments.** The author login matches the invoking",
+    "   agent identity (for example, the bot account used to post prior",
+    "   reviewer replies, sticky summaries, or fix-list comments). The",
+    "   reviewer never classifies or reacts to its own output.",
+    "2. **Bot authors.** The author login matches `*[bot]` \u2014 CI bots,",
+    "   Dependabot, CodeRabbit, GitHub Actions, and similar automation.",
+    "3. **Terminal reviewer reactions already present.** The comment",
+    "   already carries a reaction **authored by the reviewer** in the set",
+    "   `+1` (accepted), `rocket` (landed), or `-1` (declined as",
+    "   out-of-scope). These signal the item has reached a terminal state",
+    "   on a previous pass and requires no further action.",
+    "4. **Resolved threads.** Inline comments belonging to a conversation",
+    "   that GitHub marks as resolved.",
+    "",
+    "A comment whose only reviewer-authored reaction is `eyes` is **not**",
+    'terminal. `eyes` means "seen on a previous pass but not yet resolved"',
+    "\u2014 keep it in the queue so Phase 3.5 can re-evaluate and possibly",
+    "promote it to a terminal state once the corresponding action",
+    "completes.",
+    "",
+    "A comment whose only reviewer-authored reaction is `thinking_face` is",
+    "also **not** terminal \u2014 it indicates an open dispute the reviewer",
+    "raised on a prior pass that has not yet been resolved by the human.",
+    "Phase 4 uses the presence of unresolved `thinking_face` reactions as",
+    "the pushback gate.",
+    "",
+    "### Step 3: Record the gathered set",
+    "",
+    "Persist the filtered comment list in memory for Phase 3.5 and Phase",
+    "4.5. For each surviving comment record at minimum:",
+    "",
+    "```",
+    "- id: <comment or review id>",
+    "  source: <pr-comment | inline-comment | review-body>",
+    "  author: <login>",
+    "  url: <html_url>",
+    "  body: <text>",
+    "  reactions: <list of reactions with authors>",
+    "```",
+    "",
+    "If there are no unhandled comments after filtering, record that fact",
+    "and proceed \u2014 Phase 3.5 will short-circuit, and the Phase 4.5 sticky",
+    "summary will simply list no outstanding items.",
+    "",
     "## Phase 2.75: Determine Review Mode",
     "",
     "Before comparing the diff to the acceptance criteria, evaluate the PR",
@@ -5465,8 +5712,175 @@ var prReviewerSubAgent = {
     "- **CI status** \u2014 `gh pr checks` reports all required checks passing",
     "- **Scope creep** \u2014 diff stays within the issue's stated scope",
     "",
+    "## Phase 3.5: Classify Comments",
+    "",
+    "For every comment that survived Phase 2.5 filtering, assign exactly",
+    "one classification and take the corresponding action. The reviewer",
+    "acts only on unhandled comments; anything already in a terminal state",
+    "was dropped in Phase 2.5 and is left alone.",
+    "",
+    "### Classifications",
+    "",
+    "#### `in-scope`",
+    "",
+    "The comment requests a change that falls **inside** the linked",
+    "issue's acceptance criteria (or is an obvious defect in code the PR",
+    "itself introduced).",
+    "",
+    "Action on this pass:",
+    "",
+    "- React `eyes` on the comment to mark it seen.",
+    "- Queue the comment for later delegation. **Delegation wiring is out",
+    "  of scope for this phase** \u2014 the fix-list comment and the",
+    "  issue-worker hand-off land in a follow-up issue. For now, record",
+    "  the queued items in memory so Phase 4.5 can list them as",
+    "  outstanding.",
+    "- Do **not** apply `+1` or `rocket` yet. Those are terminal",
+    "  reactions reserved for later passes once the fix has been accepted",
+    "  into the PR (`+1`) and actually landed on the branch (`rocket`).",
+    "",
+    "```bash",
+    "# React eyes on a PR-level issue comment",
+    "gh api repos/{{repository.owner}}/{{repository.name}}/issues/comments/<comment-id>/reactions \\",
+    "  -X POST -f content=eyes",
+    "",
+    "# React eyes on an inline code-review comment",
+    "gh api repos/{{repository.owner}}/{{repository.name}}/pulls/comments/<comment-id>/reactions \\",
+    "  -X POST -f content=eyes",
+    "```",
+    "",
+    "#### `out-of-scope`",
+    "",
+    "The comment requests work that falls **outside** the linked issue's",
+    "acceptance criteria \u2014 new functionality, a refactor that would",
+    "expand the diff, a cleanup in a neighbouring module, and so on. It",
+    "is a legitimate request, just not for this PR.",
+    "",
+    "Action:",
+    "",
+    "1. Create a new tracking issue following the `Create Issue Workflow`",
+    "   in CLAUDE.md. Derive the title prefix (`feat:`, `fix:`, `chore:`,",
+    "   etc.) from the content of the comment. Apply the correct",
+    "   `type:*`, `priority:*`, and `status:*` labels and assign the",
+    "   GitHub issue type via the documented GraphQL mutation.",
+    "2. Reply to the original comment with a link to the new issue:",
+    "   `Tracked separately in #<new-issue>.`",
+    "3. React `-1` on the original comment. `-1` is the terminal",
+    "   reaction for out-of-scope and is only applied **after** the new",
+    "   issue has been successfully created and the reply posted.",
+    "",
+    "```bash",
+    "# Reply on the same thread",
+    "gh pr comment <pr-number> --body 'Tracked separately in #<new-issue>.'",
+    "",
+    "# React -1 on the original comment once the new issue exists",
+    "gh api repos/{{repository.owner}}/{{repository.name}}/issues/comments/<comment-id>/reactions \\",
+    "  -X POST -f content=-1",
+    "```",
+    "",
+    "#### `dispute`",
+    "",
+    "The comment conflicts with an acceptance criterion, a documented",
+    "CLAUDE.md convention, or the project-context doc; or it is ambiguous",
+    "enough that implementation would require guessing at intent. The",
+    "reviewer pushes back rather than silently complying.",
+    "",
+    "Action:",
+    "",
+    "1. React `thinking_face` on the comment to mark it as disputed.",
+    "   This reaction is **not** terminal \u2014 it persists until the human",
+    "   resolves the dispute.",
+    "2. Post a reply on the same thread explaining the pushback. Cite",
+    "   the specific acceptance criterion, convention, or project-context",
+    "   section that the comment conflicts with, or name the ambiguity",
+    "   that needs resolution.",
+    "3. The presence of an unresolved `thinking_face` reaction by the",
+    "   reviewer blocks auto-merge in Phase 4 regardless of the review",
+    "   mode decided in Phase 2.75.",
+    "",
+    "```bash",
+    "# React thinking_face on the disputed comment",
+    "gh api repos/{{repository.owner}}/{{repository.name}}/issues/comments/<comment-id>/reactions \\",
+    "  -X POST -f content=confused",
+    "",
+    "# Post the pushback reply",
+    "gh pr comment <pr-number> --body '<pushback explanation>'",
+    "```",
+    "",
+    "Note: GitHub's reactions API uses `confused` as the content string",
+    "for the `thinking_face` reaction; use `content=confused` when",
+    "POSTing the reaction.",
+    "",
+    "#### `nit` / `question`",
+    "",
+    "The comment is a minor stylistic preference, a clarifying question",
+    "with a short answer, or a drive-by note that does not request a",
+    "code change.",
+    "",
+    "Action:",
+    "",
+    "- React `eyes` to mark the comment seen.",
+    "- Optionally post a brief reply when the question has a short,",
+    "  factual answer. Skip the reply when there is nothing useful to",
+    "  add \u2014 an `eyes` reaction alone is sufficient.",
+    "- Never apply `+1`, `rocket`, or `-1` to a `nit` / `question`",
+    "  comment; those reactions are reserved for their documented",
+    "  terminal meanings.",
+    "",
+    "### Reaction protocol summary",
+    "",
+    "| Reaction | Meaning | Terminal? |",
+    "|----------|---------|-----------|",
+    "| `eyes` | Seen by reviewer; awaiting further action | No |",
+    "| `thinking_face` (`confused`) | Reviewer disputes this comment | No |",
+    "| `+1` | Reviewer accepts the comment's request | **Yes** |",
+    "| `rocket` | The accepted change has landed on the branch | **Yes** |",
+    "| `-1` | Reviewer declined as out-of-scope; tracked in a new issue | **Yes** |",
+    "",
+    "Terminal reactions (`+1`, `rocket`, `-1`) **must only be applied**",
+    "when the corresponding action is truly complete:",
+    "",
+    "- `+1` \u2014 only after the reviewer has confirmed the comment's",
+    "  request is in-scope and the fix has been accepted for this PR.",
+    "- `rocket` \u2014 only after the accepted fix has actually landed on the",
+    "  PR's branch (a commit addressing the comment is present).",
+    "- `-1` \u2014 only after a new tracking issue has been successfully",
+    "  created for the out-of-scope request and the reply linking to it",
+    "  has been posted.",
+    "",
+    "Never pre-emptively apply a terminal reaction. Applying one signals",
+    "to humans and to future reviewer passes that the item is closed;",
+    "applying it early creates a false record of completion.",
+    "",
     "## Phase 4: Decide and Act",
     "",
+    "### Pushback gate (runs before every merge decision)",
+    "",
+    "Before taking any merge-enabling action in this phase, verify that no",
+    "**unresolved `thinking_face` reactions by the reviewer** remain on",
+    "any comment gathered in Phase 2.5.",
+    "",
+    "A `thinking_face` reaction is considered **unresolved** when:",
+    "",
+    "- The reviewer applied it on this pass or a prior pass, and",
+    "- The underlying comment has not since received a resolution signal",
+    "  from the human \u2014 for example, the comment has not been withdrawn,",
+    "  the human has not posted a clarifying reply that the reviewer has",
+    "  since marked `+1`, and no `review:auto-ok` label has been applied",
+    "  to the PR as an explicit override.",
+    "",
+    "If any unresolved `thinking_face` reaction exists, **do not enable",
+    "auto-merge** and **do not apply `review:awaiting-human` as a success",
+    "hand-off**. This gate fires regardless of the review mode decided in",
+    "Phase 2.75 \u2014 pushback blocks the merge pathway even when the mode is",
+    "`auto-merge`. Skip straight to Phase 4.5 to update the sticky summary",
+    "with the outstanding pushbacks, then stop. A downstream issue",
+    "refines this gate further; for now, pushback simply blocks the",
+    "merge pathway.",
+    "",
+    "If no unresolved `thinking_face` reactions exist, proceed with the",
+    "branches below based on the review mode decided in Phase 2.75.",
+    "",
     "### If all acceptance criteria are met and CI is green",
     "",
     "Branch on the **review mode** decided in Phase 2.75:",
@@ -5524,6 +5938,82 @@ var prReviewerSubAgent = {
     "--request-changes`: it is lighter-weight, doesn't require the author to",
     "dismiss a formal review, and composes cleanly with the multi-PR loop.",
     "",
+    "## Phase 4.5: Update Sticky Summary",
+    "",
+    "On **every pass**, create or update a single **`## Reviewer notes`**",
+    "comment on the PR. This sticky comment is the human-facing single",
+    "source of truth for the PR's state \u2014 one comment per PR, edited in",
+    "place across passes, never duplicated. Do not post a fresh",
+    '"pass N summary" on each iteration.',
+    "",
+    "### Step 1: Find the existing sticky comment (if any)",
+    "",
+    "List PR-level comments and look for one authored by the reviewer",
+    "whose body starts with `## Reviewer notes`:",
+    "",
+    "```bash",
+    "gh api repos/{{repository.owner}}/{{repository.name}}/issues/<pr-number>/comments",
+    "```",
+    "",
+    "If multiple candidates exist (an older run double-posted before this",
+    "phase existed), keep the earliest and plan to delete the duplicates",
+    "on a later pass. Never delete another author's comment.",
+    "",
+    "### Step 2: Compose the sticky body",
+    "",
+    "The body uses the following shape:",
+    "",
+    "```",
+    "## Reviewer notes",
+    "",
+    "**Mode:** auto-merge | human-required \u2014 <reason from Phase 2.75>",
+    "**AC status:** <met / partial / missing> (evidence links)",
+    "**CI status:** green | pending | red",
+    "**Outstanding:** <list of comments still open with their classification and author>",
+    "**Pushbacks:** <list of disputes with reasons>",
+    "**Last pass:** <ISO timestamp>",
+    "```",
+    "",
+    "Populate each field from the phases above:",
+    "",
+    "- **Mode / reason** \u2014 the mode and reason recorded in Phase 2.75.",
+    "- **AC status** \u2014 the checklist produced in Phase 3 (met, partial,",
+    "  or missing), with links to the files or tests that provide the",
+    "  evidence.",
+    "- **CI status** \u2014 derived from `gh pr checks`.",
+    "- **Outstanding** \u2014 the comments still carrying a non-terminal",
+    "  reviewer reaction from Phase 3.5 (typically `eyes` for queued",
+    "  in-scope items and `nit` / `question` items that remain open).",
+    "  List each as `<classification>: <author> \u2014 <short summary> (<url>)`.",
+    "- **Pushbacks** \u2014 every comment the reviewer reacted",
+    "  `thinking_face` to on this or any prior pass, with the reason",
+    "  captured in the pushback reply. Empty list when there are none.",
+    "- **Last pass** \u2014 the ISO 8601 timestamp of this run.",
+    "",
+    "### Step 3: Create or edit in place",
+    "",
+    "If no existing sticky comment was found in Step 1, create one:",
+    "",
+    "```bash",
+    "gh pr comment <pr-number> --body '<sticky body>'",
+    "```",
+    "",
+    "If an existing sticky comment was found, edit it in place using the",
+    "comment id. Do not delete and re-create \u2014 editing preserves the",
+    "comment's URL and any reactions humans have added to the summary:",
+    "",
+    "```bash",
+    "gh api repos/{{repository.owner}}/{{repository.name}}/issues/comments/<sticky-comment-id> \\",
+    "  -X PATCH -f body='<sticky body>'",
+    "```",
+    "",
+    "The sticky summary must be updated on every pass through Phase 4.5,",
+    "including passes that ended in a pushback-gated skip, a",
+    "`NEEDS_CHANGES` findings comment, or the `human-required` hand-off.",
+    "Humans rely on the sticky comment to see the current state of the",
+    "PR at a glance \u2014 it must never go stale while the reviewer is",
+    "actively processing the PR.",
+    "",
     "## Phase 5: Branch Cleanup and Issue Closure Verification",
     "",
     "Skip this phase entirely when the review mode from Phase 2.75 is",
@@ -5618,7 +6108,35 @@ var prReviewerSubAgent = {
     "8. **In loop mode (`/review-prs`), never stop early.** If any review",
     "   fails, comment and move to the next PR. Only abort the loop on a",
     "   fatal error (e.g. `gh` auth failure, network outage).",
-    "9. **Follow CLAUDE.md conventions** for all `git` and `gh` operations."
+    "9. **Follow CLAUDE.md conventions** for all `git` and `gh` operations.",
+    "10. **Follow the reaction protocol.** Use `eyes` to mark a comment",
+    "    seen, `thinking_face` (`confused`) to dispute it, `+1` to accept",
+    "    its request, `rocket` when the accepted change has landed, and",
+    "    `-1` when the request is out-of-scope and has been tracked in a",
+    "    new issue. Apply reactions on the same comment endpoint the",
+    "    comment came from (`issues/comments/...` for PR-level, ",
+    "    `pulls/comments/...` for inline).",
+    "11. **Terminal reactions require completed actions.** `+1`, `rocket`,",
+    "    and `-1` must only be applied once the corresponding action is",
+    "    truly complete (respectively: the fix accepted, the fix landed,",
+    "    or the new out-of-scope issue created and linked in a reply).",
+    "    Never apply a terminal reaction pre-emptively; doing so falsely",
+    "    signals to humans and to future reviewer passes that the item",
+    "    is closed.",
+    "12. **Maintain one sticky `## Reviewer notes` comment per PR.** On",
+    "    each pass, find the existing sticky comment authored by the",
+    "    reviewer and edit it in place with `gh api ... -X PATCH`;",
+    "    create it only when none exists. Never post per-pass summary",
+    "    comments alongside the sticky \u2014 the sticky is the single",
+    "    human-facing source of truth for PR state.",
+    "13. **Pushback blocks auto-merge.** Any unresolved `thinking_face`",
+    "    reaction authored by the reviewer on any comment must prevent",
+    "    Phase 4 from enabling auto-merge, regardless of the review mode",
+    "    decided in Phase 2.75. The gate clears only when the human has",
+    "    resolved the dispute \u2014 by withdrawing the comment, by replying",
+    "    in a way that satisfies the reviewer (who then replaces the",
+    "    `thinking_face` with `+1`), or by applying the `review:auto-ok`",
+    "    label as an explicit override."
   ].join("\n")
 };
 var reviewPrSkill = {