@codedrifters/configulator 0.0.220 → 0.0.222

package/lib/index.mjs

@@ -4362,8 +4362,14 @@ var issueWorkerSubAgent = {
     "",
     "## Phase 7: Open a PR",
     "",
+    "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:",
+    "",
     "```bash",
-    'gh pr create --title "<type>(<scope>): <description>" --body "## Summary',
+    'gh pr create --title "<type>(<scope>): <description>" \\',
+    "  --label 'origin:issue-worker' \\",
+    '  --body "## Summary',
     "",
     "<bullet points>",
     "",
@@ -4415,7 +4421,12 @@ var issueWorkerSubAgent = {
     "3. **Follow CLAUDE.md conventions** for branch naming, commits, and PRs.",
     "4. **Do not assign PRs to a project board** \u2014 this repo has no GitHub project.",
     "5. **Do not add AI co-author** attribution to commits.",
-    "6. **On failure:** If you cannot complete the issue, update labels and leave a comment:",
+    "6. **Always label PRs with `origin:issue-worker`.** Every PR opened by",
+    "   the issue-worker must carry the `origin:issue-worker` label so",
+    "   downstream agents (notably the `pr-reviewer`) can identify",
+    "   bot-authored PRs. Pass `--label 'origin:issue-worker'` on every",
+    "   `gh pr create` call.",
+    "7. **On failure:** If you cannot complete the issue, update labels and leave a comment:",
     "   ```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>"',
@@ -5294,6 +5305,25 @@ var prReviewerSubAgent = {
     "---",
     "",
     ...PROJECT_CONTEXT_READER_SECTION,
+    "## Invocation Flags",
+    "",
+    "Your invocation prompt may include flags that modify how you select and",
+    "process PRs. Parse the prompt for these flags before starting Phase 1:",
+    "",
+    "- **`--allow-human-author`** \u2014 opt-in flag that allows the reviewer to",
+    "  process PRs authored by humans in addition to bot-authored PRs",
+    "  (those carrying the `origin:issue-worker` label). When absent, the",
+    "  reviewer only processes bot-authored PRs; when present, human-authored",
+    "  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 1: Identify the PR",
     "",
     "If a PR number was provided in your instructions, use that. Otherwise stop",
@@ -5332,7 +5362,7 @@ var prReviewerSubAgent = {
     "## Phase 2: Gather Context",
     "",
     "```bash",
-    "gh pr view <pr-number> --json number,title,body,headRefName,baseRefName,isDraft,state,labels,reviews",
+    "gh pr view <pr-number> --json number,title,body,headRefName,baseRefName,isDraft,state,labels,reviews,files,additions,deletions",
     "gh pr diff <pr-number>",
     "gh pr checks <pr-number>",
     "```",
@@ -5340,12 +5370,84 @@ var prReviewerSubAgent = {
     "Extract the linked issue number from the PR body using the closing keywords",
     "(`Closes #N`, `Fixes #N`, or `Resolves #N`) identified in Phase 1.5.",
     "",
-    "Then fetch the linked issue:",
+    "Then fetch the linked issue, including its `issueType` so Phase 2.75 can",
+    "evaluate the issue-type portion of the review policy:",
     "",
     "```bash",
-    "gh issue view <issue-number>",
+    "gh issue view <issue-number> --json number,title,body,labels,state,issueType",
+    "```",
+    "",
+    "## Phase 2.75: Determine Review Mode",
+    "",
+    "Before comparing the diff to the acceptance criteria, evaluate the PR",
+    "against the **PR Review Policy** embedded in this repository's",
+    "`CLAUDE.md` (rendered from the `pr-review-policy` rule). The decision",
+    "here governs whether Phase 4 enables auto-merge or hands off to a",
+    "human reviewer.",
+    "",
+    "### Step 1: Load the policy",
+    "",
+    "Read `CLAUDE.md` from the repo root and extract the fenced YAML block",
+    "under the `## PR Review Policy` heading. Parse the block into an",
+    "in-memory object with the following top-level fields: `version`,",
+    "`default`, `human-required`, `auto-merge`.",
+    "",
+    "If the policy section is missing or unparseable, fall back to",
+    "`mode = human-required` with `reason = 'policy missing or unreadable'`",
+    "and skip to Step 3. Do **not** auto-merge when the policy is absent.",
+    "",
+    "### Step 2: Evaluate in precedence order",
+    "",
+    "Walk the following checks in order. The **first match wins** and fixes",
+    "the mode; record the triggering condition as the `reason`. Mixed-match",
+    "PRs (signals from both sides) resolve conservatively to",
+    "`human-required` \u2014 force-auto only wins when it is the single highest",
+    "match and no later human-required signal changes the outcome under",
+    "step 2c.",
+    "",
+    "1. **Force-auto label** \u2014 if the PR carries any label listed under",
+    "   `auto-merge.labels-that-force-auto` (e.g. `review:auto-ok`), set",
+    "   `mode = auto-merge`.",
+    "2. **Force-human label (reserved)** \u2014 if the PR carries a",
+    "   `review:human-required` label, set `mode = human-required`.",
+    "3. **Labels that force human** \u2014 if the PR carries any label listed",
+    "   under `human-required.labels-that-force-human` (e.g.",
+    "   `priority:critical`), set `mode = human-required`.",
+    "4. **Path globs** \u2014 if any file in the PR diff matches any glob in",
+    "   `human-required.paths`, set `mode = human-required`. Record the",
+    "   first matching path + glob pair as the reason.",
+    "5. **Issue type** \u2014 if the linked issue's GitHub issue type",
+    "   (fetched in Phase 2) matches any entry in",
+    "   `human-required.issue-types` (case-insensitive), set",
+    "   `mode = human-required`.",
+    "6. **Size thresholds** \u2014 if the PR exceeds either threshold under",
+    "   `human-required.size` (`files` count or `insertions` count), set",
+    "   `mode = human-required`.",
+    "7. **Default** \u2014 if no rule above matched, apply the `default` field",
+    "   from the policy (typically `auto-merge`).",
+    "",
+    "#### Mixed-match resolution",
+    "",
+    "Apart from rule (1), which is an explicit opt-in and wins outright,",
+    "**any** match from rules (2) through (6) forces `human-required` even",
+    "if a non-force-auto signal would otherwise have allowed auto-merge.",
+    "The conservative choice wins. Rule (1) is the sole escape hatch and",
+    "requires a maintainer to have applied the force-auto label.",
+    "",
+    "### Step 3: Record the decision",
+    "",
+    "Persist the evaluated mode and reason for later phases so Phase 4 and",
+    "any downstream summary writer can cite it:",
+    "",
+    "```",
+    "Review mode: <auto-merge | human-required>",
+    "Reason: <short explanation \u2014 label name, path+glob, issue type, size threshold, default>",
     "```",
     "",
+    "Phases 3 (acceptance-criteria comparison) and CI verification run",
+    "unchanged regardless of mode. Only the terminal action in Phase 4",
+    "branches on the decided mode.",
+    "",
     "## Phase 3: Compare Diff to Acceptance Criteria",
     "",
     "Read the issue body for an **Acceptance Criteria** (or equivalent) section.",
@@ -5367,6 +5469,10 @@ var prReviewerSubAgent = {
     "",
     "### If all acceptance criteria are met and CI is green",
     "",
+    "Branch on the **review mode** decided in Phase 2.75:",
+    "",
+    "#### Mode `auto-merge`",
+    "",
     "Enable squash auto-merge with branch deletion. This queues the merge to",
     "happen once required checks pass; no separate approval review is needed.",
     "",
@@ -5380,6 +5486,27 @@ var prReviewerSubAgent = {
     "`feat(scope): description`). The body should bullet the changes and end",
     "with `Closes #<issue-number>`.",
     "",
+    "#### Mode `human-required`",
+    "",
+    "Do **not** run `gh pr merge --auto`. Instead, hand the PR off to a",
+    "human reviewer:",
+    "",
+    "1. Apply the `review:awaiting-human` label so the PR is discoverable",
+    "   in the human-review queue:",
+    "",
+    "   ```bash",
+    "   gh pr edit <pr-number> --add-label 'review:awaiting-human'",
+    "   ```",
+    "",
+    "2. Exit cleanly after the acceptance-criteria check completes and any",
+    "   summary comment the reviewer posts. Proceed to Phase 5 only if a",
+    "   merge occurred \u2014 in `human-required` mode the reviewer stops at",
+    "   the hand-off and does not poll for merge.",
+    "",
+    "The reason captured in Phase 2.75 should be included in any summary",
+    "comment so maintainers know why human review was required (path hit,",
+    "issue type, size threshold, label, or default).",
+    "",
     "### If any criterion is missing, partial, or CI is failing",
     "",
     "Post a plain comment (not a formal review block) with grouped findings:",
@@ -5399,8 +5526,12 @@ var prReviewerSubAgent = {
     "",
     "## Phase 5: Branch Cleanup and Issue Closure Verification",
     "",
-    "Auto-merge may not be immediate. Poll the PR state up to 10 times, waiting",
-    "30 seconds between polls:",
+    "Skip this phase entirely when the review mode from Phase 2.75 is",
+    "`human-required` \u2014 no merge was initiated, so there is nothing to poll",
+    "and no branch to clean up. Report the hand-off and stop.",
+    "",
+    "In `auto-merge` mode, auto-merge may not be immediate. Poll the PR",
+    "state up to 10 times, waiting 30 seconds between polls:",
     "",
     "```bash",
     "gh pr view <pr-number> --json state --jq '.state'",
@@ -5443,7 +5574,9 @@ var prReviewerSubAgent = {
     "```",
     "PR #<number> \u2014 <title>",
     "Linked issue: #<issue-number>",
-    "Verdict: AUTO_MERGE_ENABLED | NEEDS_CHANGES | INELIGIBLE | BLOCKED",
+    "Review mode: <auto-merge | human-required>",
+    "Reason: <short explanation from Phase 2.75>",
+    "Verdict: AUTO_MERGE_ENABLED | AWAITING_HUMAN | NEEDS_CHANGES | INELIGIBLE | BLOCKED",
     "",
     "Acceptance criteria:",
     "  [x] <criterion> \u2014 <evidence>",
@@ -5455,7 +5588,7 @@ var prReviewerSubAgent = {
     "  - Suggested: <items>",
     "  - Nitpick: <items>",
     "",
-    "Action taken: <enable-auto-merge | commented-on-the-pr | none>",
+    "Action taken: <enable-auto-merge | label-awaiting-human | commented-on-the-pr | none>",
     "Branch state: <merged | open | closed>",
     "Issue state: <closed | open>",
     "```",
@@ -5473,15 +5606,19 @@ var prReviewerSubAgent = {
     "   block on red checks.",
     "4. **Never bypass review conventions.** Always use `--squash`, `--auto`,",
     "   and `--delete-branch` for merges. Do not force-merge.",
-    "5. **Do not implement code.** You review, decide, and orchestrate. If",
+    "5. **Never auto-merge a `human-required` PR.** When Phase 2.75 resolves",
+    "   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.",
-    "6. **Never push commits to the PR's branch.** If the PR needs changes,",
+    "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.",
-    "7. **In loop mode (`/review-prs`), never stop early.** If any review",
+    "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).",
-    "8. **Follow CLAUDE.md conventions** for all `git` and `gh` operations."
+    "9. **Follow CLAUDE.md conventions** for all `git` and `gh` operations."
   ].join("\n")
 };
 var reviewPrSkill = {
@@ -5500,7 +5637,16 @@ var reviewPrSkill = {
     "",
     "## Usage",
     "",
-    "/review-pr <pr-number>",
+    "/review-pr <pr-number> [--allow-human-author]",
+    "",
+    "### Flags",
+    "",
+    "- **`--allow-human-author`** \u2014 opt the reviewer into processing",
+    "  human-authored PRs for **this invocation only**. By default, the",
+    "  reviewer only processes bot-authored PRs (those carrying the",
+    "  `origin:issue-worker` label); pass this flag to review a",
+    "  human-authored PR. The flag does not persist \u2014 subsequent",
+    "  invocations return to the bot-only default.",
     "",
     "## What This Skill Does",
     "",
@@ -5515,6 +5661,10 @@ var reviewPrSkill = {
     "9. After merge, verifies the linked issue is closed and closes it if not",
     "10. Cleans up the local branch after merge",
     "",
+    "Passing `--allow-human-author` opts the reviewer into processing",
+    "human-authored PRs for this invocation only (the default scope is",
+    "bot-authored PRs labeled `origin:issue-worker`).",
+    "",
     "## Input",
     "",
     "Provide the PR number to review. The skill resolves the linked issue from",
@@ -5549,7 +5699,16 @@ var reviewPrsSkill = {
     "",
     "## Usage",
     "",
-    "/review-prs",
+    "/review-prs [--allow-human-author]",
+    "",
+    "### Flags",
+    "",
+    "- **`--allow-human-author`** \u2014 opt the reviewer into processing",
+    "  human-authored PRs for **this invocation only**. By default, the",
+    "  loop only processes bot-authored PRs (those carrying the",
+    "  `origin:issue-worker` label); pass this flag to include",
+    "  human-authored PRs in the queue. The flag does not persist \u2014",
+    "  subsequent invocations return to the bot-only default.",
     "",
     "## What This Skill Does",
     "",
@@ -5594,6 +5753,10 @@ var reviewPrsSkill = {
     "When no eligible PRs remain, emit a final summary listing every PR",
     "processed and the verdict for each, then stop.",
     "",
+    "Passing `--allow-human-author` opts the reviewer into including",
+    "human-authored PRs in the queue for this invocation only (the default",
+    "scope is bot-authored PRs labeled `origin:issue-worker`).",
+    "",
     "## Output",
     "",
     "Per-PR structured report (same shape as `/review-pr`), followed by a",
@@ -5623,6 +5786,88 @@ var prReviewBundle = {
   // still exclude it explicitly via `excludeBundles` if desired.
   appliesWhen: () => true,
   rules: [
+    {
+      name: "pr-review-policy",
+      description: "Declarative policy that tells the pr-reviewer which PRs may auto-merge and which must wait for a human reviewer",
+      scope: AGENT_RULE_SCOPE.ALWAYS,
+      content: [
+        "# PR Review Policy",
+        "",
+        "The `pr-reviewer` sub-agent evaluates every PR it reviews against the",
+        "policy below and routes the PR into one of two modes:",
+        "",
+        "- **`auto-merge`** \u2014 the reviewer may enable squash auto-merge once",
+        "  all acceptance criteria are met and CI is green.",
+        "- **`human-required`** \u2014 the reviewer runs the full AC/CI check but",
+        "  never calls `gh pr merge --auto`. It applies the",
+        "  `review:awaiting-human` label and hands off to a human reviewer.",
+        "",
+        "## Policy",
+        "",
+        "```yaml",
+        "version: 1",
+        "default: auto-merge",
+        "",
+        "human-required:",
+        "  paths:",
+        '    - "docs/adrs/**"',
+        '    - "docs/project-context.md"',
+        '    - ".github/workflows/**"',
+        '    - ".github/CODEOWNERS"',
+        '    - ".projenrc.ts"',
+        '    - "projenrc/**"',
+        '    - "CLAUDE.md"',
+        '    - ".claude/**"',
+        '    - "packages/**/package.json"',
+        "  issue-types:",
+        "    - release",
+        "    - hotfix",
+        "  size:",
+        "    files: 10",
+        "    insertions: 500",
+        "  labels-that-force-human:",
+        '    - "review:human-required"',
+        '    - "priority:critical"',
+        "",
+        "auto-merge:",
+        "  labels-that-force-auto:",
+        '    - "review:auto-ok"',
+        "```",
+        "",
+        "## Precedence",
+        "",
+        "The reviewer walks the following checks in order. The **first match**",
+        "fixes the mode; any mixed-match PR (signals from both sides) resolves",
+        "conservatively to `human-required` \u2014 `auto-merge` only wins when the",
+        "force-auto label is the single top-priority match.",
+        "",
+        "1. **`auto-merge.labels-that-force-auto`** \u2014 if the PR carries any of",
+        "   these labels (e.g. `review:auto-ok`), the mode is `auto-merge`",
+        "   outright. This is the only escape hatch from the conservative",
+        "   default; it requires a maintainer to apply the label explicitly.",
+        "2. **`review:human-required` label** \u2014 reserved force-human label;",
+        "   if present (and no force-auto label beat it in step 1), the mode",
+        "   is `human-required`.",
+        "3. **`human-required.labels-that-force-human`** \u2014 any listed label on",
+        "   the PR (e.g. `priority:critical`) forces `human-required`.",
+        "4. **`human-required.paths`** \u2014 if any file in the PR diff matches",
+        "   any glob here, the mode is `human-required`. Matching uses",
+        "   standard glob semantics (`**` for recursive directories,",
+        "   `*` for a single path segment).",
+        "5. **`human-required.issue-types`** \u2014 if the linked issue's GitHub",
+        "   issue type matches any entry (case-insensitive), the mode is",
+        "   `human-required`.",
+        "6. **`human-required.size`** \u2014 if the PR exceeds either the `files`",
+        "   count or the `insertions` count, the mode is `human-required`.",
+        "7. **`default`** \u2014 applied only when no rule above matched",
+        "   (normally `auto-merge`).",
+        "",
+        "The `pr-reviewer` sub-agent records the decided mode and the triggering",
+        "reason in its Phase 2.75 output so downstream phases and any sticky",
+        "summary can cite the specific rule that applied."
+      ].join("\n"),
+      tags: ["policy", "review"]
+    },
     {
       name: "pr-review-workflow",
       description: "Describes the /review-pr and /review-prs skills and their delegation to the pr-reviewer sub-agent",
@@ -5643,15 +5888,21 @@ var prReviewBundle = {
         "   has a linked issue). Ineligible PRs get a short comment and are",
         "   skipped.",
         "2. Fetches the PR, its diff, CI status, and the linked issue",
-        "3. Builds a checklist from the issue's acceptance criteria",
-        "4. Verifies the diff satisfies each criterion and that CI is green",
-        "5. **Enables squash auto-merge** (with `--delete-branch`) when all",
-        "   checks pass \u2014 no explicit approval review",
-        "6. **Comments with grouped findings** when any check fails (plain",
+        "3. **Evaluates the PR Review Policy** (see the `PR Review Policy`",
+        "   section above) to decide whether the PR is `auto-merge` or",
+        "   `human-required`, and records the triggering reason",
+        "4. Builds a checklist from the issue's acceptance criteria",
+        "5. Verifies the diff satisfies each criterion and that CI is green",
+        "6. **Enables squash auto-merge** (with `--delete-branch`) when all",
+        "   checks pass **and** the review mode is `auto-merge`",
+        "7. **Applies `review:awaiting-human`** and hands off to a human",
+        "   reviewer when the review mode is `human-required` (no auto-merge,",
+        "   even if every acceptance criterion is met)",
+        "8. **Comments with grouped findings** when any check fails (plain",
         "   `gh pr comment`, not a formal `--request-changes` review)",
-        "7. After a successful merge, verifies the linked issue is closed",
+        "9. After a successful merge, verifies the linked issue is closed",
         "   and closes it explicitly if the merge commit did not",
-        "8. Cleans up the local branch after merge",
+        "10. Cleans up the local branch after merge",
         "",
         "The reviewer **never** implements code and **never** pushes commits",
         "to a PR's branch \u2014 it only reviews, decides, and orchestrates merge",