@codedrifters/configulator 0.0.222 → 0.0.223

package/lib/index.js

@@ -5454,6 +5454,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",
@@ -5542,8 +5617,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:",
@@ -5601,6 +5843,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",
@@ -5695,7 +6013,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 = {