@codedrifters/configulator 0.0.226 → 0.0.227

package/lib/index.js

@@ -6744,7 +6744,179 @@ var prReviewBundle = {
         "to a PR's branch \u2014 it only reviews, decides, and orchestrates merge",
         "or comment. In loop mode, a failed review for one PR never stops",
         "the loop; the reviewer comments and moves on. See the `pr-reviewer`",
-        "agent definition for the full phase-by-phase contract."
+        "agent definition for the full phase-by-phase contract.",
+        "",
+        "## Human-in-the-Loop Feedback Protocol",
+        "",
+        "The PR review pipeline is a **human-in-the-loop feedback loop**.",
+        "Reviewers (human or agent) leave comments on the PR; the",
+        "`pr-reviewer` sub-agent classifies each comment, reacts to it,",
+        "delegates in-scope fixes to `issue-worker`, and updates a single",
+        "sticky `## Reviewer notes` comment that is the canonical record of",
+        "PR state. The sections below document the conventions humans need",
+        "to read and drive that loop.",
+        "",
+        "### Trigger Model: Human-Triggered, Single-Pass",
+        "",
+        "Each reviewer pass runs exactly once and does not self-chain. A",
+        "human re-invokes `/review-pr <n>` (or `/review-prs`) whenever the",
+        "PR state changes enough to warrant another look \u2014 a new comment,",
+        "a new commit, a resolved pushback, a label flip. The reviewer",
+        "never reschedules itself and never loops back after handing off to",
+        "`issue-worker`: the worker's run is the terminal step of that",
+        "pass, and a human must re-invoke the reviewer to see the follow-up",
+        "reactions and the auto-merge re-enablement decision.",
+        "",
+        "This keeps the loop cheap to reason about: every agent action is",
+        "traceable to a specific human invocation, and there is no",
+        "background automation to pause or cancel.",
+        "",
+        "### Reaction State Machine",
+        "",
+        "The reviewer signals its disposition toward each human comment via",
+        "GitHub reactions on that comment. Five reactions carry meaning in",
+        "this workflow; every other reaction is ignored.",
+        "",
+        "| Reaction | Meaning | Terminal? |",
+        "|----------|---------|-----------|",
+        "| `eyes` | Seen by reviewer; no terminal decision yet. Queued for processing on this or a later pass. | No |",
+        "| `+1` | Reviewer accepted the comment's request; a fix has been queued or has already landed. | **Yes** |",
+        "| `rocket` | The accepted fix has landed on the branch. The reviewer's reply cites the commit SHA that applied it. | **Yes** |",
+        "| `thinking_face` | Reviewer pushback \u2014 the comment conflicts with an acceptance criterion, a CLAUDE.md convention, the project-context doc, or is ambiguous. **Blocks auto-merge** until resolved. | No |",
+        "| `-1` | Declined as out-of-scope. A separate tracking issue was created; the reviewer's reply links to it. | **Yes** |",
+        "",
+        "Terminal reactions (`+1`, `rocket`, `-1`) are applied **only after**",
+        "the corresponding action has truly completed \u2014 the fix accepted,",
+        "the commit landed on the branch, or the out-of-scope tracking",
+        "issue created and linked in a reply. The reviewer never applies a",
+        "terminal reaction pre-emptively.",
+        "",
+        "A comment carrying only `eyes` or `thinking_face` from the",
+        "reviewer is **non-terminal** and will be re-evaluated on the next",
+        "pass. A comment carrying any terminal reaction authored by the",
+        "reviewer is dropped from future classification.",
+        "",
+        "GitHub's reactions API uses `confused` as the content string for",
+        "the `thinking_face` reaction (`content=confused` when POSTing).",
+        "",
+        "### Resolving a Pushback",
+        "",
+        "When the reviewer pushes back on a comment with `thinking_face`,",
+        "auto-merge is blocked until the dispute is resolved. Humans have",
+        "three ways to clear a pushback:",
+        "",
+        "1. **Withdraw the comment.** Delete the comment, or edit out the",
+        "   disputed request, then re-invoke `/review-pr <n>`. The reviewer",
+        "   drops the withdrawn item from its queue on the next pass.",
+        "2. **Reply with clarification.** Post a reply on the same thread",
+        "   that addresses the reviewer's objection (cite the acceptance",
+        "   criterion you meant, supply the missing context, or concede the",
+        "   point). Re-invoke `/review-pr <n>` \u2014 the reviewer re-classifies",
+        "   the thread and may promote `thinking_face` to `+1` if the",
+        "   clarification satisfies it.",
+        "3. **Force through with `review:auto-ok`.** Apply the",
+        "   `review:auto-ok` label to the PR as an explicit maintainer",
+        "   override. The reviewer will log the override in the sticky",
+        "   `## Reviewer notes` comment and proceed with auto-merge even",
+        "   though the dispute was never resolved by reply or withdrawal.",
+        "",
+        "### Fix-List Comment Format",
+        "",
+        "When Phase 4 delegates in-scope fixes to `issue-worker`, it posts",
+        "a single PR-level comment whose body carries both a human-readable",
+        "checkbox summary and a fenced ```json fix-list``` block. The JSON",
+        "block is the authoritative payload the worker parses; the",
+        "checkbox list is for humans reading the PR.",
+        "",
+        "```markdown",
+        "## Reviewer: fix list for @issue-worker",
+        "",
+        "- [ ] @<author> \u2014 <instruction summary> (<file>:<line>)",
+        "",
+        "```json fix-list",
+        "{",
+        '  "pr": <pr-number>,',
+        '  "branch": "<head-ref-name>",',
+        '  "generated_at": "<ISO-8601 timestamp>",',
+        '  "items": [',
+        '    {"comment_id": "<id>", "author": "<login>", "file": "<path>", "line": <n>, "instruction": "<imperative instruction>"}',
+        "  ]",
+        "}",
+        "```",
+        "```",
+        "",
+        "Each `items[]` entry corresponds to one in-scope comment the",
+        "reviewer queued on this pass. The `comment_id` is preserved",
+        "exactly as returned by the GitHub API so that `issue-worker` can",
+        "report per-item outcomes and the reviewer can apply `rocket` or",
+        "`thinking_face` to the correct source comment on the next pass.",
+        "",
+        "### Sticky `## Reviewer notes` Comment",
+        "",
+        "Every PR has **one** canonical reviewer-notes comment. The",
+        "reviewer creates it on the first pass, then **edits it in place**",
+        "on every subsequent pass via",
+        "`gh api .../issues/comments/<id> -X PATCH`. It is never",
+        "duplicated and never replaced by a fresh per-pass summary.",
+        "",
+        "This sticky comment is the **single human-facing source of truth**",
+        "for the PR's current state. Humans scanning the PR should read",
+        "the sticky first, before scrolling back through individual threads.",
+        "It carries, at a minimum:",
+        "",
+        "- **Mode** \u2014 `auto-merge` or `human-required`, with the Phase 2.75",
+        "  reason that chose that mode.",
+        "- **AC status** \u2014 met, partial, or missing, with evidence links",
+        "  to files or tests.",
+        "- **CI status** \u2014 green, pending, or red.",
+        "- **Outstanding** \u2014 comments still carrying a non-terminal",
+        "  reviewer reaction (`eyes`, open `thinking_face`).",
+        "- **Pushbacks** \u2014 every unresolved `thinking_face` the reviewer",
+        "  has left, with the reason captured in its pushback reply.",
+        "- **Last pass** \u2014 the ISO 8601 timestamp of the most recent run.",
+        "",
+        "The sticky is updated on every pass \u2014 including passes that ended",
+        "in a pushback-gated skip, a `NEEDS_CHANGES` findings comment, or",
+        "a `human-required` hand-off \u2014 so it never goes stale while the",
+        "reviewer is actively processing the PR.",
+        "",
+        "### Label Glossary",
+        "",
+        "Five review-workflow labels drive the feedback loop. Consumers",
+        "that adopt this workflow are responsible for creating them in",
+        "their own repos (the same way they create `priority:*` and",
+        "`status:*` labels).",
+        "",
+        "| Label | Purpose |",
+        "|-------|---------|",
+        "| `origin:issue-worker` | PR was opened by the `issue-worker` agent. Eligible for auto-delegation of in-scope fixes. Human-authored PRs lack this label and will not trigger delegation unless the reviewer is invoked with `--allow-human-author`. |",
+        "| `review:human-required` | Force human review regardless of what the policy would otherwise decide. The reviewer never enables auto-merge on a PR carrying this label. |",
+        "| `review:auto-ok` | Force auto-merge regardless of what the policy would otherwise decide. **Also resolves outstanding `thinking_face` pushbacks** as an explicit maintainer override; the reviewer logs the override in the sticky summary. |",
+        "| `review:awaiting-human` | Set by the reviewer when it completes its work on a `human-required` PR and is handing off the final merge decision. Cleared by a human (or by `review:auto-ok` flipping the PR back to `auto-merge` mode). |",
+        "| `review:fixing` | Short-lived lease held by the reviewer while an `issue-worker` feedback-mode delegation is mid-run. Released automatically at the end of Phase 4 step (g). Contention on this label means a prior delegation crashed without releasing it and needs human investigation. |",
+        "",
+        "### Reviewing Human-Authored PRs: the `--allow-human-author` Flag",
+        "",
+        "By default the reviewer only **delegates** in-scope fixes on",
+        "bot-authored PRs \u2014 those carrying the `origin:issue-worker`",
+        "label. Running `/review-pr <n>` or `/review-prs` on a",
+        "human-authored PR still produces a full review (reactions,",
+        "replies, sticky summary, and auto-merge when the policy allows",
+        "it) but skips the delegation hand-off to `issue-worker` \u2014 the",
+        "human author is expected to apply the fixes themselves.",
+        "",
+        "Pass `--allow-human-author` to opt into delegation on",
+        "human-authored PRs for a single invocation:",
+        "",
+        "```",
+        "/review-pr <pr-number> --allow-human-author",
+        "/review-prs --allow-human-author",
+        "```",
+        "",
+        "The flag does **not** persist across invocations. Subsequent",
+        "invocations return to the bot-only default and require the flag",
+        "to be re-supplied if delegation on a human-authored PR is desired",
+        "again."
       ].join("\n"),
       platforms: {
         cursor: { exclude: true }