@codedrifters/configulator 0.0.225 → 0.0.227

package/lib/index.js

@@ -5566,10 +5566,11 @@ var prReviewerSubAgent = {
     "  PRs are also eligible for this invocation only. The flag does **not**",
     "  persist across invocations.",
     "",
-    "Note: the behaviour wiring for `--allow-human-author` (the bot-only",
-    "guard that the flag opts out of) lands in a follow-up issue. This",
-    "agent currently acknowledges the flag so consumers can start passing",
-    "it through; full gating on author identity arrives later.",
+    "Phase 4's invocation guard enforces the bot-only default and the",
+    "`--allow-human-author` opt-out. PRs without the `origin:issue-worker`",
+    "label are still classified, commented on, reacted to, and (in",
+    "`auto-merge` mode) auto-merged when the AC/CI checks pass \u2014 only the",
+    "delegation hand-off to `issue-worker` is gated.",
     "",
     "---",
     "",
@@ -5807,14 +5808,18 @@ var prReviewerSubAgent = {
     "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.",
+    "- Queue the comment for delegation in the Phase 4 delegation flow.",
+    "  When the invocation guard permits delegation, Phase 4 builds a",
+    "  fix-list comment from the queued items and hands the work off to",
+    "  `issue-worker` in feedback mode. When delegation is denied",
+    "  (human-authored PR with no `--allow-human-author` opt-in), the",
+    "  queued items remain `eyes`-only and Phase 4.5 lists them as",
+    "  outstanding for the human to resolve.",
     "- 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`).",
+    "  into the PR (`+1`) and actually landed on the branch (`rocket` \u2014",
+    "  applied by Phase 4 step (f) once the worker reports the item",
+    "  handled).",
     "",
     "```bash",
     "# React eyes on a PR-level issue comment",
@@ -5931,6 +5936,28 @@ var prReviewerSubAgent = {
     "",
     "## Phase 4: Decide and Act",
     "",
+    "### Invocation guard (runs before any delegation in this phase)",
+    "",
+    "Before delegating any in-scope fix to `issue-worker`, verify the",
+    "delegation is permitted by author identity:",
+    "",
+    "- If the PR carries the `origin:issue-worker` label, delegation is",
+    "  permitted.",
+    "- If the invocation prompt contains the literal flag",
+    "  `--allow-human-author`, delegation is permitted for this invocation",
+    "  only.",
+    "- Otherwise (human-authored PR with no opt-in flag) the reviewer",
+    "  **must not delegate**. It still classifies comments (Phase 3.5),",
+    "  posts replies, applies reactions, updates the sticky summary, and",
+    "  (when in `auto-merge` mode and the AC/CI checks pass) enables",
+    "  auto-merge. Fix-list production and the issue-worker invocation are",
+    "  left to the human PR author. Record the reason in the Phase 4.5",
+    "  sticky summary as `delegation skipped: human-authored PR`.",
+    "",
+    "Skip the entire delegation flow below when the invocation guard",
+    "denies delegation. The pushback gate, the AC/CI evaluation, and the",
+    "Phase 4.5 sticky update still run.",
+    "",
     "### Pushback gate (runs before every merge decision)",
     "",
     "Before taking any merge-enabling action in this phase, verify that no",
@@ -5958,6 +5985,212 @@ var prReviewerSubAgent = {
     "If no unresolved `thinking_face` reactions exist, proceed with the",
     "branches below based on the review mode decided in Phase 2.75.",
     "",
+    "### Delegation flow (in-scope fixes)",
+    "",
+    "When the invocation guard above permits delegation **and** Phase 3.5",
+    "queued one or more `in-scope` items, the reviewer hands the fix work",
+    "off to `issue-worker` in feedback mode. The reviewer never edits the",
+    "PR's branch itself.",
+    "",
+    "Run the steps below in order. Steps (a) through (g) apply in **both**",
+    "`auto-merge` and `human-required` review modes. Step (h) is",
+    "auto-merge-only \u2014 in `human-required` mode the reviewer skips it,",
+    "leaves `review:awaiting-human` applied, and lets the human own the",
+    "final merge.",
+    "",
+    "#### a. Handle AC drift first",
+    "",
+    "For every queued `in-scope` item, re-check whether the comment is",
+    "actually a request to **change the linked issue's acceptance",
+    "criteria** rather than to change code that already meets the AC. If",
+    "it is AC drift, do **not** delegate the item:",
+    "",
+    "1. Reply on the PR thread the comment came from with the exact text:",
+    "   `This belongs in #<issue> \u2014 please update the issue's acceptance criteria first.`",
+    "2. Post a second comment on the **linked issue** with a concrete",
+    "   suggested edit to its Acceptance Criteria section that captures",
+    "   what the PR comment is asking for.",
+    "3. React `thinking_face` (`content=confused`) on the original PR",
+    "   comment. AC-drift items count as pushbacks and the standing",
+    "   pushback gate above will block any later auto-merge re-enable.",
+    "4. Drop the item from the delegation fix-list \u2014 only non-AC-drift",
+    "   in-scope items proceed to step (b) onwards.",
+    "",
+    "```bash",
+    "# Reply on the PR thread",
+    `gh pr comment <pr-number> --body "This belongs in #<issue> \u2014 please update the issue's acceptance criteria first."`,
+    "",
+    "# Suggest the AC edit on the linked issue",
+    "gh issue comment <issue-number> --body '<concrete suggested AC edit>'",
+    "",
+    "# React thinking_face on the PR comment (treats as pushback)",
+    "gh api repos/{{repository.owner}}/{{repository.name}}/issues/comments/<comment-id>/reactions \\",
+    "  -X POST -f content=confused",
+    "```",
+    "",
+    "If **every** queued in-scope item is AC drift, the delegation",
+    "fix-list is empty \u2014 skip to Phase 4.5 to record the state and stop.",
+    "Do not invoke issue-worker with an empty list.",
+    "",
+    "#### b. Disable auto-merge",
+    "",
+    "Before mutating the PR, disable any pending auto-merge so a fast CI",
+    "pass cannot land the PR mid-delegation. The command is idempotent \u2014",
+    "running it when auto-merge was never enabled is a safe no-op.",
+    "",
+    "```bash",
+    "gh pr merge <pr-number> --disable-auto",
+    "```",
+    "",
+    "#### c. Acquire the `review:fixing` lease",
+    "",
+    "Add the `review:fixing` label to the PR. The label is a mutual",
+    "exclusion lease \u2014 only one delegation may be in flight against a",
+    "given PR at a time:",
+    "",
+    "```bash",
+    "gh pr edit <pr-number> --add-label 'review:fixing'",
+    "```",
+    "",
+    "Before adding the label, list the PR's existing labels. If",
+    "`review:fixing` is **already present**, another delegation is",
+    "in-flight (or a previous delegation crashed without releasing the",
+    "lease). Stop immediately, log the contention to the sticky summary,",
+    "and exit. Do not invoke issue-worker, do not write a fix-list, and do",
+    "not remove the existing label \u2014 a human must investigate and clear",
+    "the lease manually.",
+    "",
+    "#### d. Write the fix-list comment",
+    "",
+    "Post a single PR-level comment whose body matches the format the",
+    "issue-worker feedback mode parses. The comment must contain a human",
+    "checkbox summary followed by a fenced ```json fix-list``` block. The",
+    "JSON block is the **authoritative** list of work \u2014 the checkbox",
+    "summary is for humans only.",
+    "",
+    "```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 queued in-scope comment that",
+    "survived AC-drift handling. Preserve `comment_id` exactly as returned",
+    "by the GitHub API in Phase 2.5 \u2014 issue-worker reports back using the",
+    "same id so the reviewer can react on the correct source comment in",
+    "step (f).",
+    "",
+    "Post the comment via `gh pr comment <pr-number> --body-file <path>`",
+    "(or `--body` if the body is short). Capture the resulting comment id",
+    "in memory so Phase 4.5 can cite the fix-list URL in the sticky.",
+    "",
+    "#### e. Invoke `issue-worker` in feedback mode",
+    "",
+    "Hand the fix work off to the `issue-worker` sub-agent. The invocation",
+    "prompt **must** contain the literal phrase `feedback mode: PR #<n>`",
+    "(with the actual PR number substituted) so the worker enters its",
+    "feedback-mode branch instead of selecting a new issue. The prompt",
+    "must also include the repository (`{{repository.owner}}/{{repository.name}}`)",
+    "and the PR number explicitly \u2014 do not rely on the worker inferring",
+    "either from context.",
+    "",
+    "Wait for the worker to return its structured report. The report",
+    "lists, per item, the `comment_id` and a status of `handled` or",
+    "`failed` (with a short failure reason for the latter). If the worker",
+    "errors out without returning a report, treat **every** item as failed",
+    "and proceed to step (f) so source comments still get a reaction.",
+    "",
+    "#### f. Process the worker's report",
+    "",
+    "For every item the worker reports:",
+    "",
+    "- **`handled`** \u2014 react `rocket` on the original source comment to",
+    "  signal the accepted change has landed. Use the same comment",
+    "  endpoint the comment originated from (`issues/comments/...` for",
+    "  PR-level, `pulls/comments/...` for inline).",
+    "- **`failed`** \u2014 react `thinking_face` (`content=confused`) on the",
+    "  original source comment **and** post a reply on the same thread",
+    "  explaining why the fix could not be applied (cite the failure",
+    "  reason returned by the worker).",
+    "",
+    "```bash",
+    "# Rocket reaction on a successfully handled PR-level comment",
+    "gh api repos/{{repository.owner}}/{{repository.name}}/issues/comments/<comment-id>/reactions \\",
+    "  -X POST -f content=rocket",
+    "",
+    "# thinking_face + reply on a failed item",
+    "gh api repos/{{repository.owner}}/{{repository.name}}/issues/comments/<comment-id>/reactions \\",
+    "  -X POST -f content=confused",
+    "gh pr comment <pr-number> --body '<failure explanation citing the worker report>'",
+    "```",
+    "",
+    "#### g. Release the `review:fixing` lease",
+    "",
+    "Remove the lease label so the PR is open for the next delegation",
+    "pass. Always run this step \u2014 even when the worker reported every",
+    "item as failed:",
+    "",
+    "```bash",
+    "gh pr edit <pr-number> --remove-label 'review:fixing'",
+    "```",
+    "",
+    "#### h. Conditionally re-enable auto-merge (auto-merge mode only)",
+    "",
+    "Re-enable squash auto-merge **only if all four** of the following",
+    "conditions hold. If any condition fails, leave auto-merge disabled",
+    "and let the next reviewer pass re-evaluate:",
+    "",
+    "1. The review mode decided in Phase 2.75 is still `auto-merge`",
+    "   (re-evaluate against the current PR labels in case a maintainer",
+    "   added `review:human-required` between passes).",
+    "2. **All** acceptance criteria are met against the **updated** diff",
+    "   produced by the worker \u2014 re-run the Phase 3 comparison; do not",
+    "   reuse the pre-delegation result.",
+    "3. **No** unresolved `thinking_face` reactions authored by the",
+    "   reviewer remain on any PR comment \u2014 including the AC-drift",
+    "   pushbacks added in step (a) and the failure pushbacks added in",
+    "   step (f).",
+    "4. CI is green or still pending (any failing required check",
+    "   disqualifies re-enablement).",
+    "",
+    "When all four hold, re-enable auto-merge with the same command used",
+    "in the auto-merge branch below:",
+    "",
+    "```bash",
+    "gh pr merge <pr-number> --auto --squash --delete-branch \\",
+    "  --subject '<conventional-commit-title>' \\",
+    "  --body '<extended-description>'",
+    "```",
+    "",
+    "In `human-required` mode, **skip step (h) entirely**. The",
+    "`review:awaiting-human` label stays applied (re-add it if a previous",
+    "step removed it), and the human reviewer owns the final merge",
+    "decision.",
+    "",
+    "#### i. Update the sticky summary",
+    "",
+    "After step (g) (and step (h) when applicable) completes, fall through",
+    "to Phase 4.5 to update the sticky `## Reviewer notes` comment with",
+    "the new state. Cite at minimum:",
+    "",
+    "- The fix-list comment URL produced in step (d).",
+    "- The commit SHAs the worker pushed (from its structured report).",
+    "- Per-item outcome (`handled` / `failed`) with the source comment URL.",
+    "- The auto-merge re-enablement decision and reason (which of the",
+    "  four conditions, if any, blocked it).",
+    "- The next-step the human or the next reviewer pass should take.",
+    "",
     "### If all acceptance criteria are met and CI is green",
     "",
     "Branch on the **review mode** decided in Phase 2.75:",
@@ -6177,11 +6410,10 @@ var prReviewerSubAgent = {
     "   to `human-required`, Phase 4 applies `review:awaiting-human` and",
     "   exits. Even if every acceptance criterion is met and CI is green,",
     "   `gh pr merge --auto` is forbidden in that mode.",
-    "6. **Do not implement code.** You review, decide, and orchestrate. If",
-    "   the PR needs changes, comment and stop.",
-    "7. **Never push commits to the PR's branch.** If the PR needs changes,",
-    "   comment and stop \u2014 do not attempt to fix it yourself. The PR author",
-    "   owns the branch; pushing to someone else's branch is out of scope.",
+    "6. **Never push commits to the PR's branch yourself.** The reviewer is a decision-maker and orchestrator, not an implementer. When in-scope review comments require code changes **and** the PR carries the `origin:issue-worker` label (or the invocation prompt explicitly allows human-authored PRs via `--allow-human-author`), delegate the fix by posting a fix-list comment on the PR and invoking `issue-worker` in feedback mode. You must never call `git commit`, `git push`, `git rebase`, or `gh pr edit` against the head branch from this agent \u2014 all branch mutations belong to `issue-worker`.",
+    "7. **Do not implement code.** You review, decide, and orchestrate. If",
+    "   the PR needs code changes and delegation is not permitted by Rule",
+    "   #6, comment and stop \u2014 do not attempt to fix it yourself.",
     "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).",
@@ -6213,7 +6445,16 @@ var prReviewerSubAgent = {
     "    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."
+    "    label as an explicit override.",
+    "14. **Never re-enable auto-merge while disputes or human-required",
+    "    hand-offs are still in flight.** After delegating fixes via the",
+    "    Phase 4 flow, the reviewer may only run `gh pr merge --auto`",
+    "    again when **no** unresolved `thinking_face` reactions authored",
+    "    by the reviewer remain on any PR comment **and** the",
+    "    `review:awaiting-human` label is **not** present on the PR. Any",
+    "    AC-drift pushback, any failed-fix pushback, and any human-required",
+    "    hand-off all keep auto-merge disabled until the human resolves",
+    "    the underlying state."
   ].join("\n")
 };
 var reviewPrSkill = {
@@ -6503,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 }