agentic-devtools 0.2.86__tar.gz → 0.2.87__tar.gz

{agentic_devtools-0.2.86 → agentic_devtools-0.2.87}/.github/scripts/speckit-trigger/generate-spec-from-issue.sh

@@ -1973,7 +1973,7 @@ capture_missing_mandatory_sections() {
 # ---------------------------------------------------------------------------
 run_specify_phase() {
     # Load the spec template
-    local template_file="$REPO_ROOT/.specify/templates/spec-template.md"
+    local template_file="$REPO_ROOT/.specify/presets/agdt-templates/templates/spec-template.md"
     local spec_template=""
     if [[ -f "$template_file" ]]; then
         spec_template=$(cat "$template_file")

{agentic_devtools-0.2.86 → agentic_devtools-0.2.87}/.github/workflows/ai-pr-loop.yml

@@ -54,4 +54,8 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+          # Separate identity for PR approval — GitHub prevents a user from
+          # approving their own PR, so bot-authored PRs require a distinct
+          # account's token for the approval step.
+          AGDT_PR_APPROVER_PAT: ${{ secrets.AGDT_PR_APPROVER_PAT }}
         run: agdt-ai-pr-loop

agentic_devtools-0.2.87/.specify/config.yml

@@ -0,0 +1,17 @@
+# Spec-Kit Configuration
+# See: https://github.github.io/spec-kit/reference/configuration.html
+#
+# This file references local extension and preset packages using relative paths.
+# The monorepo approach keeps AGDT-specific code atomic and easier to evolve
+# without cross-repo maintenance burden. See issue #1444 for rationale.
+#
+# To publish to the community catalog later, replace relative paths with
+# published package names and version pins.
+
+extensions:
+  # AGDT-specific commands and scripts for agentic-devtools workflows
+  - "./.specify/extensions/agdt-workflows"
+
+presets:
+  # AGDT-specific template overrides (spec, plan, tasks, checklist, agent-file)
+  - "./.specify/presets/agdt-templates"

{agentic_devtools-0.2.86/.specify/templates → agentic_devtools-0.2.87/.specify/extensions/agdt-workflows}/commands/.markdownlint.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json",
-  "extends": "../../../.markdownlint.json",
+  "extends": "../../../../.markdownlint.json",
   "MD041": false,
   "MD013": false
 }

agentic_devtools-0.2.87/.specify/extensions/agdt-workflows/extension.yml

@@ -0,0 +1,36 @@
+name: agdt-workflows
+version: 1.0.0
+description: >
+  AGDT-specific commands and scripts for agentic-devtools spec-driven
+  development workflows. Provides custom slash commands (specify, plan,
+  tasks, implement, analyze, clarify, checklist, constitution, taskstoissues)
+  and supporting bash/powershell scripts.
+
+author: ayaiayorg
+license: MIT
+repository: https://github.com/ayaiayorg/agentic-devtools
+
+commands:
+  - analyze.md
+  - checklist.md
+  - clarify.md
+  - constitution.md
+  - implement.md
+  - plan.md
+  - specify.md
+  - tasks.md
+  - taskstoissues.md
+
+scripts:
+  bash:
+    - check-prerequisites.sh
+    - common.sh
+    - create-new-feature.sh
+    - setup-plan.sh
+    - update-agent-context.sh
+  powershell:
+    - check-prerequisites.ps1
+    - common.ps1
+    - create-new-feature.ps1
+    - setup-plan.ps1
+    - update-agent-context.ps1

agentic_devtools-0.2.87/.specify/presets/agdt-templates/preset.yml

@@ -0,0 +1,21 @@
+name: agdt-templates
+version: 1.0.0
+description: >
+  AGDT-specific template overrides for agentic-devtools spec-driven
+  development. Provides custom versions of spec, plan, tasks, checklist,
+  and agent-file templates, along with VS Code settings for prompt
+  file recommendations.
+
+author: ayaiayorg
+license: MIT
+repository: https://github.com/ayaiayorg/agentic-devtools
+
+templates:
+  - agent-file-template.md
+  - checklist-template.md
+  - plan-template.md
+  - spec-template.md
+  - tasks-template.md
+
+assets:
+  - vscode-settings.json

{agentic_devtools-0.2.86/.specify → agentic_devtools-0.2.87/.specify/presets/agdt-templates}/templates/vscode-settings.json

@@ -7,8 +7,8 @@
         "speckit.implement": true
     },
     "chat.tools.terminal.autoApprove": {
-        ".specify/scripts/bash/": true,
-        ".specify/scripts/powershell/": true
+        ".specify/extensions/agdt-workflows/scripts/bash/": true,
+        ".specify/extensions/agdt-workflows/scripts/powershell/": true
     }
 }
 

{agentic_devtools-0.2.86 → agentic_devtools-0.2.87}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-devtools
-Version: 0.2.86
+Version: 0.2.87
 Summary: Agentic devtools integrate Jira, DevOps & more
 Author: ayaiayorg
 License-Expression: MIT

{agentic_devtools-0.2.86 → agentic_devtools-0.2.87}/agentic_devtools/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.86'
-__version_tuple__ = version_tuple = (0, 2, 86)
+__version__ = version = '0.2.87'
+__version_tuple__ = version_tuple = (0, 2, 87)
 
 __commit_id__ = commit_id = None

{agentic_devtools-0.2.86 → agentic_devtools-0.2.87}/agentic_devtools/cli/ci/github_provider.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 import json
 import logging
+import os
 from typing import Any
 
 from agentic_devtools.cli.ci.exceptions import MalformedEventError
@@ -24,7 +25,14 @@ from agentic_devtools.cli.subprocess_utils import run_safe
 logger = logging.getLogger(__name__)
 
 
-def _gh_api(endpoint: str, *, method: str = "GET", body: dict | None = None, paginate: bool = False) -> str:
+def _gh_api(
+    endpoint: str,
+    *,
+    method: str = "GET",
+    body: dict | None = None,
+    paginate: bool = False,
+    token: str | None = None,
+) -> str:
     """Call the GitHub API via the ``gh`` CLI.
 
     Args:
@@ -32,6 +40,9 @@ def _gh_api(endpoint: str, *, method: str = "GET", body: dict | None = None, pag
         method: HTTP method.
         body: JSON body for POST/PATCH/PUT requests.
         paginate: Whether to use --paginate for list endpoints.
+        token: Optional token to use instead of the default ``GH_TOKEN``.
+            When provided, the subprocess environment is overridden so that
+            ``gh`` authenticates with this token.
 
     Returns:
         Raw response body as string.
@@ -46,12 +57,17 @@ def _gh_api(endpoint: str, *, method: str = "GET", body: dict | None = None, pag
     if body is not None:
         cmd.extend(["--input", "-"])
 
+    env: dict[str, str] | None = None
+    if token:
+        env = {**os.environ, "GH_TOKEN": token}
+
     result = run_safe(
         cmd,
         capture_output=True,
         text=True,
         shell=False,
         input=json.dumps(body) if body else None,
+        env=env,
     )
 
     if result.returncode != 0:
@@ -59,11 +75,7 @@ def _gh_api(endpoint: str, *, method: str = "GET", body: dict | None = None, pag
         stderr_lower = stderr.lower()
         # GitHub rate limit responses — only match actual rate-limit indicators,
         # not generic 403 (which covers permissions, SSO, access restrictions).
-        if (
-            "rate limit" in stderr_lower
-            or "secondary rate limit" in stderr_lower
-            or "429" in stderr
-        ):
+        if "rate limit" in stderr_lower or "secondary rate limit" in stderr_lower or "429" in stderr:
             raise RetryableError(f"GitHub API rate limited: {stderr}")
         # Server errors are retryable
         if any(code in stderr for code in ("500", "502", "503", "504")):
@@ -106,10 +118,9 @@ def _parse_paginated_json(raw: str) -> Any:
         try:
             obj, end_idx = decoder.raw_decode(raw, idx)
         except json.JSONDecodeError as exc:
-            snippet = raw[idx:idx + 80]
+            snippet = raw[idx : idx + 80]
             raise json.JSONDecodeError(
-                f"Failed to parse concatenated JSON at index {idx} "
-                f"(snippet: {snippet!r}): {exc.msg}",
+                f"Failed to parse concatenated JSON at index {idx} (snippet: {snippet!r}): {exc.msg}",
                 raw,
                 idx,
             ) from exc
@@ -326,12 +337,38 @@ class GitHubActionsProvider(CIPlatformProvider):
 
     @retry_with_backoff()
     def approve_pr(self, pr_number: int, head_sha: str, body: str) -> None:
-        """Approve a pull request."""
-        _gh_api(
-            self._repo_api(f"/pulls/{pr_number}/reviews"),
-            method="POST",
-            body={"commit_id": head_sha, "event": "APPROVE", "body": body},
-        )
+        """Approve a pull request.
+
+        Uses ``AGDT_PR_APPROVER_PAT`` when set so that the approval comes from
+        a separate identity (GitHub prevents approving your own PR).  When the
+        variable is unset or empty the approval is skipped with a warning.
+        """
+        approver_token = os.environ.get("AGDT_PR_APPROVER_PAT", "").strip()
+        if not approver_token:
+            logger.warning(
+                "AGDT_PR_APPROVER_PAT is not configured. "
+                "Cannot approve PR without a dedicated approver token. "
+                "See repository documentation for setup instructions."
+            )
+            return
+
+        try:
+            _gh_api(
+                self._repo_api(f"/pulls/{pr_number}/reviews"),
+                method="POST",
+                body={"commit_id": head_sha, "event": "APPROVE", "body": body},
+                token=approver_token,
+            )
+        except RuntimeError as exc:
+            stderr = str(exc)
+            if "401" in stderr or "Bad credentials" in stderr.lower():
+                logger.warning(
+                    "AGDT_PR_APPROVER_PAT authentication failed (401). "
+                    "The token may be expired or invalid. "
+                    "Skipping PR approval. Rotate the secret and retry."
+                )
+                return
+            raise
 
     @retry_with_backoff()
     def merge_pr(self, pr_number: int, head_sha: str, method: str) -> None:

agentic_devtools-0.2.87/docs/ci-secrets.md

@@ -0,0 +1,58 @@
+# CI Secrets Configuration
+
+This document describes the GitHub Actions secrets used by the
+`ai-pr-loop` workflow (`.github/workflows/ai-pr-loop.yml`).
+
+## Secrets
+
+| Secret | Purpose | Required |
+|--------|---------|----------|
+| `GITHUB_TOKEN` | Default token for merge, comments, and general API calls | Yes (auto-provided) |
+| `COPILOT_GITHUB_TOKEN` | Token for Copilot review requests | Yes |
+| `AGDT_PR_APPROVER_PAT` | Dedicated token for PR approvals from a separate identity | Yes |
+
+## `AGDT_PR_APPROVER_PAT`
+
+### Why a separate token?
+
+GitHub prevents a user from approving their own pull request. When the
+AI PR Loop creates a PR under the `GITHUB_TOKEN` identity and then
+attempts to approve it with the same token, the approval is rejected.
+A Personal Access Token from a **different** GitHub account is required
+so the approval comes from a distinct identity.
+
+### Required permissions
+
+- **Token type**: Fine-grained Personal Access Token (recommended)
+- **Repository access**: Only `ayaiayorg/agentic-devtools`
+- **Permissions**: `Pull requests: Write`
+- **Expiry**: 90 days (rotate before expiration)
+
+### Setup steps
+
+1. Sign in to the dedicated approver account (e.g., `ayaiayorg-pr-approver`).
+2. Navigate to **Settings → Developer settings → Personal access tokens → Fine-grained tokens**.
+3. Click **Generate new token**.
+4. Configure:
+   - **Name**: `AGDT_PR_APPROVER_PAT`
+   - **Repository access**: Only select repositories → `ayaiayorg/agentic-devtools`
+   - **Permissions**: `Pull requests: Write`
+5. Copy the generated token.
+6. In the repository, go to **Settings → Secrets and variables → Actions**.
+7. Create a new secret named `AGDT_PR_APPROVER_PAT` with the token value.
+
+### Rotation procedure
+
+1. Generate a new token following the setup steps above.
+2. Update the `AGDT_PR_APPROVER_PAT` secret in repository settings.
+3. The old token is invalidated automatically once the new one is saved.
+4. No workflow changes are required — the secret name stays the same.
+
+### Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `AGDT_PR_APPROVER_PAT is not configured` (warning) | Secret not set in repository | Add the secret per setup steps |
+| `HTTP 401: Bad credentials` | Token expired or revoked | Rotate the token |
+| `HTTP 403` | Insufficient permissions or wrong repo scope | Regenerate with correct permissions |
+| Approval rejected (self-approval) | Token belongs to the same account as PR author | Use a different account's token |

agentic_devtools-0.2.87/specs/1432-standardize-copilot-review-response/checklists/requirements.md

@@ -0,0 +1,48 @@
+# Specification Quality Checklist: Standardize Copilot Review PR Response Process
+
+**Purpose**: Validate specification completeness before proceeding to planning
+**Created**: 2026-05-15
+**Feature**: [spec.md](../spec.md)
+**Source Issue**: #1432
+
+## Content Quality
+
+- [ ] CHK001 All six user stories clearly articulate user value from the repository maintainer/developer perspective (not implementation convenience)
+- [ ] CHK002 Each user story follows "As a [role], I want [capability], so that [benefit]" format — verify US1 (Automated AI Session Trigger), US2 (Thread Resolution), US3 (Commit Squash), US4
+  (Template-Driven Formatting), US5 (Platform-Agnostic Code), US6 (Deduplication)
+- [ ] CHK003 Priority assignments (P1: US1–US3, P2: US4–US6) include justification and reflect dependency ordering — confirm P1 items are true prerequisites for P2 items
+- [ ] CHK004 Requirements FR-001 through FR-017 specify WHAT the system must do without prescribing HOW (e.g., FR-012's hidden HTML comment marker and FR-014's polling interval/timeout are
+  implementation details that should be moved to clarifications or design). Verify FR-010 correctly specifies Copilot SDK usage (not @copilot comment) for commit message generation, and FR-011
+  correctly specifies force-push with human PAT (not re-request review) for re-triggering automatic Copilot review.
+
+## Requirement Completeness
+
+- [ ] CHK005 Each acceptance scenario in US1–US6 is independently testable as stated in the "Independent Test" sections — verify no scenario requires unstated preconditions
+- [ ] CHK006 All five documented edge cases (re-run after failure, agent timeout, multi-submission suppressed comments, insufficient PAT permissions, force-push race condition) have corresponding
+  functional requirements or acceptance scenarios that address them
+- [ ] CHK007 All acceptance scenarios follow Given/When/Then format with concrete, unambiguous conditions — verify US3 scenario 2 (commit message generation via Copilot SDK with fallback) is not
+  overloaded with multiple outcomes
+- [ ] CHK008 Success criteria SC-001 through SC-007 specify measurable numeric thresholds (e.g., "10 consecutive PRs", "60 seconds", "100% coverage") that can be validated in CI or integration tests
+- [ ] CHK009 Out of Scope section explicitly excludes Azure DevOps adapter, fork PRs, agent behavior modification, CLI signature changes, and building a custom Copilot agent — verify no requirement
+  contradicts these boundaries
+- [ ] CHK010 Dependencies section identifies all external systems (GitHub REST/GraphQL API, GitHub Actions, PAT secrets, Copilot SDK,
+  existing `agdt-gh-*` Python functions, `agentic_devtools.prompts.loader`) and the Assumptions section documents what must be true
+  about each
+
+## Feature Readiness
+
+- [ ] CHK011 Every functional requirement (FR-001 through FR-017) has at least one acceptance scenario in US1–US6 that validates it — verify FR-014 (result comment polling), FR-015 (template
+  selection), FR-016 (timeout failure comment), and FR-017 (head SHA verification before force-push) are covered by specific scenarios
+- [ ] CHK012 User scenarios cover the complete lifecycle: trigger (US1) → agent execution wait (FR-014) → thread resolution (US2) → commit squash (US3) → force-push re-trigger (FR-011) — verify no
+  lifecycle gap exists between squash completion and re-triggered Copilot review
+- [ ] CHK013 Success criteria SC-001 (end-to-end loop for 10 PRs) and SC-003 (thread resolution within 60 seconds) define concrete measurement methods or environments where validation will occur
+- [ ] CHK014 Functional requirements contain no implementation leakage — specifically verify FR-012 (HTML comment marker format), FR-014 (30-second polling interval, 15-minute timeout), FR-016
+  (timeout duration and failure-comment contents), and NFR-002 (2-second base delay, 2× multiplier) belong in design/planning rather than specification
+
+## Notes
+
+- This checklist was generated from the specification content for issue #1432
+- Items marked incomplete require spec updates before proceeding to planning
+
+---
+*Generated by SpecKit agent session (claude-opus-4.6)*

agentic_devtools-0.2.87/specs/1432-standardize-copilot-review-response/fr-coverage.json

@@ -0,0 +1 @@
+{"covered": ["FR-001", "FR-002", "FR-003", "FR-004", "FR-005", "FR-006", "FR-007", "FR-008", "FR-009", "FR-010", "FR-011", "FR-012", "FR-013", "FR-014", "FR-015", "FR-016", "FR-017"], "uncovered": [], "total": 17, "max_retries": 2}

agentic_devtools-0.2.87/specs/1432-standardize-copilot-review-response/plan.md

@@ -0,0 +1,276 @@
+# Implementation Plan: Standardize Copilot Review PR Response Process
+
+## 1. Technical Context
+
+### Technology Stack
+
+- **Language**: Python 3.10+ (per `requires-python = ">=3.10"` in `pyproject.toml`)
+- **Package**: `agentic-devtools` (pip-installable, CLI entry points via `pyproject.toml`)
+- **CI Platform**: GitHub Actions (`gh` CLI for API interactions)
+- **APIs**: GitHub REST API, GitHub GraphQL API (via `gh api`)
+- **Template Engine**: Jinja2 (existing `agentic_devtools.prompts.loader` module)
+- **Testing**: pytest with 1:1:1 structure, 100% coverage requirement
+- **Existing Infrastructure**: `agentic_devtools/cli/ci/` package with provider abstraction, orchestrator, guards, retry utilities
+
+### Architecture Decisions
+
+- All business logic in Python (`agentic_devtools/cli/ci/`), workflow YAML is orchestration-only
+- Reuse existing `CIPlatformProvider` abstraction and `GitHubActionsProvider`
+- Reuse existing `agdt-gh-resolve-review-threads` and `agdt-gh-reply-to-review-comments` Python functions directly (not subprocess)
+- Templates in `agentic_devtools/prompts/ci/` loaded via `load_ci_template()` + `substitute_variables()`
+- New modules extend the existing `cli/ci/` package; no new top-level packages
+
+## 2. Research Summary
+
+Key technical decisions informing this plan:
+
+- **Copilot SDK integration**: Use Copilot SDK for commit message generation with a 5-minute timeout; local fallback generates a conventional-commit message from PR title + commit history
+- **Result comment detection**: Polling-based approach (30s intervals, 15min max) preferred over webhooks for simplicity and reliability in GitHub Actions
+- **Force-push safety**: `--force-with-lease` combined with pre-push SHA verification (FR-017) prevents overwriting concurrent changes
+- **Template selection**: Automatic selection based on review state — suppressed-comments template vs CI-only template
+
+## 3. Design Overview
+
+### High-Level Architecture
+
+```text
+┌──────────────────────────────────────────────────────────────────┐
+│  GitHub Actions Workflow (ai-pr-loop.yml)                         │
+│  ┌────────────────────────────────────────────────────────────┐  │
+│  │ Orchestration only: triggers, env vars, secrets, steps     │  │
+│  └────────────────────────────────────────────────────────────┘  │
+│         │                                                        │
+│         ▼                                                        │
+│  agdt-ai-pr-loop (Python CLI entry point)                        │
+└──────────────────────────────────────────────────────────────────┘
+         │
+         ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  agentic_devtools/cli/ci/ (Python business logic)                │
+│                                                                  │
+│  orchestrator.py ─── Extended state machine:                     │
+│    ├── Guards (existing)                                         │
+│    ├── CI status check (existing)                                │
+│    ├── Review evaluation (existing)                              │
+│    ├── NEW: Trigger comment posting                              │
+│    ├── NEW: Result comment polling                               │
+│    ├── NEW: Thread resolution                                    │
+│    ├── NEW: Commit squash + message generation                   │
+│    └── NEW: Force-push with SHA verification                     │
+│                                                                  │
+│  NEW modules:                                                    │
+│  ├── trigger.py       (trigger comment logic + dedup)            │
+│  ├── result_poller.py (agent result detection + timeout)         │
+│  ├── thread_resolver.py (reply + resolve orchestration)          │
+│  ├── squash.py        (commit squash + message generation)       │
+│  └── templates.py     (template selection + rendering)           │
+│                                                                  │
+│  Reused (direct Python calls, external to cli/ci/):              │
+│  ├── agentic_devtools/cli/github/resolve_review_threads.py       │
+│  └── agentic_devtools/cli/github/review_reply.py                 │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### Module Interaction Flow
+
+```text
+Event (pull_request_review / workflow_run)
+  → orchestrator.run_ai_pr_loop()
+    → guards (existing)
+    → CI status check (existing)
+    → copilot_review_ready? (new check)
+    → trigger.post_trigger_comment()
+      → templates.select_template()
+      → templates.render_trigger_comment()
+      → dedup check (find_comment with marker)
+      → provider.post_comment() [PAT-authenticated]
+    → result_poller.poll_for_result_comment()
+      → filter by sentinel marker (<!-- copilot-agent-result -->)
+      → secondary confirmation: comment author == github-actions[bot]
+      → 30s interval, 15min max
+      → timeout → post failure comment (via GITHUB_TOKEN) + exit non-zero
+    → thread_resolver.resolve_copilot_review_threads()
+      → calls review_reply functions directly
+      → calls resolve_review_threads functions directly
+    → squash.squash_and_force_push()
+      → generate commit message (Copilot SDK or fallback)
+      → SHA verification before force-push
+      → git push --force-with-lease [PAT-authenticated]
+```
+
+## 4. Implementation Phases
+
+### Phase 1: Template System & Comment Rendering (FR-003, FR-004, FR-005, FR-006)
+
+**Constraints:**
+
+- **FR-006 compliance**: All rendered trigger comments MUST begin with `@copilot` at the very start of the comment body.
+  Templates MUST place `@copilot` as the first content, with any metadata (e.g., dedup markers) appended after
+  the `@copilot` prefix line.
+
+**Deliverables:**
+
+- `agentic_devtools/prompts/ci/pr_review_process.md` template (must start with `@copilot`)
+- `agentic_devtools/prompts/ci/ci_review_process.md` template (must start with `@copilot`)
+- `agentic_devtools/cli/ci/templates.py` — template selection and rendering module
+- Unit tests following 1:1:1 structure (include assertion that rendered output starts with `@copilot`)
+
+**New files:**
+
+| File | Purpose |
+|------|---------|
+| `agentic_devtools/prompts/ci/pr_review_process.md` | Template for suppressed-comments trigger |
+| `agentic_devtools/prompts/ci/ci_review_process.md` | Template for CI-only trigger |
+| `agentic_devtools/cli/ci/templates.py` | `select_template()`, `render_trigger_comment()` |
+| `tests/unit/cli/ci/templates/test_select_template.py` | Template selection tests |
+| `tests/unit/cli/ci/templates/test_render_trigger_comment.py` | Rendering tests |
+
+### Phase 2: Trigger Comment & Deduplication (FR-001, FR-002, FR-006, FR-012)
+
+**Constraints:**
+
+- The dedup marker (`<!-- copilot-trigger:REVIEW_ID -->`) MUST be appended after the initial `@copilot` prefix line (not before it) to preserve FR-006 compliance.
+- `post_trigger_comment()` MUST validate that the final comment body starts with `@copilot` before posting.
+
+**Deliverables:**
+
+- `agentic_devtools/cli/ci/trigger.py` — trigger comment posting with deduplication
+- Integration with `CIPlatformProvider.post_comment()` and `find_comment()`
+- Hidden HTML marker for deduplication (`<!-- copilot-trigger:REVIEW_ID -->`)
+- Unit tests
+
+**New files:**
+
+| File | Purpose |
+|------|---------|
+| `agentic_devtools/cli/ci/trigger.py` | `post_trigger_comment()`, `is_duplicate_trigger()` |
+| `tests/unit/cli/ci/trigger/test_post_trigger_comment.py` | Trigger posting tests |
+| `tests/unit/cli/ci/trigger/test_is_duplicate_trigger.py` | Dedup detection tests |
+
+### Phase 3: Result Comment Polling (FR-014, FR-016)
+
+**Constraints:**
+
+- **FR-014 compliance**: Polling MUST filter primarily by the sentinel marker (`<!-- copilot-agent-result -->`) in the comment body, with the `github-actions[bot]` author login as secondary
+  confirmation.
+- The result comment MUST be posted by the workflow step using the workflow's `GITHUB_TOKEN` (not the PAT) to ensure the author is deterministically `github-actions[bot]`.
+- Timeout failure comments (FR-016) MUST also be posted via `GITHUB_TOKEN` (author: `github-actions[bot]`).
+
+**Deliverables:**
+
+- `agentic_devtools/cli/ci/result_poller.py` — polling logic with timeout + failure comment
+- Sentinel marker detection (`<!-- copilot-agent-result -->`) + author login verification (`github-actions[bot]`)
+- Timeout failure comment with workflow run link (posted via `GITHUB_TOKEN`)
+- Unit tests
+
+**New files:**
+
+| File | Purpose |
+|------|---------|
+| `agentic_devtools/cli/ci/result_poller.py` | `poll_for_result_comment()`, `post_timeout_failure()` |
+| `tests/unit/cli/ci/result_poller/test_poll_for_result_comment.py` | Polling logic tests |
+| `tests/unit/cli/ci/result_poller/test_post_timeout_failure.py` | Timeout failure tests |
+
+### Phase 4: Thread Resolution Orchestration (FR-007, FR-008)
+
+**Deliverables:**
+
+- `agentic_devtools/cli/ci/thread_resolver.py` — orchestrates reply + resolve
+- Direct Python calls to existing `resolve_review_threads` and `review_reply` functions
+- Retry logic (3 retries per NFR-002)
+- Unit tests
+
+**New files:**
+
+| File | Purpose |
+|------|---------|
+| `agentic_devtools/cli/ci/thread_resolver.py` | `resolve_copilot_review_threads()` |
+| `tests/unit/cli/ci/thread_resolver/test_resolve_copilot_review_threads.py` | Resolution tests |
+
+### Phase 5: Commit Squash & Force-Push (FR-009, FR-010, FR-011, FR-017)
+
+**Deliverables:**
+
+- `agentic_devtools/cli/ci/squash.py` — squash commits, generate message, force-push
+- Copilot SDK integration with 5-minute timeout + local fallback
+- SHA verification before force-push (FR-017)
+- Unit tests
+
+**New files:**
+
+| File | Purpose |
+|------|---------|
+| `agentic_devtools/cli/ci/squash.py` | `squash_and_force_push()`, `generate_commit_message()`, `_local_fallback_message()` |
+| `tests/unit/cli/ci/squash/test_squash_and_force_push.py` | Squash + push tests |
+| `tests/unit/cli/ci/squash/test_generate_commit_message.py` | Message generation tests |
+| `tests/unit/cli/ci/squash/test_local_fallback_message.py` | Fallback message tests |
+
+### Phase 6: Orchestrator Integration (FR-013, NFR-005, NFR-006)
+
+**Deliverables:**
+
+- Extend `run_ai_pr_loop()` with new Copilot review response path
+- Structured audit logging for each step
+- Update workflow YAML to pass required secrets/env vars
+- Integration tests
+
+**Modified files:**
+
+| File | Change |
+|------|--------|
+| `agentic_devtools/cli/ci/orchestrator.py` | Add copilot response path after review evaluation |
+| `agentic_devtools/cli/ci/models.py` | Add `CopilotReviewContext` dataclass |
+| `agentic_devtools/cli/ci/__init__.py` | Export new modules |
+| `.github/workflows/ai-pr-loop.yml` | Verify existing `COPILOT_GITHUB_TOKEN` secret mapping; add `GITHUB_TOKEN` env var to result-posting and timeout-failure steps for `github-actions[bot]` authorship |
+| `pyproject.toml` | No new entry points needed (extends existing `agdt-ai-pr-loop`) |
+
+### Phase 7: End-to-End Testing & Documentation
+
+**Deliverables:**
+
+- Workflow integration tests (`tests/workflows/`)
+- Documentation updates
+- PR check validation
+
+## 5. Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| Copilot SDK unavailable/undocumented | Medium | Medium | Local fallback generates message from PR title + commit history |
+| Race condition during force-push | Low | High | SHA verification (FR-017) + `--force-with-lease` |
+| Polling timeout false positives | Low | Medium | 15min window is generous; failure comment provides debugging link |
+| Duplicate triggers from concurrent workflow runs | Medium | Low | Dedup marker + concurrency group in YAML |
+| PAT permission issues | Low | High | Clear error messages (NFR-007); document required scopes |
+| Existing `agdt-gh-*` function API changes | Low | Medium | Pin to internal function signatures; add integration tests |
+
+## 6. Dependencies
+
+### External Dependencies
+
+- GitHub REST API v3 (PR comments, reviews, check runs)
+- GitHub GraphQL API (thread resolution — already used)
+- Copilot SDK (commit message generation — with fallback)
+- `gh` CLI (already required; pinned in CI)
+
+### Internal Dependencies
+
+- `agentic_devtools.cli.ci.provider.CIPlatformProvider` — post_comment, find_comment
+- `agentic_devtools.cli.ci.github_provider.GitHubActionsProvider` — concrete implementation
+- `agentic_devtools.cli.ci.retry.retry_with_backoff` — retry decorator
+- `agentic_devtools.cli.github.resolve_review_threads` — thread resolution internals
+- `agentic_devtools.cli.github.review_reply` — reply posting internals
+- `agentic_devtools.prompts.loader.load_ci_template` — template loading
+- `agentic_devtools.prompts.loader.substitute_variables` — Jinja2 rendering
+
+### Sequencing Constraints
+
+- Phase 1 (templates) can start immediately — no dependencies
+- Phase 2 (trigger) depends on Phase 1 templates
+- Phase 3 (polling) depends on Phase 2 (needs trigger comment to define polling start)
+- Phase 4 (thread resolution) depends on Phase 3 (needs result comment reference)
+- Phase 5 (squash) depends on Phase 4 (runs after threads resolved)
+- Phase 6 (orchestrator) depends on all prior phases
+- Phase 7 (E2E) depends on Phase 6
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*