@codedrifters/configulator 0.0.224 → 0.0.226

package/lib/index.js

@@ -4299,7 +4299,7 @@ var issueWorkerSubAgent = {
   name: "issue-worker",
   description: "Selects the next ready issue from the queue, claims it, and implements the change end-to-end following repository conventions",
   model: AGENT_MODEL.POWERFUL,
-  maxTurns: 50,
+  maxTurns: 100,
   canDelegateToAgents: [],
   platforms: { cursor: { exclude: true } },
   prompt: [
@@ -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 = {