@codedrifters/configulator 0.0.226 → 0.0.228

package/lib/index.js

@@ -2267,6 +2267,148 @@ var companyProfileBundle = {
 
 // src/agent/bundles/github-workflow.ts
 var import_github = require("projen/lib/github");
+var setIssueTypeProcedure = {
+  name: "set-issue-type.sh",
+  description: "Assign a GitHub issue type (Feature / Task / Epic / Bug / etc.) via the updateIssueIssueType GraphQL mutation in a single step",
+  content: [
+    "#!/usr/bin/env bash",
+    "# set-issue-type.sh \u2014 Assign a GitHub issue type in one step.",
+    "#",
+    "# Wraps the two-step GraphQL flow used to set an issue's type:",
+    "#   1. Look up the repo's issue type node IDs.",
+    "#   2. Call the updateIssueIssueType mutation.",
+    "#",
+    "# Usage:",
+    "#   .claude/procedures/set-issue-type.sh <issue-number> <type-name>",
+    "#",
+    "# Where <type-name> is the human-readable GitHub issue type name",
+    "# (e.g. Feature, Task, Epic, Bug). Matching is case-insensitive.",
+    "#",
+    "# Exits 0 on success. Exits non-zero with a clear diagnostic on stderr",
+    "# for any validation error or API failure.",
+    "",
+    "set -uo pipefail",
+    "",
+    "# \u2500\u2500 helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
+    "",
+    "err() {",
+    '  printf "set-issue-type.sh: %s\\n" "$*" >&2',
+    "}",
+    "",
+    "usage() {",
+    "  cat >&2 <<'USAGE'",
+    "Usage: set-issue-type.sh <issue-number> <type-name>",
+    "",
+    "  <issue-number>  Positive integer GitHub issue number.",
+    "  <type-name>     Human-readable issue type (Feature, Task, Epic, Bug,",
+    "                  or any type defined at the org level). Case-insensitive.",
+    "",
+    "Examples:",
+    "  set-issue-type.sh 123 Feature",
+    "  set-issue-type.sh 456 bug",
+    "USAGE",
+    "}",
+    "",
+    "# \u2500\u2500 argument validation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
+    "",
+    "if [[ $# -ne 2 ]]; then",
+    '  err "expected 2 arguments, got $#"',
+    "  usage",
+    "  exit 2",
+    "fi",
+    "",
+    'issue_number="$1"',
+    'type_name="$2"',
+    "",
+    'if ! [[ "$issue_number" =~ ^[1-9][0-9]*$ ]]; then',
+    `  err "issue number must be a positive integer (got: '$issue_number')"`,
+    "  exit 2",
+    "fi",
+    "",
+    'if [[ -z "${type_name// /}" ]]; then',
+    '  err "type name must be non-empty"',
+    "  exit 2",
+    "fi",
+    "",
+    "# \u2500\u2500 dependency checks \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
+    "",
+    "for cmd in gh jq; do",
+    '  if ! command -v "$cmd" >/dev/null 2>&1; then',
+    '    err "required command not found on PATH: $cmd"',
+    "    exit 3",
+    "  fi",
+    "done",
+    "",
+    "# \u2500\u2500 resolve repo owner/name \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
+    "",
+    "repo_json=$(gh repo view --json owner,name 2>/dev/null)",
+    'if [[ -z "$repo_json" ]]; then',
+    `  err "could not resolve owning repo via 'gh repo view' (not a GitHub repo or gh not authenticated?)"`,
+    "  exit 4",
+    "fi",
+    "",
+    `owner=$(echo "$repo_json" | jq -r '.owner.login // empty')`,
+    `name=$(echo "$repo_json" | jq -r '.name // empty')`,
+    "",
+    'if [[ -z "$owner" || -z "$name" ]]; then',
+    '  err "could not parse owner/name from gh repo view output"',
+    "  exit 4",
+    "fi",
+    "",
+    "# \u2500\u2500 look up issue type node ID \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
+    "",
+    "types_json=$(gh api graphql \\",
+    "  -f query='query($owner:String!,$repo:String!){repository(owner:$owner,name:$repo){issueTypes(first:50){nodes{id name}}}}' \\",
+    '  -f owner="$owner" -f repo="$name" 2>/dev/null)',
+    "",
+    'if [[ -z "$types_json" ]]; then',
+    '  err "failed to query repo issue types via GraphQL"',
+    "  exit 5",
+    "fi",
+    "",
+    `types_nodes=$(echo "$types_json" | jq -c '.data.repository.issueTypes.nodes // []')`,
+    "",
+    'if [[ "$types_nodes" == "[]" || "$types_nodes" == "null" ]]; then',
+    '  err "repo ${owner}/${name} has no issue types defined"',
+    "  exit 5",
+    "fi",
+    "",
+    "# Case-insensitive match by name.",
+    `type_id=$(echo "$types_nodes" | jq -r --arg n "$type_name" '`,
+    "  .[] | select((.name | ascii_downcase) == ($n | ascii_downcase)) | .id",
+    "' | head -n 1)",
+    "",
+    'if [[ -z "$type_id" ]]; then',
+    `  available=$(echo "$types_nodes" | jq -r '.[].name' | paste -sd ',' - | sed 's/,/, /g')`,
+    "  err \"type '${type_name}' not found in ${owner}/${name}. Available types: ${available}\"",
+    "  exit 6",
+    "fi",
+    "",
+    "# \u2500\u2500 look up issue node ID \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
+    "",
+    `issue_id=$(gh issue view "$issue_number" --json id -q '.id' 2>/dev/null || echo "")`,
+    "",
+    'if [[ -z "$issue_id" ]]; then',
+    '  err "issue #${issue_number} not found in ${owner}/${name}"',
+    "  exit 7",
+    "fi",
+    "",
+    "# \u2500\u2500 apply the mutation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
+    "",
+    "result=$(gh api graphql \\",
+    "  -f query='mutation($issueId:ID!,$typeId:ID!){updateIssueIssueType(input:{issueId:$issueId,issueTypeId:$typeId}){issue{number issueType{name}}}}' \\",
+    '  -f issueId="$issue_id" -f typeId="$type_id" 2>&1)',
+    "mutation_exit=$?",
+    "",
+    "if [[ $mutation_exit -ne 0 ]]; then",
+    '  err "updateIssueIssueType mutation failed: ${result}"',
+    "  exit 8",
+    "fi",
+    "",
+    "# Print the resulting {number, issueType: {name}} JSON line.",
+    `echo "$result" | jq -c '.data.updateIssueIssueType.issue'`
+  ].join("\n")
+};
 var githubWorkflowBundle = {
   name: "github-workflow",
   description: "GitHub issue and PR workflow automation patterns",
@@ -2329,19 +2471,20 @@ var githubWorkflowBundle = {
         "   - `--title '<type>: <description>'`",
         "   - `--body '<issue body>'`",
         "   - `--label '<type-label>' --label '<priority-label>' --label '<status-label>'`",
-        "7. **Set the GitHub issue type** via the GraphQL `updateIssueIssueType` mutation:",
-        "   - Look up the issue's node ID: `gh issue view <issue-number> --json id -q .id`",
-        "   - Look up the repo's issue type node IDs (one-time, can be cached):",
+        "7. **Set the GitHub issue type** by invoking the `set-issue-type.sh` helper (shipped with this bundle):",
         "",
-        "     ```sh",
-        "     gh api graphql -f query='query($owner:String!,$repo:String!){repository(owner:$owner,name:$repo){issueTypes(first:20){nodes{id name}}}}' -f owner=<owner> -f repo=<repo>",
-        "     ```",
+        "   ```sh",
+        "   .claude/procedures/set-issue-type.sh <issue-number> <Feature|Task|Epic|Bug>",
+        "   ```",
+        "",
+        "   The helper resolves owner/repo, looks up the issue type node ID, looks up the issue node ID, and applies the `updateIssueIssueType` mutation in one step. It exits non-zero with a clear diagnostic on any error and lists available types if the type name is not recognised.",
         "",
-        "   - Apply the chosen type to the issue:",
+        "   **Under the hood** (documented fallback if the helper is unavailable): the helper performs a two-step GraphQL flow \u2014 first a `repository(...).issueTypes` query to map the human-readable type name to a node ID, then the `updateIssueIssueType` mutation. The canonical queries are:",
         "",
-        "     ```sh",
-        "     gh api graphql -f query='mutation($issueId:ID!,$typeId:ID!){updateIssueIssueType(input:{issueId:$issueId,issueTypeId:$typeId}){issue{number issueType{name}}}}' -f issueId=<issue-node-id> -f typeId=<issue-type-node-id>",
-        "     ```",
+        "   ```sh",
+        "   gh api graphql -f query='query($owner:String!,$repo:String!){repository(owner:$owner,name:$repo){issueTypes(first:50){nodes{id name}}}}' -f owner=<owner> -f repo=<repo>",
+        "   gh api graphql -f query='mutation($issueId:ID!,$typeId:ID!){updateIssueIssueType(input:{issueId:$issueId,issueTypeId:$typeId}){issue{number issueType{name}}}}' -f issueId=<issue-node-id> -f typeId=<issue-type-node-id>",
+        "   ```",
         "",
         "### Issue Body Template",
         "",
@@ -2362,7 +2505,7 @@ var githubWorkflowBundle = {
         "### Important",
         "",
         "- Always use the conventional prefix in the issue title",
-        "- Always assign the correct GitHub issue type via the `updateIssueIssueType` GraphQL mutation (step 7) \u2014 never via `gh issue create --type`",
+        "- Always assign the correct GitHub issue type via the `set-issue-type.sh` helper (step 7) \u2014 never via `gh issue create --type`",
         "- Always include `type:*`, `priority:*`, and `status:*` labels",
         "- If the user does not specify a type, ask before creating the issue",
         "- If the priority cannot be inferred from the description, ask the user before creating the issue",
@@ -2414,7 +2557,8 @@ var githubWorkflowBundle = {
       ].join("\n"),
       tags: ["workflow"]
     }
-  ]
+  ],
+  procedures: [setIssueTypeProcedure]
 };
 
 // src/agent/bundles/industry-discovery.ts
@@ -6744,7 +6888,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 }