agentic-devtools 0.2.82__tar.gz → 0.2.83__tar.gz

agentic_devtools-0.2.83/.github/agents/agdt.address-copilot-review.ci-repair.agent.md

@@ -0,0 +1,40 @@
+---
+description: "Address Copilot Review (CI Repair): Automatically address GitHub Copilot PR review comments and CI failures in a CI environment"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+The expected input is a GitHub PR review comment URL of the form:
+`https://github.com/{owner}/{repo}/pull/{pr_number}#pullrequestreview-{review_id}`
+
+## Purpose
+
+CI-safe variant of the address-copilot-review agent designed to run on a
+GitHub-hosted runner within the AI PR Loop workflow. This agent:
+
+- Addresses Copilot review comments and/or CI failures
+- Applies lint fixes using only pinned trusted tooling (ruff, markdownlint-cli2)
+- Commits and pushes changes
+- Replies to review comments and resolves threads
+- Re-requests Copilot review
+
+**Scope limitations** (CI repair mode):
+
+- Does NOT run tests (`agdt-test`, `pytest`, or any test runner)
+- Does NOT install packages from the PR branch
+- Does NOT execute PR-sourced scripts
+- Does NOT approve or merge the PR
+
+## Instructions
+
+Follow the detailed instructions in the corresponding prompt file
+(`.github/prompts/agdt.address-copilot-review.ci-repair.prompt.md`).
+
+## Next Step
+
+Task is complete.

agentic_devtools-0.2.83/.github/prompts/agdt.address-copilot-review.ci-repair.prompt.md

@@ -0,0 +1,378 @@
+# Address Copilot PR Review Comments (CI Repair Mode)
+
+> **CI Repair Mode**: This prompt is designed for automated execution on a
+> GitHub-hosted runner. Verification (tests, CI) is delegated to the subsequent
+> CI pipeline triggered by the push — this agent does NOT run tests.
+>
+> **⚠️ SECURITY CONSTRAINTS**:
+>
+> - Do NOT run `pytest`, `agdt-test`, `agdt-test-quick`, `agdt-test-file`,
+>   `agdt-test-pattern`, `bash scripts/*.sh`, or any PR-sourced executable.
+> - Do NOT install packages from the PR branch (`pip install .`, `pip install -e .`).
+> - Do NOT approve or merge the PR. Your scope is limited to: code changes,
+>   comment replies, thread resolution, and re-requesting review.
+> - If `AGDT_CI_REPAIR_MODE=1` is set, these constraints are mandatory
+>   (defense-in-depth).
+
+You are a senior software engineer addressing feedback from a GitHub Copilot pull
+request review and/or CI failures. Follow this workflow systematically, completing
+each phase before proceeding to the next.
+
+---
+
+## Tooling Priority
+
+**Always prefer `agdt-*` commands** from agentic-devtools over raw alternatives:
+
+| Operation | Preferred (agdt-*) | Fallback (raw) |
+|-----------|-------------------|----------------|
+| Reply to review comments | `agdt-gh-reply-to-review-comments` | `gh api .../comments/{id}/replies` per comment |
+| Resolve review threads | `agdt-gh-resolve-review-threads` | GraphQL `resolveReviewThread` mutation per thread |
+| Request Copilot re-review | `agdt-gh-request-copilot-review` | `gh api .../requested_reviewers -X POST` |
+| Stage changes | — | `git add` |
+| Commit & push | — | `git commit` + `git push` |
+| Force push | — | `git push --force-with-lease` |
+
+> **CI Repair Note**: Because the `agentic-devtools` package is NOT installed on the
+> runner (security constraint: no `pip install` from PR branch), only `agdt-gh-*`
+> commands that wrap `gh` CLI are available. Git operations (`stage`, `commit`,
+> `push`) use raw git commands directly.
+
+The `agdt-gh-*` commands provide: centralized state tracking and consistent formatting.
+
+---
+
+## Phase 1: Parse the Review URL
+
+Extract identifiers from the PR review URL provided as input.
+
+### Expected URL Format
+
+```text
+https://github.com/{owner}/{repo}/pull/{pr_number}#pullrequestreview-{review_id}
+```
+
+### Parse Out
+
+| Variable | Example |
+|----------|---------|
+| `owner` | `ayaiayorg` |
+| `repo` | `agentic-devtools` |
+| `pr_number` | `1009` |
+| `review_id` | `4019856282` |
+
+### Validation
+
+- Confirm the URL matches the expected pattern (note: the fragment uses
+  `pullrequestreview-` — singular, not plural).
+- If the URL is malformed or missing, check environment variables
+  `REPAIR_PR_NUMBER`, `REPAIR_REVIEW_URL`, and `REPAIR_HEAD_SHA` for context.
+
+---
+
+## Phase 2: Fetch Review Comments
+
+Retrieve all comments belonging to this specific review using the GitHub REST API.
+
+Reviews can exceed 100 comments, so you **must** handle pagination.
+
+### Command
+
+```bash
+# Use --paginate to ensure ALL pages of comments are fetched, not just the first 100
+gh api --paginate \
+  "repos/{owner}/{repo}/pulls/{pr_number}/reviews/{review_id}/comments" \
+  --jq '.[]'
+```
+
+> **Note:** This raw `gh api` call is intentionally retained — no `agdt-gh-*`
+> command wraps individual comment content fetching.
+
+### Relevant Fields per Comment
+
+| Field | Use |
+|-------|-----|
+| `id` | Database ID — needed for replying and mapping to GraphQL thread IDs |
+| `path` | File path the comment is on |
+| `line` | Line number (may be `null` for file-level comments) |
+| `body` | Full comment text (the reviewer's feedback) |
+| `diff_hunk` | The diff context the comment was placed on |
+
+### Output
+
+List each comment with its `id`, `path`, `line`, and a short excerpt of `body`.
+
+---
+
+## Phase 3: Triage Each Comment
+
+For each comment, read the `body` and `diff_hunk` to understand the reviewer's
+request. Also read the referenced file(s) in the working tree to understand the
+current state.
+
+### Classification
+
+| Category | Criteria | Action |
+|----------|----------|--------|
+| **Addressable** | The feedback is valid and a code/doc change will fix it | Make a change in the relevant file |
+| **Not addressable** | False positive, already correct, out of scope, or should not result in a change | Reply with a clear explanation |
+
+### Output
+
+Document a triage table:
+
+```markdown
+| Comment ID | File | Line | Category | Reason |
+|------------|------|------|----------|--------|
+| 12345 | src/foo.py | 42 | Addressable | Valid: missing null check |
+| 12346 | README.md | 10 | Not addressable | Already correct |
+```
+
+---
+
+## Phase 3b: Handle CI Failures (if present)
+
+If CI failure context is provided (see the `## CI Failure Context` section at the
+end of this prompt, if present), address those failures:
+
+### For Lint Failures (ruff)
+
+1. Read the failure messages to identify specific files and violations
+2. Apply automated fixes using **only pinned trusted tooling**:
+
+   ```bash
+   ruff check --fix .
+   ruff format .
+   ```
+
+3. Review the changes to ensure they are correct
+
+### For Markdown Lint Failures (markdownlint)
+
+1. Read the failure messages to identify files and rules violated
+2. Fix the markdown issues manually (markdownlint-cli2 does not have a
+   reliable `--fix` mode for all rules)
+
+### For Test Failures
+
+1. Read the test failure output to understand which tests failed and why
+2. Read the failing test code and the code under test
+3. Fix the **source code** (not the tests) to make the tests pass
+4. Do NOT run the tests yourself — verification is delegated to the
+   subsequent CI run
+
+### For Other Failures
+
+1. Read the failure output carefully
+2. If the failure is addressable (e.g., type errors, import issues), fix it
+3. If the failure is not addressable (e.g., infrastructure issues, flaky
+   tests), note it in your summary
+
+---
+
+## Phase 4: Make Changes for Addressable Comments
+
+Edit files to address every comment classified as **addressable** and every
+CI failure that is fixable. After **all** edits are complete, commit and push
+once (not per-comment).
+
+> **⚠️ DO NOT run tests.** Verification is delegated to the subsequent CI run
+> triggered by the push.
+
+### Stage Changes and Secret Scanning Guard
+
+Explicitly stage all changes first, then run the secret scan on the staged diff.
+This ensures the scan covers all pending work before committing.
+
+```bash
+# Stage all changes explicitly
+git add -A
+
+# Scan staged diff for potential secrets
+if git diff --cached | grep -iqE '(token|password|secret|api_key|private_key)'; then
+  echo 'ABORT: potential secret detected in staged changes'
+  exit 1
+fi
+```
+
+If the guard triggers, review the staged changes and remove any sensitive content
+before proceeding.
+
+### Resolve the GitHub Issue Key
+
+Before committing, determine the GitHub issue linked to this PR so your commit
+message follows the repository's required convention.
+
+1. Check the **existing commit message** on the branch for an issue reference
+   like `#1062` in the conventional-commit scope.
+2. If not found, check the **PR title** and **PR body** for closing keywords.
+3. If still not found, check the PR's **linked issues** via the GitHub API:
+
+   ```bash
+   gh api graphql -f query='query {
+     repository(owner: "{owner}", name: "{repo}") {
+       pullRequest(number: {pr_number}) {
+         closingIssuesReferences(first: 10) {
+           nodes { number title }
+         }
+       }
+     }
+   }'
+   ```
+
+### Commit & Push
+
+Include `[ai-repair]` in the commit body so repair commits are identifiable
+in git log.
+
+```bash
+agdt-set commit_message "<type>([#<issue>](https://github.com/{owner}/{repo}/issues/<issue>)): address copilot review feedback
+
+- <summary of changes>
+[ai-repair]
+
+[#<issue>](https://github.com/{owner}/{repo}/issues/<issue>)"
+agdt-git-save-work --skip-stage
+agdt-task-wait
+```
+
+> **Note:** `--skip-stage` is used because changes were already staged in the
+> secret scanning guard step above. This prevents re-staging after the scan.
+
+Choose the commit **type** based on the nature of the changes:
+
+| Type | When to use |
+|------|-------------|
+| `fix` | Bug fixes, incorrect behavior |
+| `refactor` | Code quality, readability, or structure improvements |
+| `style` | Formatting, naming, whitespace changes |
+| `docs` | Documentation-only changes |
+| `chore` | Maintenance tasks that don't affect production code |
+
+### Capture the Commit Hash
+
+```bash
+COMMIT_FULL=$(git log -1 --format="%H")
+COMMIT_SHORT=$(git log -1 --format="%h")
+```
+
+### Verify Push Was Successful
+
+After `agdt-git-save-work` completes, confirm the local commit was pushed:
+
+```bash
+REMOTE_SHA=$(gh pr view {pr_number} --repo {owner}/{repo} --json headRefOid --jq '.headRefOid')
+REMOTE_SHA_SHORT=$(echo "$REMOTE_SHA" | cut -c1-7)
+```
+
+Compare `REMOTE_SHA` with `COMMIT_FULL`. If they do not match, run
+`agdt-git-force-push` and `agdt-task-wait`, then re-verify.
+
+### Edge Case: No Addressable Comments and No CI Failures
+
+If every comment was triaged as **not addressable** and there are no CI failures
+to fix, skip the commit step and proceed directly to Phase 5 (replies only).
+
+---
+
+## Phase 5: Reply to Every Comment
+
+Send a reply to **each** comment from the review using the
+`agdt-gh-reply-to-review-comments` command.
+
+### Prepare the Replies File
+
+Create a JSON file (e.g., `replies.json`) containing one entry per comment:
+
+```json
+[
+  {"commentId": 12345, "body": "addressed in [abc123d](https://github.com/{owner}/{repo}/pull/{pr_number}/commits/{COMMIT_FULL})"},
+  {"commentId": 12346, "body": "Already correct — the raw markdown uses standard single-pipe format."}
+]
+```
+
+#### For Comments That WERE Addressed
+
+Use this reply template:
+
+```text
+addressed in [{COMMIT_SHORT}](https://github.com/{owner}/{repo}/pull/{pr_number}/commits/{COMMIT_FULL})
+```
+
+#### For Comments That Were NOT Addressed
+
+Reply with a clear, specific explanation of **why** the feedback was not applied.
+
+### Post Replies
+
+```bash
+agdt-gh-reply-to-review-comments --pr {pr_number} --repo {owner}/{repo} \
+  --review-id {review_id} --replies-file replies.json
+```
+
+---
+
+## Phase 6: Resolve Review Threads
+
+After all replies are posted, resolve the corresponding discussion threads.
+
+```bash
+agdt-gh-resolve-review-threads --pr {pr_number} --repo {owner}/{repo} \
+  --review-id {review_id}
+```
+
+---
+
+## Phase 7: Re-request Copilot Review
+
+Request a new review from the Copilot reviewer bot so it can verify the changes.
+
+```bash
+agdt-gh-request-copilot-review --pr {pr_number} --repo {owner}/{repo}
+```
+
+Check the JSON output — if `verified` is `false`, retry once after 10 seconds.
+
+---
+
+## Phase 8: Summary
+
+After completing all phases, present a summary:
+
+```markdown
+## CI Repair Summary
+
+**PR:** {owner}/{repo}#{pr_number}
+**Review ID:** {review_id}
+**Total comments:** X
+**CI failures addressed:** Y
+
+### Results
+
+| Comment ID | File | Line | Category | Action Taken |
+|------------|------|------|----------|--------------|
+| 12345 | src/foo.py | 42 | Addressed | Fixed in {COMMIT_SHORT} |
+| 12346 | README.md | 10 | Not addressed | Already correct (explained) |
+
+### Verification
+
+| Step | Status | Details |
+|------|--------|---------|
+| Push to remote | ✅ Verified | Head SHA matches {COMMIT_SHORT} |
+| Replies posted | ✅ Verified | {successful}/{totalReplies} succeeded |
+| Threads resolved | ✅ Verified | {threadsResolved} resolved |
+| Copilot re-review requested | ✅ Verified | Reviewer confirmed |
+```
+
+---
+
+## Error Handling
+
+- **Command failures**: If any `agdt-gh-*` command exits with a non-zero code,
+  print the stderr output and handle as described in the relevant phase.
+- **Thread already resolved**: `agdt-gh-resolve-review-threads` handles this
+  silently.
+- **Comment reply fails**: `agdt-gh-reply-to-review-comments` handles retries
+  internally.
+- **No comments found**: If the review has zero comments and no CI failures,
+  inform the user and stop.

{agentic_devtools-0.2.82 → agentic_devtools-0.2.83}/.github/prompts/agdt.address-copilot-review.prompt.md

@@ -1,5 +1,9 @@
 # Address Copilot PR Review Comments
 
+> **Defense-in-depth**: If the environment variable `AGDT_CI_REPAIR_MODE=1` is set,
+> skip all test execution steps (Phase 4 test verification). This variable is set
+> by the CI repair job to prevent executing untrusted PR code on the runner.
+
 You are a senior software engineer addressing feedback from a GitHub Copilot pull request review.
 Follow this workflow systematically, completing each phase before proceeding to the next.
 

{agentic_devtools-0.2.82 → agentic_devtools-0.2.83}/.github/scripts/speckit-trigger/create-spec-pr.sh

@@ -24,7 +24,9 @@
 #   --phase-name   - Phase name (specify, clarify, plan, tasks, analyze) (optional)
 #
 # Environment:
-#   GH_TOKEN or GITHUB_TOKEN - GitHub token for gh CLI
+#   GH_TOKEN or GITHUB_TOKEN - GitHub token for gh CLI (PR creation)
+#   LABEL_TOKEN              - GitHub token with issues:write for label operations
+#                              (falls back to GH_TOKEN if not set)
 #   GITHUB_REPOSITORY        - Repository in owner/repo format
 #
 # Outputs:
@@ -128,6 +130,10 @@ if [[ -z "${GH_TOKEN:-}" ]]; then
     exit 1
 fi
 
+# LABEL_TOKEN is used for label operations (gh label create / gh pr edit --add-label)
+# which require issues:write permission. Falls back to GH_TOKEN if not set.
+LABEL_TOKEN="${LABEL_TOKEN:-$GH_TOKEN}"
+
 # Validate GITHUB_REPOSITORY — required for building artifact URLs in the PR body
 if [[ -z "${GITHUB_REPOSITORY:-}" ]]; then
     echo "Error: GITHUB_REPOSITORY is required (expected owner/repo format)" >&2
@@ -569,21 +575,80 @@ if [[ -z "$PR_NUMBER" ]]; then
     PR_NUMBER=$(echo "$PR_URL" | grep -o '[0-9]\+$' || echo "")
 fi
 
-# Apply labels if provided
+# ---------------------------------------------------------------------------
+# Label operations — use LABEL_TOKEN (issues:write) instead of GH_TOKEN
+# ---------------------------------------------------------------------------
+
+# Preflight: verify LABEL_TOKEN can read repository labels (issues:read).
+# Note: this does NOT prove issues:write — a full write-scoped check would
+# require creating/deleting a scratch label, which is unnecessarily destructive.
+# A read failure, however, reliably detects missing/invalid tokens and wrong scopes.
+LABEL_PREFLIGHT_OK=true
+LABEL_PREFLIGHT_ERR=""
+if ! LABEL_PREFLIGHT_ERR=$(GH_TOKEN="$LABEL_TOKEN" gh api "/repos/${REPO_SLUG}/labels" --jq '.[0].name' 2>&1); then
+    echo "Warning: LABEL_TOKEN failed read-access preflight — labels will not be applied. Error: $LABEL_PREFLIGHT_ERR" >&2
+    LABEL_PREFLIGHT_OK=false
+fi
+
+# Helper: create a label with retry (ensures label exists before applying)
+_create_label_with_retry() {
+    local label_name="$1"
+    local description="${2:-}"
+    local color="${3:-}"
+    local create_args=("$label_name" "--force")
+    [[ -n "$description" ]] && create_args+=(--description "$description")
+    [[ -n "$color" ]] && create_args+=(--color "$color")
+
+    local error_output
+    if ! error_output=$(GH_TOKEN="$LABEL_TOKEN" gh label create "${create_args[@]}" --repo "$REPO_SLUG" 2>&1); then
+        echo "  Warning: Could not create label '$label_name': $error_output" >&2
+        return 1
+    fi
+    return 0
+}
+
+# Helper: apply labels to PR in batch with retry
+_apply_labels_with_retry() {
+    local pr_url="$1"
+    local label_csv="$2"
+    local error_output
+    if ! error_output=$(GH_TOKEN="$LABEL_TOKEN" gh pr edit "$pr_url" --add-label "$label_csv" 2>&1); then
+        echo "  Warning: Could not apply labels '$label_csv' to PR: $error_output" >&2
+        return 1
+    fi
+    return 0
+}
+
+# Collect all labels to apply in a single batch
+ALL_LABELS=()
+
+# Short-circuit all label operations when the preflight failed — avoids
+# pointless retries with backoff that slow down PR creation and spam logs.
+if [[ "$LABEL_PREFLIGHT_OK" != "true" ]]; then
+    echo "Skipping all label operations (preflight failed)." >&2
+else
+
+# Parse issue labels
 if [[ "$LABELS_JSON" != "[]" ]] && [[ -n "$LABELS_JSON" ]]; then
     echo "Applying labels from issue..."
-
-    # Parse labels and apply them
-    LABELS=$(echo "$LABELS_JSON" | jq -r '.[]' 2>/dev/null || echo "")
+    JQ_TMPFILE=$(mktemp)
+    LABELS=$(echo "$LABELS_JSON" | jq -r '.[]' 2>"$JQ_TMPFILE") || true
+    JQ_ERR=$(cat "$JQ_TMPFILE")
+    rm -f "$JQ_TMPFILE"
+    if [[ -n "$JQ_ERR" ]]; then
+        echo "  Warning: jq failed to parse LABELS_JSON: $JQ_ERR" >&2
+        LABELS=""
+    fi
 
     if [[ -n "$LABELS" ]]; then
         while IFS= read -r label; do
             [[ -z "$label" ]] && continue
-            echo "  Adding label: $label"
-            gh label create "$label" --force 2>/dev/null || true
-            gh pr edit "$PR_URL" --add-label "$label" 2>/dev/null || {
-                echo "  Warning: Could not add label '$label'"
-            }
+            echo "  Ensuring label exists: $label"
+            if call_with_retry 3 2 _create_label_with_retry "$label"; then
+                ALL_LABELS+=("$label")
+            else
+                echo "  Warning: Skipping label '$label' after retry exhaustion" >&2
+            fi
         done <<< "$LABELS"
     fi
 fi
@@ -592,18 +657,31 @@ fi
 if [[ -n "$PHASE_NUMBER" ]]; then
     PHASE_LABEL="speckit:phase-${PHASE_NUMBER}"
     echo "Adding $PHASE_LABEL label..."
-    gh label create "$PHASE_LABEL" --force --description "SpecKit Phase $PHASE_NUMBER PR" --color "0E8A16" 2>/dev/null || true
-    gh pr edit "$PR_URL" --add-label "$PHASE_LABEL" 2>/dev/null || {
-        echo "Warning: Could not add $PHASE_LABEL label"
-    }
+    if call_with_retry 3 2 _create_label_with_retry "$PHASE_LABEL" "SpecKit Phase $PHASE_NUMBER PR" "0E8A16"; then
+        ALL_LABELS+=("$PHASE_LABEL")
+    else
+        echo "Warning: Skipping label '$PHASE_LABEL' after retry exhaustion" >&2
+    fi
 else
     echo "Adding speckit:spec label..."
-    gh label create "speckit:spec" --force --description "Spec PR created by SpecKit pipeline" --color "0E8A16" 2>/dev/null || true
-    gh pr edit "$PR_URL" --add-label "speckit:spec" 2>/dev/null || {
-        echo "Warning: Could not add speckit:spec label"
+    if call_with_retry 3 2 _create_label_with_retry "speckit:spec" "Spec PR created by SpecKit pipeline" "0E8A16"; then
+        ALL_LABELS+=("speckit:spec")
+    else
+        echo "Warning: Skipping label 'speckit:spec' after retry exhaustion" >&2
+    fi
+fi
+
+# Apply all labels in a single batch call
+if [[ ${#ALL_LABELS[@]} -gt 0 ]]; then
+    LABEL_CSV=$(IFS=,; echo "${ALL_LABELS[*]}")
+    echo "Applying labels to PR: $LABEL_CSV"
+    call_with_retry 3 2 _apply_labels_with_retry "$PR_URL" "$LABEL_CSV" || {
+        echo "Warning: Failed to apply some labels after retries" >&2
     }
 fi
 
+fi  # end of LABEL_PREFLIGHT_OK gate
+
 # Output results
 echo "pr_url=$PR_URL" >> "${GITHUB_OUTPUT:-/dev/stdout}"
 echo "pr_number=$PR_NUMBER" >> "${GITHUB_OUTPUT:-/dev/stdout}"