agentic-devtools 0.2.159__tar.gz → 0.2.161__tar.gz

{agentic_devtools-0.2.159 → agentic_devtools-0.2.161}/PKG-INFO

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

{agentic_devtools-0.2.159 → agentic_devtools-0.2.161}/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.159'
-__version_tuple__ = version_tuple = (0, 2, 159)
+__version__ = version = '0.2.161'
+__version_tuple__ = version_tuple = (0, 2, 161)
 
 __commit_id__ = commit_id = None

{agentic_devtools-0.2.159 → agentic_devtools-0.2.161}/agentic_devtools/cli/ci/ado_provider.py

@@ -162,6 +162,10 @@ class AzureDevOpsProvider(CIPlatformProvider):
         """Not implemented for ADO stub."""
         raise NotImplementedError("AzureDevOpsProvider.request_reviewer() not yet implemented")
 
+    def count_unresolved_review_threads(self, pr_number: int) -> int:
+        """Not implemented for ADO stub."""
+        raise NotImplementedError("AzureDevOpsProvider.count_unresolved_review_threads() not yet implemented")
+
     def list_pr_files(self, pr_number: int) -> list[str]:
         """Not implemented for ADO stub."""
         raise NotImplementedError("AzureDevOpsProvider.list_pr_files() not yet implemented")

{agentic_devtools-0.2.159 → agentic_devtools-0.2.161}/agentic_devtools/cli/ci/github_provider.py

@@ -925,6 +925,45 @@ class GitHubActionsProvider(CIPlatformProvider):
             ) in signals.items()
         }
 
+    @retry_with_backoff()
+    def count_unresolved_review_threads(self, pr_number: int) -> int:
+        """Count unresolved review comment threads on a pull request.
+
+        Reuses the existing thread signals query and counts threads whose
+        isResolved status is False. Each unique thread is counted once
+        regardless of how many comments it contains.
+        """
+        owner, repo_name = self._resolve_repo().split("/", maxsplit=1)
+        cursor: str | None = None
+        unresolved = 0
+
+        while True:
+            variables: dict[str, Any] = {
+                "owner": owner,
+                "repoName": repo_name,
+                "prNumber": pr_number,
+            }
+            if cursor is not None:
+                variables["threadsCursor"] = cursor
+            response = _gh_api(
+                "graphql",
+                method="POST",
+                body={"query": _REVIEW_THREADS_QUERY, "variables": variables},
+            )
+            data = json.loads(response)
+            thread_data = data["data"]["repository"]["pullRequest"]["reviewThreads"]
+            for thread in thread_data.get("nodes", []):
+                if not thread.get("isResolved", False):
+                    unresolved += 1
+
+            page_info = thread_data.get("pageInfo", {})
+            if page_info.get("hasNextPage") is True and page_info.get("endCursor"):
+                cursor = page_info["endCursor"]
+            else:
+                break
+
+        return unresolved
+
     @retry_with_backoff()
     def approve_pr(self, pr_number: int, head_sha: str, body: str) -> bool:
         """Approve a pull request.

{agentic_devtools-0.2.159 → agentic_devtools-0.2.161}/agentic_devtools/cli/ci/orchestrator.py

@@ -532,9 +532,25 @@ def _request_copilot_review_if_needed(
     failure_context: str,
     repair_dispatched: bool = False,
     copilot_review_comment_count: int = 0,
+    unresolved_threads: int = 0,
 ) -> str | None:
     """Request Copilot review unless it is already pending or already exhausted."""
 
+    # Gate: block review request when unresolved review threads exist
+    if unresolved_threads == -1:
+        logger.info(
+            "PR #%d skipping Copilot review request: unresolved thread count unavailable — awaiting resolution",
+            pr_number,
+        )
+        return "awaiting_thread_resolution"
+    if unresolved_threads != 0:
+        logger.info(
+            "PR #%d skipping Copilot review request: %d unresolved thread(s) — awaiting resolution",
+            pr_number,
+            unresolved_threads,
+        )
+        return "awaiting_thread_resolution"
+
     skip_reason = _get_copilot_review_request_skip_reason(
         pr_meta,
         copilot_review,
@@ -1078,6 +1094,17 @@ def run_ai_pr_loop(
         logger.info("PR #%d passed dedup (count=%d) and cycle (count=%d) guards", pr_number, dedup_count, cycle_count)
     _log_endgroup()
 
+    # Fetch unresolved review thread count once, after all early-exit guards.
+    try:
+        unresolved_thread_count = provider.count_unresolved_review_threads(pr_number)
+    except Exception as exc:
+        logger.warning(
+            "PR #%d failed to count unresolved review threads: %s — failing closed",
+            pr_number,
+            exc,
+        )
+        unresolved_thread_count = -1
+
     # Step 5: Evaluate reviews
     # Collapse to effective latest state per reviewer (highest review.id wins).
     # All COPILOT_LOGINS aliases are normalized to a single canonical key so
@@ -1421,6 +1448,7 @@ def run_ai_pr_loop(
             failure_context="PR",
             repair_dispatched=False,
             copilot_review_comment_count=len(copilot_review_comments),
+            unresolved_threads=unresolved_thread_count,
         )
         summary["decision"] = "awaiting_copilot_review_after_ci"
         if request_skip_reason is not None:
@@ -1568,6 +1596,7 @@ def run_ai_pr_loop(
             failure_context="draft",
             repair_dispatched=False,
             copilot_review_comment_count=len(copilot_review_comments),
+            unresolved_threads=unresolved_thread_count,
         )
         summary["decision"] = "published_awaiting_review"
         if request_skip_reason is not None:
@@ -1595,6 +1624,7 @@ def run_ai_pr_loop(
             failure_context="PR",
             repair_dispatched=False,
             copilot_review_comment_count=len(copilot_review_comments),
+            unresolved_threads=unresolved_thread_count,
         )
         summary["decision"] = "awaiting_copilot_review"
         if request_skip_reason is not None:

{agentic_devtools-0.2.159 → agentic_devtools-0.2.161}/agentic_devtools/cli/ci/pipeline/actions/squash.py

@@ -30,6 +30,7 @@ class SquashAction:
 
     Preconditions:
     - Commits above merge-base > 1
+    - All review threads resolved
     - No repair dispatched in this run (keeps HEAD stable for the repair cycle)
     - No active Copilot coding session (pending review does NOT block squash)
 
@@ -54,6 +55,19 @@ class SquashAction:
                 details=f"Only {snapshot.commit_count} commit(s) — nothing to squash",
             )
 
+        unresolved_threads = derived.get("unresolved_threads", snapshot.unresolved_threads)
+        preconditions["all_threads_resolved"] = unresolved_threads == 0
+        if unresolved_threads > 0:
+            return ActionResult(
+                name=self.name,
+                decision=ActionDecision.SKIP,
+                preconditions=preconditions,
+                details=(
+                    f"unresolved_threads: {unresolved_threads} thread(s) still open — "
+                    "squash blocked until all review threads are resolved"
+                ),
+            )
+
         # Repair dispatch in this run should keep HEAD stable for the repair cycle.
         repair_dispatched = getattr(derived, "repair_dispatched", False)
         preconditions["no_repair_dispatched"] = not repair_dispatched

{agentic_devtools-0.2.159 → agentic_devtools-0.2.161}/agentic_devtools/cli/ci/pipeline/command.py

@@ -46,7 +46,7 @@ def run_ai_pr_loop_v2(
     trigger type.
 
     Pipeline ordering:
-        Guards → Publish → DispatchRepair → Squash → ResolveThreads → RequestReview → Approve → Merge
+        Guards → Publish → DispatchRepair → ResolveThreads → Squash → RequestReview → Approve → Merge
 
     ResolveThreads runs before RequestReview so that resolved threads are reflected in
     derived state before the review-request guard evaluates unresolved_threads.
@@ -94,8 +94,8 @@ def run_ai_pr_loop_v2(
             GuardsAction(),
             PublishAction(),
             DispatchRepairAction(),
-            SquashAction(),
             ResolveThreadsAction(),
+            SquashAction(),
             RequestReviewAction(),
             ApproveAction(),
             MergeAction(),

{agentic_devtools-0.2.159 → agentic_devtools-0.2.161}/agentic_devtools/cli/ci/pipeline/snapshot.py

@@ -96,6 +96,14 @@ class DerivedState:
         """Set a derived state override."""
         self._overrides[name] = value
 
+    def get(self, name: str, default: Any = None) -> Any:
+        """Get a derived state value with default fallback."""
+        if name.startswith("_"):
+            raise AttributeError(name)
+        if name in self._overrides:
+            return self._overrides[name]
+        return getattr(self._snapshot, name, default)
+
     @property
     def snapshot(self) -> PRStateSnapshot:
         """Access the underlying immutable snapshot."""

{agentic_devtools-0.2.159 → agentic_devtools-0.2.161}/agentic_devtools/cli/ci/provider.py

@@ -165,6 +165,17 @@ class CIPlatformProvider(ABC):
             reviewer: Username of the reviewer to request.
         """
 
+    @abstractmethod
+    def count_unresolved_review_threads(self, pr_number: int) -> int:
+        """Count unresolved review comment threads on a pull request.
+
+        Args:
+            pr_number: Pull request number.
+
+        Returns:
+            Number of unresolved review threads.
+        """
+
     @abstractmethod
     def list_pr_files(self, pr_number: int) -> list[str]:
         """List files changed in a pull request.

agentic_devtools-0.2.161/specs/1749-auto-apply-code-review/checklists/requirements.md

@@ -0,0 +1,43 @@
+# Specification Quality Checklist: Auto-apply Code Review Suggestions via GraphQL in AI PR Loop
+
+**Purpose**: Validate specification completeness before proceeding to planning
+**Created**: 2026-06-03
+**Feature**: [spec.md](../spec.md)
+**Source Issue**: #1749
+
+## Content Quality
+
+- [ ] CHK001 Each user story clearly articulates developer/operator value (e.g., US1 focuses on eliminating AI agent token waste for deterministic fixes, US2 focuses on pipeline reliability)
+- [ ] CHK002 All 5 user stories follow "As a [role], I want [capability], so that [benefit]" format with explicit role (developer, pipeline operator, repository maintainer)
+- [ ] CHK003 Priority assignments (P1–P3) include justification paragraphs explaining relative ordering and dependencies (e.g., US3 depends on US1, US5 is deferrable)
+- [ ] CHK004 Functional requirements FR-001 through FR-013 describe observable system behavior without prescribing internal class hierarchies, file layouts, or function signatures
+
+## Requirement Completeness
+
+- [ ] CHK005 Each acceptance scenario in US1–US5 uses Given/When/Then format with concrete, verifiable assertions (specific counts, specific field values, specific action outcomes)
+- [ ] CHK006 Edge cases section covers deleted file references, single conflicting suggestion, branch protection violations, concurrent loop executions, and bisection producing multiple commits with
+  explicit expected behavior for each
+- [ ] CHK007 All 12 acceptance scenarios across US1–US5 specify observable outcomes (commit counts, thread resolution states, SKIP/EXECUTE decisions, comment formats) rather than internal state
+- [ ] CHK008 Success criteria SC-001 through SC-007 include quantifiable thresholds (100%, 90%, 10 seconds, 60%, 95% branch coverage) with measurement methods specified
+- [ ] CHK009 Scope boundaries are defined: hardcoded batch size of 50 (FR-011), per-repo configurability explicitly deferred, summary comment (US5) marked P3/deferrable, no manual squashing by the
+  action
+- [ ] CHK010 Dependencies on existing pipeline components are documented: `GuardsAction` blocking mechanism, `DispatchRepairAction` preconditions, `SquashAction` deferral behavior, `DerivedState` for
+  `ExclusionContext` passing, `invalidates_snapshot` pipeline runner support
+
+## Feature Readiness
+
+- [ ] CHK011 All 13 functional requirements (FR-001 through FR-013) have at least one corresponding acceptance scenario or edge case that validates the requirement's behavior
+- [ ] CHK012 User scenarios cover the full decision tree: all suggestions applied (US1-AS1), partial apply with repair (US2-AS1), zero suggestions (US1-AS3), guard-blocked (US4-AS1/AS2), and transient
+  failure (US2-AS3)
+- [ ] CHK013 Success criteria SC-001 and SC-003 specify measurement periods (2-week observation) and instrumentation methods (action-level timing), SC-004 specifies verification method (unit tests
+  with 95% branch coverage)
+- [ ] CHK014 Requirements reference GraphQL mutation names (`applySuggestedChanges`), API field names (`outdated`, `databaseId`), and action result patterns (`ActionDecision.SKIP/EXECUTE/FAILED`) as
+  domain terminology without dictating module structure, class inheritance, or file organization
+
+## Notes
+
+- This checklist was generated from the specification content for issue #1749
+- Items marked incomplete require spec updates before proceeding to planning
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*

{agentic_devtools-0.2.159 → agentic_devtools-0.2.161}/specs/1749-auto-apply-code-review/spec.md

@@ -1,6 +1,6 @@
 # Feature Specification: Auto-apply Code Review Suggestions via GraphQL in AI PR Loop
 
-**Feature Branch**: `speckit/1749/phase-1-specify`  
+**Feature Branch**: `speckit/1749/phase-2-clarify`  
 **Created**: 2026-06-03  
 **Status**: Draft  
 **Input**: User description: "Implement an automated step in the ai-pr-loop workflow to programmatically apply all available autofixable GitHub PR review suggestions using the GraphQL
@@ -9,6 +9,34 @@
 
 ---
 
+## Clarifications
+
+### Session 2026-06-03
+
+- Q: Should the maximum suggestion batch size threshold (FR-011) be configurable per-repository via `.github/agdt-config.json`, or is a hardcoded default of 50 sufficient for the initial
+  implementation? → A: A hardcoded threshold of 50 is sufficient for the initial implementation. Per-repository configuration via `.github/agdt-config.json` should be deferred to a follow-up iteration
+  once production usage patterns are observed.
+
+- Q: In the partial-apply + repair-dispatched path, should `SquashAction` squash the autofix commit together with the repair agent's commit in the same loop run, or should it defer until a subsequent
+  run? → A: `SquashAction` should defer squash when `repair_dispatched` is True (it already does via its `no_repair_dispatched` precondition). In the "all suggestions auto-applied, no repair" path,
+  `SquashAction` will squash normally since `repair_dispatched` is False. In the partial-apply + repair path, `SquashAction` defers in the current run and squashes all commits (autofix + repair) on
+  the next run after the repair agent completes. No behavioral change to `SquashAction` is required.
+
+- Q: Should `ApplySuggestionsAction` set `invalidates_snapshot = True` on its `ActionResult` when it successfully commits, causing the pipeline runner to refresh the snapshot before evaluating
+  `DispatchRepairAction`? → A: Yes. When `ApplySuggestionsAction` successfully applies suggestions and produces a commit, it MUST set `invalidates_snapshot = True` on its `ActionResult`. This ensures
+  `DispatchRepairAction` evaluates against the refreshed post-commit state (new HEAD SHA, updated CI status, updated review thread resolution). `DispatchRepairAction` must have
+  `runs_after_invalidation = True` to opt into the refreshed snapshot path.
+
+- Q: How does the system identify which review comment IDs to pass to repair dispatch for exclusion — by the suggestion's GraphQL node ID, or by the parent review comment's database ID (`databaseId`)?
+  → A: The exclusion context uses the parent review comment's REST API numeric ID (`databaseId` from GraphQL), since `provider.list_review_comments()` in the repair dispatch already works with REST
+  API comment IDs. The `ExclusionContext.resolved_comment_ids` field stores these numeric IDs.
+
+- Q: When bisection fallback produces multiple mutation calls, should each successful call produce its own commit, or should the action attempt to consolidate into a single commit? → A: Each
+  successful `applySuggestedChanges` mutation call produces its own commit (this is GitHub API behavior — each mutation creates one commit). The `ApplySuggestionsResult.commit_shas` list captures all
+  commits produced. `SquashAction` will consolidate them on a subsequent run. The action should NOT attempt manual squashing; it relies on the existing pipeline squash mechanism.
+
+---
+
 ## Problem Statement
 
 The AI PR Loop (`ai-pr-loop.yml`) currently treats all actionable Copilot review comments uniformly — when a review with suggestions lands, the pipeline dispatches a full agentic repair job that must
@@ -150,20 +178,22 @@ during automated processing, especially when reviewing the PR timeline after the
 ### Edge Cases
 
 The system must handle the following boundary conditions:
-What happens when a suggestion references a file that was deleted in a subsequent
-commit pushed between review and loop execution? The action should detect this via
-the `outdated` field or mutation error and exclude the suggestion gracefully.
-How does the system behave when the PR has exactly one suggestion and it conflicts?
-The bisection fallback should degrade gracefully to a no-op since there is nothing
-left to split, and the single suggestion passes through to repair dispatch.
-What happens if the `applySuggestedChanges` mutation succeeds but the resulting
-commit triggers a branch protection rule violation (e.g., required status checks)?
-The pipeline should treat this as any other post-commit state and re-evaluate CI
-status in the next loop iteration.
-How does the system handle concurrent loop executions where two instances attempt to
-apply the same suggestions? The deduplication guard (existing `check_deduplication`
-mechanism) should prevent double-application, and the GraphQL mutation itself is
-idempotent for already-resolved suggestions.
+
+- **Deleted file reference**: When a suggestion references a file that was deleted in a subsequent commit pushed between review and loop execution, the action should detect this via the `outdated`
+  field or mutation error and exclude the suggestion gracefully, logging it as skipped with reason "file deleted / outdated".
+
+- **Single conflicting suggestion**: When the PR has exactly one suggestion and it conflicts, the bisection fallback should degrade gracefully to a no-op since there is nothing left to split, and the
+  single suggestion passes through to repair dispatch.
+
+- **Branch protection violation**: When the `applySuggestedChanges` mutation succeeds but the resulting commit triggers a branch protection rule violation (e.g., required status checks), the pipeline
+  should treat this as any other post-commit state and re-evaluate CI status in the next loop iteration. The `invalidates_snapshot = True` flag refreshes pipeline state; only actions that opt in via
+  `runs_after_invalidation=True` continue in the same run.
+
+- **Concurrent loop executions**: When two instances attempt to apply the same suggestions, the deduplication guard (existing `check_deduplication` mechanism) should prevent double-application, and
+  the GraphQL mutation itself is idempotent for already-resolved suggestions (returning a no-op or error that the action handles gracefully).
+
+- **Bisection producing multiple commits**: When bisection fallback applies suggestions in multiple mutation calls, each call produces one commit (GitHub API behavior). The `commit_shas` list in
+  `ApplySuggestionsResult` records all produced commits. `SquashAction` consolidates them on a subsequent pipeline run. The action does NOT attempt manual squashing.
 
 ---
 
@@ -182,11 +212,12 @@ idempotent for already-resolved suggestions.
 - **FR-004**: The system MUST exclude suggestions with `outdated: true` from any application attempt and log them as skipped for auto-apply; this exclusion MUST NOT, by itself, remove their parent
   review comments from repair dispatch context.
 
-- **FR-005**: The system MUST record the set of successfully applied review comment IDs (the root comment ID for each suggestion thread) and pass them to the repair dispatch action so that
-  `provider.list_review_comments()` can exclude those comments from the repair context.
+- **FR-005**: The system MUST record the `databaseId` of each `PullRequestReviewComment` node that contains an applied suggestion (i.e., the `reviewComment.databaseId` REST API numeric ID) and pass
+  those IDs to the repair dispatch action via `ExclusionContext` so that `provider.list_review_comments()` can exclude those comments from the repair context.
 
 - **FR-006**: The system MUST re-evaluate whether repair dispatch is necessary after suggestions are applied — if no unresolved actionable comments remain AND CI is not failing, the repair dispatch
-  action MUST return SKIP.
+  action MUST return SKIP. This re-evaluation is facilitated by `invalidates_snapshot = True` on the apply-suggestions `ActionResult`, which triggers a snapshot refresh before `DispatchRepairAction`
+  evaluates.
 
 - **FR-007**: The apply-suggestions action MUST be positioned after `GuardsAction` in the pipeline sequence so that the pipeline runner's existing guard-blocking mechanism applies. When any guard
   fires (`GuardsAction` returns `ActionDecision.BLOCKED`), the pipeline runner marks the apply-suggestions action as `ActionDecision.BLOCKED_BY_GUARD` and never evaluates or executes it, ensuring
@@ -198,11 +229,17 @@ idempotent for already-resolved suggestions.
 - **FR-009**: The system MUST be positioned in the pipeline action sequence after `GuardsAction` evaluation and before `DispatchRepairAction`, ensuring guards are checked first and repair dispatch
   receives the updated post-autofix state.
 
-- **FR-010**: The system MUST handle GitHub API rate limits and transient errors (5xx responses) with retry logic (up to 2 retries with exponential backoff) before reporting failure.
+- **FR-010**: The system MUST handle GitHub API rate limits and transient errors (5xx responses) with retry logic (up to 2 retries with exponential backoff, starting at 1 second) before reporting
+  failure. On exhausted retries, the action returns `ActionDecision.SKIP` (not `FAILED`) to avoid halting the pipeline.
+
+- **FR-011**: The system MUST NOT apply suggestions when the total number of applicable suggestions exceeds a hardcoded safety threshold of 50, logging a warning and deferring to repair dispatch
+  instead. This prevents runaway batch commits on PRs with an unusually high suggestion count that may indicate a systemic review pattern requiring human judgment. Per-repository configurability via
+  `.github/agdt-config.json` is deferred to a follow-up iteration.
+
+- **FR-012**: When the apply-suggestions action successfully produces one or more commits, it MUST set `invalidates_snapshot = True` on its `ActionResult`, causing the pipeline runner to refresh the
+  `PRStateSnapshot` before evaluating subsequent actions (specifically `DispatchRepairAction`).
 
-- **FR-011**: The system MUST NOT apply suggestions when the total number of applicable suggestions exceeds a configurable safety threshold (default: 50), logging a warning and deferring to repair
-  dispatch instead. This prevents runaway batch commits on PRs with an unusually high suggestion count that may indicate a systemic review pattern requiring human judgment. [NEEDS CLARIFICATION:
-  Should the threshold be configurable per-repository or is a global default sufficient for the initial implementation?]
+- **FR-013**: `DispatchRepairAction` MUST have `runs_after_invalidation = True` to opt into the refreshed snapshot path when `ApplySuggestionsAction` invalidates the snapshot.
 
 ### Non-Functional Requirements
 
@@ -222,18 +259,19 @@ idempotent for already-resolved suggestions.
 ### Key Entities
 
 - **SuggestedChange**: Represents a single autofixable code change proposed in a review comment. Key attributes: `id` (GraphQL node ID), `outdated` (boolean indicating staleness), parent
-  `reviewThread` (for thread resolution tracking).
+  `reviewComment.databaseId` (REST API numeric ID from the parent `PullRequestReviewComment`, used for exclusions), parent `reviewThread` (for thread resolution tracking).
 
 - **ApplySuggestionsResult**: The output of the apply-suggestions action,
   containing: `applied_ids` (list of successfully applied suggestion IDs),
   `skipped_ids` (list of suggestions excluded due to outdated status or
   conflicts), `commit_shas` (ordered list of autofix commit SHAs produced by
-  batch and/or fallback application, empty when nothing was applied), `error`
+  batch and/or fallback application — each `applySuggestedChanges` mutation call produces exactly one commit, so multiple entries indicate bisection fallback was used; empty when nothing was applied),
+  `error`
   (optional error detail for partial failures).
 
 - **ExclusionContext**: Data structure passed from the apply-suggestions action
-  to the repair dispatch action, containing the set of resolved review comment
-  IDs (root thread comments) that should be excluded from repair comment
+  to the repair dispatch action via `DerivedState`, containing the set of resolved review comment
+  IDs (parent review comment REST API numeric IDs / `databaseId`) that should be excluded from repair comment
   fetching.
 
 ---
@@ -248,12 +286,13 @@ idempotent for already-resolved suggestions.
   2-week production observation period.
 
 - **SC-002**: The batch application of suggestions produces exactly 1 commit per successful action execution in at least 90% of cases (the remaining 10% accounts for bisection fallback scenarios
-  requiring multiple mutations but still targeting a single squashed commit).
+  requiring multiple mutations, each producing one commit; `SquashAction` consolidates them on a subsequent run).
 
 - **SC-003**: The apply-suggestions action adds no more than 10 seconds of wall-clock time to the AI PR Loop execution for PRs with 10 or fewer suggestions, as measured by action-level timing
   instrumentation.
 
-- **SC-004**: The repair dispatch action's `review_comments` list correctly excludes 100% of review comment IDs (root thread comments) that were auto-applied, verified by unit tests covering the
+- **SC-004**: The repair dispatch action's `review_comments` list correctly excludes 100% of review comment IDs (parent review comment REST API numeric IDs) that were auto-applied, verified by unit
+  tests covering the
   exclusion logic with at least 95% branch coverage on the new action module.
 
 - **SC-005**: Zero false positives on guard enforcement — the action MUST never produce a commit on a fork PR or a PR touching privileged paths, validated by integration tests that assert SKIP on
@@ -268,11 +307,12 @@ idempotent for already-resolved suggestions.
 
 ## Open Questions
 
-- [NEEDS CLARIFICATION]: `SquashAction` already squashes when `commit_count > 1`, no repair was dispatched, and no Copilot session is active; in the "all suggestions auto-applied, no repair"
-  path this should already produce a single commit in the same loop run. Clarify the decision point for partial-apply + repair-dispatched paths where `SquashAction` intentionally defers.
+- **Resolved** (see Clarifications): `SquashAction` already squashes when `commit_count > 1`, no repair was dispatched, and no Copilot session is active; in the "all suggestions auto-applied, no
+  repair" path this already produces a single commit in the same loop run. In the partial-apply + repair-dispatched path, `SquashAction` defers (via its `no_repair_dispatched` precondition) and
+  squashes all commits on the next run after repair completes.
 
-- [NEEDS CLARIFICATION]: Should the maximum suggestion batch size threshold (FR-011) be configurable per-repository via `.github/agdt-config.json`, or is a hardcoded default of 50 sufficient for the
-  initial implementation?
+- **Resolved** (see Clarifications): The maximum suggestion batch size threshold (FR-011) uses a hardcoded default of 50 for the initial implementation. Per-repository configurability is deferred to a
+  follow-up iteration.
 
 ---
 *Generated by Copilot SDK (claude-opus-4.6)*

agentic_devtools-0.2.161/specs/1756-remove-deps-installs-and/checklists/requirements.md

@@ -0,0 +1,42 @@
+# Specification Quality Checklist: Remove --no-deps Installs and Make github-copilot-sdk a Direct Dependency
+
+**Purpose**: Validate specification completeness before proceeding to planning
+**Created**: 2026-06-03
+**Feature**: [spec.md](../spec.md)
+**Source Issue**: #1756
+
+## Content Quality
+
+- [ ] CHK001 Each user story clearly articulates CI maintainer, developer, and script maintainer value (Stories 1–4 each state a distinct pain point and benefit)
+- [ ] CHK002 All four user stories follow "As a [role], I want [goal] so that [benefit]" format with explicit role identification (CI workflow maintainer, developer, maintainer of copilot_generate.py,
+  local developer)
+- [ ] CHK003 Priority assignments (P1–P3) are justified with "Why this priority" rationale and Story 1/Story 2 both at P1 is explicitly defended
+- [ ] CHK004 Requirements FR-001 through FR-008 specify WHAT must change without prescribing HOW (no algorithm choices, no code snippets dictating implementation structure)
+
+## Requirement Completeness
+
+- [ ] CHK005 Each acceptance scenario in Stories 1–4 uses Given/When/Then format with verifiable assertions (e.g., "from copilot import CopilotClient succeeds" is executable)
+- [ ] CHK006 Edge cases document behavior for: older SDK versions, PyPI unavailability, removed `[copilot-sdk]` extra warning, and `--no-deps` removal in speckit-phase-progression.yml
+- [ ] CHK007 All acceptance scenarios specify observable outcomes rather than internal state (e.g., SC-003 specifies "zero subprocess calls to pip show" which is grep-verifiable)
+- [ ] CHK008 Success criteria SC-001 through SC-006 each define a measurable, binary pass/fail condition with specific numeric thresholds or exact behavioral assertions
+- [ ] CHK009 Scope boundaries are defined: explicitly includes `ai-pr-loop.yml`, `speckit-phase-progression.yml`, `copilot_generate.py`, and `pyproject.toml`; explicitly notes other
+  optional-dependency groups (langchain, dev) must remain unchanged
+- [ ] CHK010 Dependencies and assumptions are documented: assumes pip version supporting dependency resolution, assumes `github-copilot-sdk>=0.1.0,<1.0.0` availability on PyPI, assumes v1 upgrade is
+  deferred to a separate issue
+
+## Feature Readiness
+
+- [ ] CHK011 FR-001 through FR-008 each have at least one corresponding acceptance scenario or success criterion (FR-001→SC-005, FR-003→SC-001/SC-006, FR-005→SC-003, FR-006→SC-004, FR-008 has explicit
+  CHANGELOG requirement)
+- [ ] CHK012 User scenarios cover all affected personas: CI workflow maintainer (Story 1), SDK-upgrading developer (Story 2), script maintainer (Story 3), and first-time local developer (Story 4)
+- [ ] CHK013 Success criteria include quantifiable measures: "zero subprocess calls" (SC-003), "100% of existing tests" (SC-004), "10% installation time threshold" (NFR-001), and "single pip install
+  command" (SC-001)
+- [ ] CHK014 Requirements FR-001–FR-008 and NFR-001–NFR-003 avoid specifying implementation approach (no mention of specific refactoring patterns, code structure, or ordering of implementation steps)
+
+## Notes
+
+- This checklist was generated from the specification content for issue #1756
+- Items marked incomplete require spec updates before proceeding to planning
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*

{agentic_devtools-0.2.159 → agentic_devtools-0.2.161}/specs/1756-remove-deps-installs-and/spec.md

@@ -19,10 +19,31 @@ failure. When a dependency is declared as optional but actually required, pip's
 import the missing or incompatible module at runtime. This defeats one of the core purposes of a dependency management system: catching conflicts early and deterministically. Developers and CI runners
 waste time debugging import errors that should never occur if the dependency graph is honest.
 
-Additionally, the `copilot_generate.py` script contains 20+ lines of defensive diagnostic code that runs `pip show github-copilot-sdk` as a subprocess to detect whether the SDK was installed
-correctly. This runtime detection logic adds complexity, increases script execution time, and produces diagnostic messages that must be maintained in test assertions. By making the SDK a direct
-dependency, standard Python import error reporting becomes sufficient — if the SDK is missing, the package itself wasn't installed correctly, and the standard `ModuleNotFoundError` traceback
-communicates this clearly without custom diagnostic machinery.
+Additionally, the `copilot_generate.py` script (located at `.github/scripts/speckit-trigger/copilot_generate.py`) contains 20+ lines of defensive diagnostic code that runs `pip show github-copilot-sdk`
+as a subprocess to investigate import failures. This runtime detection logic adds complexity, increases script execution time, and produces diagnostic messages that must be maintained in test assertions.
+By making the SDK a direct dependency, standard Python import error reporting becomes sufficient here without custom diagnostic machinery.
+
+## Clarifications
+
+### Session 2026-06-03
+
+- Q: Should the `copilot_generate.py` diagnostic removal also remove the check for a conflicting `copilot` package (lines 39–51 that detect a shadowing `copilot` package), or only the
+  `pip show github-copilot-sdk` diagnostic? → A: Remove the entire defensive diagnostic block (lines 30–56 of the try/except handler), including the
+  conflicting-package check. Once the SDK is a direct dependency, separate `pip show` diagnostics are no longer required here; the except block should re-raise the ImportError (or allow it to
+  propagate naturally) rather than performing subprocess diagnostics.
+- Q: The spec references `pip install agentic-devtools` for the `ai-pr-loop.yml` workflow — should this remain as a PyPI install from the published package, or should it use `pip install .` (source
+  install) like `speckit-phase-progression.yml`? → A: Retain the existing install mechanism for each workflow: `ai-pr-loop.yml` uses `pip install agentic-devtools` (from PyPI) and
+  `speckit-phase-progression.yml` uses `pip install .` (from source). The spec already correctly distinguishes these in FR-003 and FR-004.
+- Q: After removing the `copilot-sdk` optional-dependencies group, should any deprecation notice or migration guidance be added to CHANGELOG.md or a migration document? → A: Yes, add a CHANGELOG.md
+  entry under the next release noting the removal of the `copilot-sdk` optional extra and that `github-copilot-sdk` is now installed automatically as a direct dependency. No separate migration
+  document is needed since the change is backward-compatible for users who were already installing the extra.
+- Q: The `speckit-phase-progression.yml` workflow (line 487) also uses `pip install . --no-deps` for `agentic-devtools` itself — should this `--no-deps` on the package install also be removed? → A:
+  Yes, absolutely. The `--no-deps` flag on `pip install .` defeats the entire purpose of declaring direct dependencies. It must be replaced with a plain `pip install .` so that pip resolves all
+  declared dependencies (including the newly-direct `github-copilot-sdk`).
+- Q: Should the `copilot-setup-steps.yml` workflow (used for Copilot cloud agent setup) also be checked and updated if it contains similar SDK install workarounds? → A: Yes, all workflow files under
+  `.github/workflows/` that contain separate `github-copilot-sdk` install steps or `--no-deps`/`--force-reinstall` workarounds must be updated. The scope includes `ai-pr-loop.yml`,
+  `speckit-phase-progression.yml`, and any other workflow exhibiting the same pattern. The spec's FR-003 and FR-004 explicitly name the two known workflows; any additional workflows discovered during
+  implementation should be fixed under the same principle.
 
 ## User Scenarios & Testing
 
@@ -78,9 +99,12 @@ than silently succeeding.
 As a maintainer of `copilot_generate.py`, I want the script's import error handling to rely on standard Python mechanisms rather than custom `pip show` subprocess diagnostics, reducing code complexity
 and test maintenance burden.
 
-The current `copilot_generate.py` contains approximately 20 lines of defensive code that shells out to `pip show github-copilot-sdk` and `pip show copilot` to diagnose installation problems. This code
-exists solely because the SDK might not be installed despite `agentic-devtools` being present. Once the SDK is a direct dependency, these diagnostics become redundant — a missing SDK means
-`agentic-devtools` itself wasn't installed, and standard `ModuleNotFoundError` tracebacks are clear enough.
+The current `copilot_generate.py` (at `.github/scripts/speckit-trigger/copilot_generate.py`) contains approximately 20 lines of defensive code that shells out to `pip show github-copilot-sdk` and
+`pip show copilot` to diagnose installation problems. This code exists solely because the SDK might not be installed despite `agentic-devtools` being present. Once the SDK is a direct dependency,
+these diagnostics become redundant because installation and import failures should be surfaced through standard pip/Python error reporting.
+
+The entire defensive diagnostic block (including the conflicting-package shadow detection for the `copilot` package name) must be removed. The except block should allow the `ImportError` to propagate
+naturally with standard Python traceback output.
 
 **Why this priority**: This is a clean-up task that reduces maintenance burden but doesn't change user-facing behavior. The diagnostic removal makes the codebase simpler and eliminates test assertions
 that track internal implementation details rather than observable behavior.
@@ -123,8 +147,11 @@ steps.
   installation.
 - What happens if `github-copilot-sdk` is temporarily unavailable on PyPI? The `agentic-devtools` installation will fail entirely, which is the correct behavior — it's better to fail clearly at
   install time than to succeed installation and fail at runtime.
-- What happens to environments that previously installed `agentic-devtools` with the `[copilot-sdk]` extra? The extra group is removed, so `pip install agentic-devtools[copilot-sdk]` will fail due
-  to an unknown/invalid extra. Migration guidance is to run `pip install agentic-devtools` (without extras), since the SDK is now installed unconditionally.
+- What happens to environments that previously installed `agentic-devtools` with the `[copilot-sdk]` extra? The extra group is removed, so `pip install agentic-devtools[copilot-sdk]` will emit a
+  warning about an unknown extra (pip does not hard-fail on unknown extras but prints a warning). Migration guidance is to run `pip install agentic-devtools` (without extras), since the SDK is now
+  installed unconditionally. A CHANGELOG.md entry will document this change.
+- What happens to `pip install . --no-deps` in `speckit-phase-progression.yml`? This flag is removed because it prevented pip from resolving any dependencies including the newly-direct SDK. It is
+  replaced with a plain `pip install .`.
 
 ## Requirements
 
@@ -140,17 +167,23 @@ steps.
   installation, `--force-reinstall`, or `--no-deps` flags present. An optional SDK import smoke check command MAY be retained.
 
 - **FR-004**: The `.github/workflows/speckit-phase-progression.yml` install step MUST use `pip install --upgrade pip` and `pip install .` as the installation commands, with no separate SDK
-  installation, `--force-reinstall`, or `--no-deps` flags present. An optional SDK import smoke check command MAY be retained.
+  installation, `--force-reinstall`, or `--no-deps` flags present (including the `--no-deps` flag on the `pip install .` command itself, which must also be removed). An optional SDK import smoke check
+  command MAY be retained.
 
-- **FR-005**: The `copilot_generate.py` script MUST NOT invoke `pip show github-copilot-sdk` or `pip show copilot` as subprocess commands for diagnostic purposes. Import failure handling should rely
-  on standard Python exception propagation.
+- **FR-005**: The `copilot_generate.py` script (at `.github/scripts/speckit-trigger/copilot_generate.py`) MUST NOT invoke `pip show github-copilot-sdk` or `pip show copilot` as subprocess commands for
+  diagnostic purposes. The entire defensive diagnostic block — including the conflicting-package shadow detection — must be removed. Import failure handling should rely
+  on standard Python exception propagation (allowing `ImportError`/`ModuleNotFoundError` to propagate naturally).
 
-- **FR-006**: All existing tests in the repository MUST continue to pass after the changes. Tests that assert on SDK diagnostic messages (such as strings containing `"pip show github-copilot-sdk"`)
+- **FR-006**: All existing tests in the repository MUST continue to pass after the changes. Tests that assert on SDK diagnostic messages (such as strings containing `"pip show github-copilot-sdk"` or
+  `"Ensure 'github-copilot-sdk' is installed"`)
   MUST be updated or removed to reflect the simplified error handling.
 
 - **FR-007**: The upper bound version constraint (`<1.0.0`) MUST be maintained on the SDK dependency to protect against breaking changes from a future v1 release, consistent with the project's stated
   intent to address the v1 upgrade in a separate issue.
 
+- **FR-008**: A CHANGELOG.md entry MUST be added under the next release section documenting: (a) the removal of the `copilot-sdk` optional extra, (b) that `github-copilot-sdk` is now a direct
+  dependency installed automatically, and (c) that users previously using `pip install agentic-devtools[copilot-sdk]` should switch to `pip install agentic-devtools`.
+
 ### Non-Functional Requirements
 
 - **NFR-001**: CI workflow installation time MUST NOT increase by more than 10% compared to the current multi-step installation approach. Since pip already resolves dependencies transitively, the
@@ -165,8 +198,10 @@ steps.
 ### Key Entities
 
 - **`pyproject.toml` dependency declaration**: The single source of truth for the SDK version constraint, consumed by pip during installation of `agentic-devtools`.
-- **CI workflow install steps**: The YAML configurations in `.github/workflows/` that install the package in CI runners. These must be simplified to a single pip install command.
-- **SDK diagnostic block in `copilot_generate.py`**: The defensive import error handling code that performs subprocess calls to diagnose SDK installation issues.
+- **CI workflow install steps**: The YAML configurations in `.github/workflows/` that install the package in CI runners. These must be simplified to a single pip install command (specifically
+  `ai-pr-loop.yml` and `speckit-phase-progression.yml`, plus any other workflows found to have the same pattern).
+- **SDK diagnostic block in `copilot_generate.py`**: The defensive import error handling code (approximately lines 30–56 in `.github/scripts/speckit-trigger/copilot_generate.py`) that performs
+  subprocess calls to diagnose SDK installation issues, including the conflicting-package shadow detection.
 
 ## Success Criteria
 

agentic_devtools-0.2.161/specs/1767-rename-workflow-files-clarity/.markdownlint.json

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