agentic-devtools 0.2.125__tar.gz → 0.2.126__tar.gz

{agentic_devtools-0.2.125 → agentic_devtools-0.2.126}/PKG-INFO

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

{agentic_devtools-0.2.125 → agentic_devtools-0.2.126}/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.125'
-__version_tuple__ = version_tuple = (0, 2, 125)
+__version__ = version = '0.2.126'
+__version_tuple__ = version_tuple = (0, 2, 126)
 
 __commit_id__ = commit_id = None

{agentic_devtools-0.2.125 → agentic_devtools-0.2.126}/agentic_devtools/cli/azure_devops/review_commands.py

@@ -104,12 +104,43 @@ def _get_linked_pull_request_from_jira(issue_key: str) -> int | None:
     return None
 
 
+def _try_force_push_after_rebase(dry_run: bool) -> bool | None:
+    """Attempt force push after a successful rebase.
+
+    Wraps ``force_push()`` so that a push failure is non-blocking: the rebase
+    already succeeded locally and the caller can continue.
+
+    Args:
+        dry_run: If True, delegates to ``force_push(dry_run=True)`` which only
+            prints what would happen.
+
+    Returns:
+        ``True`` if the push succeeded, ``False`` if it failed, or ``None``
+        when running in dry-run mode.
+    """
+    from ..git.operations import force_push
+
+    if dry_run:
+        force_push(dry_run=True)
+        return None
+
+    try:
+        force_push(dry_run=False)
+        return True
+    except SystemExit:
+        print(
+            "Warning: Rebase succeeded but push failed. "
+            "You can manually push with: git push --force-with-lease"
+        )
+        return False
+
+
 def checkout_and_sync_branch(
     source_branch: str,
     pull_request_id: int | None = None,
     save_files_on_branch: bool = False,
     dry_run: bool = False,
-) -> tuple[bool, str | None, set[str], bool]:
+) -> tuple[bool, str | None, set[str], bool, bool | None]:
     """
     Checkout the PR source branch, sync it with origin, and rebase onto main.
 
@@ -119,6 +150,7 @@ def checkout_and_sync_branch(
        so the local copy reflects the author's latest pushed commits
     3. Fetching the latest from origin/main
     4. Rebasing onto main (continues even if conflicts, with warning)
+    5. If rebase rewrote history, force-pushing to update the remote
 
     Args:
         source_branch: The PR source branch name (without refs/heads/)
@@ -129,11 +161,13 @@ def checkout_and_sync_branch(
             based on the current HEAD.
 
     Returns:
-        Tuple of (success, error_message, files_on_branch, had_rebase_conflicts)
+        Tuple of (success, error_message, files_on_branch, had_rebase_conflicts, push_succeeded)
         - success: True if checkout succeeded and we can proceed
         - error_message: If success is False, the message to show the user
         - files_on_branch: Set of file paths changed on this branch vs main
         - had_rebase_conflicts: True if rebase conflicts were detected
+        - push_succeeded: True if auto-push succeeded, False if it failed,
+          None if no push was attempted (no rebase, or dry-run)
     """
     from ..git.operations import (
         checkout_branch,
@@ -161,12 +195,14 @@ def checkout_and_sync_branch(
                 f"{'=' * 60}",
                 set(),
                 False,
+                None,
             )
         return (  # pragma: no cover
             False,
             f"Error checking out branch: {checkout_result.message}",
             set(),
             False,
+            None,
         )
 
     # Step 1b: Fetch source branch from origin to get latest changes
@@ -176,6 +212,7 @@ def checkout_and_sync_branch(
             f"Failed to fetch origin/{source_branch}. Cannot proceed with review on potentially stale code.",
             set(),
             False,
+            None,
         )
 
     # Step 1c: Reset local branch to match origin
@@ -186,10 +223,12 @@ def checkout_and_sync_branch(
             "See the messages above for details and resolution steps.",
             set(),
             False,
+            None,
         )
 
     # Step 2: Fetch latest from main
     had_rebase_conflicts = False
+    push_succeeded: bool | None = None
     fetch_success = fetch_main(dry_run=dry_run)
     if not fetch_success:
         print("Warning: Could not fetch from origin/main, continuing without rebase...")
@@ -200,6 +239,9 @@ def checkout_and_sync_branch(
 
         if rebase_result.is_success:
             print("Branch is synced with main.")
+            # Step 3b: Auto-push if rebase rewrote history
+            if rebase_result.was_rebased:
+                push_succeeded = _try_force_push_after_rebase(dry_run)
         elif rebase_result.needs_manual_resolution:
             had_rebase_conflicts = True
             # Continue with review but warn about conflicts
@@ -232,7 +274,7 @@ def checkout_and_sync_branch(
             json.dump({"files": list(files_set)}, f, indent=2)
         print(f"Saved files on branch to: {files_on_branch_path}")
 
-    return True, None, files_set, had_rebase_conflicts
+    return True, None, files_set, had_rebase_conflicts, push_succeeded
 
 
 def _normalize_path_for_comparison(path: str) -> str:
@@ -869,7 +911,9 @@ def setup_pull_request_review() -> None:
     had_rebase_conflicts = False
     if source_branch:
         print(f"\nChecking out source branch '{source_branch}' and syncing with main...")
-        checkout_success, checkout_error, files_on_branch, had_rebase_conflicts = checkout_and_sync_branch(
+        (
+            checkout_success, checkout_error, files_on_branch, had_rebase_conflicts, _push_succeeded,
+        ) = checkout_and_sync_branch(
             source_branch, pull_request_id, save_files_on_branch=True, dry_run=is_dry_run()
         )
 

{agentic_devtools-0.2.125 → agentic_devtools-0.2.126}/agentic_devtools/cli/git/commands.py

@@ -269,6 +269,12 @@ def commit_cmd() -> None:
             force_push(dry_run=False)
         else:
             publish_branch(dry_run=False)
+    else:
+        # Dry-run: report the push that would occur
+        if needs_force_push:
+            force_push(dry_run=True)
+        else:
+            publish_branch(dry_run=True)
 
     # Mark checklist items if specified
     if completed_items and not dry_run:

agentic_devtools-0.2.126/specs/1587-feature-webhook-event-driven/analysis-report.md

@@ -0,0 +1,79 @@
+# Cross-Artifact Consistency & Quality Analysis Report
+
+## Findings Table
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| F-01 | E | MEDIUM | NFR-002 | NFR-002 (15% Actions minutes cap) has no dedicated task or validation mechanism in tasks.md | Add a task to establish a baseline measurement and define how the 15% threshold will be monitored post-deployment |
+| F-02 | F | MEDIUM | tasks.md T008-T011 vs Plan Phase 4 | Tasks T008-T011 are labeled "Dry-run test" but Plan Phase 4 states "no Python unit tests needed (pure bash implementation)" — the tasks reference dry-run validation which requires T007 (DRY_RUN support) to be implemented first, yet no explicit test script or fixture is defined for T008-T011 beyond the fixture in T018 | Clarify whether T008-T011 are manual validations or scripted checks; if scripted, define the test harness |
+| F-03 | F | MEDIUM | E.2 Test Coverage Data vs tasks.md | The pre-validated coverage data maps FR-004→T024, FR-001→T030, FR-003→T031, FR-005→T032, FR-007→T033, but the FR Traceability Matrix in tasks.md maps differently (e.g., FR-001→T013,T016,T008; FR-004→T014,T012,T029). The E.2 data references task IDs that don't align with the traceability matrix | Reconcile E.2 coverage data task ID references with the actual FR Traceability Matrix; the E.2 data appears to reference a different task numbering scheme |
+| F-04 | C | MEDIUM | NFR-001 | "Prioritize recently-active PRs" — no explicit mechanism defined for how deferred PRs are tracked or guaranteed to be processed in subsequent cycles | Document that deferred PRs are naturally re-processed on the next cycle via the same `gh pr list` sorted query (no explicit tracking needed) |
+| F-05 | B | LOW | NFR-002 | "Under 30 seconds per run for typical repositories with fewer than 20 open PRs" — "typical" is subjective; the 20-PR threshold is specific but "typical" weakens it | Reword to "repositories with fewer than 20 open PRs" without "typical" qualifier |
+| F-06 | G | CRITICAL | T008, T009, T010, T011 | Four dry-run validation tasks all target the same file and dispatch logic section with highly overlapping scope — each validates a single field of the same `gh workflow run` command output | Consider consolidating into a single dry-run validation task that checks all dispatch command fields (pr_number, trigger_reason, both event types) in one pass |
+| F-07 | G | CRITICAL | T025, T013 | T025 implements structured log output in the scan step; T013 creates the scan step skeleton — both target the same bash step in the same file with overlapping code sections | Ensure T025 is clearly scoped as an enhancement to the step created in T013, not a rewrite; add explicit dependency |
+| F-08 | F | LOW | Spec "Key Entities" vs Plan | Spec defines "Event Dispatch Record" as containing "a JSON array of integer event IDs" but Plan Phase 1 task 3 says "prune the array to the last N IDs (e.g., 500)" — the spec doesn't mention pruning or size limits | Add pruning/size-limit language to the spec's Key Entities section or NFR-001 |
+| F-09 | D | LOW | Spec | No explicit "Out of Scope" section documenting what this feature intentionally does NOT cover (e.g., webhook-based real-time triggers, changes to orchestrator.py) | Add an "Out of Scope" section to the spec for clarity |
+| F-10 | A | LOW | FR-001, FR-003, FR-005 | FR-001, FR-003, and FR-005 all specify aspects of the same `gh workflow run` dispatch command — FR-001 specifies the full command, FR-003 specifies `pr_number` parameter, FR-005 specifies `trigger_reason` parameter | Acceptable decomposition for traceability but note that FR-003 and FR-005 are subsumed by FR-001's full command specification |
+
+### Category G Structured Findings
+
+[
+  {
+    "id": "F-06",
+    "overlap_type": "overlapping",
+    "severity": "CRITICAL",
+    "task_ids": ["T008", "T009", "T010", "T011"],
+    "dimensions": ["file_path", "code_section"],
+    "rationale": "All four tasks validate different fields of the same dispatch command in the same file and code section. Distinct validation outcomes make this overlapping rather than duplicate."
+  },
+  {
+    "id": "F-07",
+    "overlap_type": "overlapping",
+    "severity": "CRITICAL",
+    "task_ids": ["T025", "T013"],
+    "dimensions": ["file_path", "code_section"],
+    "rationale": "T013 creates the scan step skeleton and T025 adds structured log output within it. Both target the same file and bash step, creating overlap risk during implementation."
+  }
+]
+
+## Coverage Summary Table
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|----------------|-----------|----------|-------|
+| FR-001 | Yes | T008, T013, T016 | Core dispatch mechanism |
+| FR-002 | Yes | T006, T018, T019, T020, T021, T022 | Deduplication via cache |
+| FR-003 | Yes | T009, T016 | PR number field in dispatch |
+| FR-004 | Yes | T012, T014, T029 | Guard checks (fork, label, state) |
+| FR-005 | Yes | T010, T016 | Trigger reason field |
+| FR-006 | Yes | T023, T024, T030 | Coexistence validation |
+| FR-007 | Yes | T011, T015 | Both terminal event types |
+| NFR-001 | Yes | T004, T017 | 2-minute budget + scan cap |
+| NFR-002 | No | — | No measurement/validation task |
+| NFR-003 | Yes | T027, T028 | Per-PR error isolation |
+| NFR-004 | Yes | T025, T026 | Structured logging |
+
+## Metrics
+
+| Metric | Value |
+|--------|-------|
+| Total Requirements | 11 (7 FR + 4 NFR) |
+| Total Tasks | 34 |
+| Coverage % | 91% (10/11 requirements have tasks) |
+| Ambiguity Count | 1 |
+| Requirement Duplication Count (Category A) | 1 (partial subsumption) |
+| Critical Issues Count | 2 |
+| Task Deduplication Finding Count | 2 |
+| Task Deduplication by Type | duplicate: 0 / overlapping: 2 / conflicting: 0 |
+| Multi-Task Group Count | 1 (F-06 involves 4 tasks) |
+
+## Next Actions
+
+1. **Consolidate dry-run validation tasks (F-06)**: Merge T008–T011 into a single task that validates all dispatch command fields in one pass, reducing overlap risk.
+2. **Clarify T025/T013 dependency (F-07)**: Add an explicit dependency from T025 → T013 and scope T025 as an additive enhancement (not a rewrite) of the scan step created in T013.
+3. **Add NFR-002 validation task (F-01)**: Create a task to measure Actions minutes usage against the 15% cap defined in NFR-002.
+4. **Reconcile E.2 coverage data (F-03)**: Align E.2 test coverage task IDs with the FR Traceability Matrix in tasks.md.
+
+> Would you like me to suggest concrete remediation edits to the spec artifacts?
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*

agentic_devtools-0.2.126/specs/1587-feature-webhook-event-driven/fr-coverage.json

@@ -0,0 +1 @@
+{"covered": ["FR-001", "FR-002", "FR-003", "FR-004", "FR-005", "FR-006", "FR-007"], "uncovered": [], "total": 7, "max_retries": 2}

agentic_devtools-0.2.126/specs/1587-feature-webhook-event-driven/plan.md

@@ -0,0 +1,171 @@
+# Implementation Plan: Event-Driven Trigger for AI PR Loop
+
+## Technical Context
+
+- **Repository**: `ayaiayorg/agentic-devtools`
+- **Platform**: GitHub Actions workflows (YAML-based)
+- **Existing infrastructure**:
+  - `ai-pr-loop.yml` — orchestrator workflow with `workflow_dispatch` input accepting `pr_number` (string) and `trigger_reason` (string)
+  - `squash-wait-scheduler.yml` — cron-based (`*/5`) scheduler dispatching via `gh workflow run`
+  - `agentic_devtools/cli/ci/` — Python CI module with `github_provider.py` (Issues Events API via `list_pr_issue_events`), `models.py` (event constants), `session_detector.py` (staleness logic)
+  - Concurrency group: `ai-pr-loop-${{ ... || github.event.inputs.pr_number || github.run_id }}`
+- **Key constants**: `COPILOT_SESSION_EVENT_FINISHED`, `COPILOT_SESSION_EVENT_FINISHED_FAILURE`, `LABEL_SKIP_ENTIRELY = "ai-pr-loop-ignore"`
+- **Auth**: `AGDT_PR_APPROVER_PAT` secret for `gh` CLI calls
+
+## Research Summary
+
+See the decisions below for:
+
+- Caching strategy for event deduplication
+- Monitor workflow structure (standalone vs. integrated)
+- Monitor trigger cadence and dispatch mechanism
+
+All decisions align with the proven `squash-wait-scheduler.yml` pattern.
+
+## Design Overview
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│    agent-session-monitor.yml (*/2 cron + workflow_dispatch)    │
+├─────────────────────────────────────────────────────────────┤
+│  1. Restore seen-events cache (prefix restore)               │
+│  2. List open PRs (non-fork, no ignore label)                │
+│  3. For each PR:                                             │
+│     a. GET /issues/{pr}/events (filter terminal events)     │
+│     b. Deduplicate against seen-events set                  │
+│     c. Dispatch workflow_dispatch for new terminal events    │
+│     d. Append event ID and prune seen-events set to last N   │
+│  4. Save updated seen-events cache (per-run key)             │
+└─────────────────────────────────────────────────────────────┘
+         │
+         │ gh workflow run ai-pr-loop.yml
+         │   --repo "$GITHUB_REPOSITORY"
+         │   --field pr_number="$pr"
+         │   --field trigger_reason=agent_session_finished
+         ▼
+┌─────────────────────────────────────────────────────────────┐
+│              ai-pr-loop.yml (existing, UNCHANGED)           │
+│  concurrency: ai-pr-loop-${{ github.event.pull_request.    │
+│    number || github.event.issue.number ||                  │
+│    github.event.workflow_run.pull_requests[0].number ||    │
+│    github.event.inputs.pr_number || github.run_id }}       │
+│  cancel-in-progress: false                                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Implementation Phases
+
+### Phase 1: Core Monitor Workflow (`.github/workflows/agent-session-monitor.yml`)
+
+**Deliverable**: A self-contained GitHub Actions workflow file.
+
+#### Tasks
+
+1. **Create workflow file** with:
+   - Triggers:
+     - `schedule: - cron: '*/2 * * * *'` (meets the 120-second latency target from FR-001)
+     - `workflow_dispatch` (manual trigger)
+   - Permissions: `contents: read`, `pull-requests: read`, `actions: write`, `issues: read`
+   - Single job `monitor-agent-sessions`, `runs-on: ubuntu-latest`, `timeout-minutes: 2`
+   - **Concurrency group**: `agent-session-monitor` with `cancel-in-progress: false` (serializes scheduled runs)
+
+2. **Step: Restore cache** — use `actions/cache/restore@v4` with:
+   - `key: agent-monitor-seen-events-${{ github.run_id }}`
+   - `restore-keys: agent-monitor-seen-events-`
+   - Path: `.cache/seen-events.json`
+
+3. **Step: Scan and dispatch** — bash script that:
+   - Sets `GH_TOKEN: ${{ secrets.AGDT_PR_APPROVER_PAT }}` in the step env (matching the existing scheduler pattern)
+   - Ensures `.cache/` exists and initializes `.cache/seen-events.json` to `[]` when missing
+   - Loads seen-events JSON (or initializes empty array)
+   - Lists open PRs via `gh pr list --repo $GITHUB_REPOSITORY --json number,labels,isCrossRepository,updatedAt --limit 500`
+   - Sorts PRs by `updatedAt` descending (most recently active first), skips forks via `isCrossRepository`, and excludes PRs labeled `ai-pr-loop-ignore`
+   - For each eligible PR, calls `gh api /repos/{owner}/{repo}/issues/{pr}/events --paginate`
+   - Filters for `copilot_work_finished` and `copilot_work_finished_failure` events
+   - Deduplicates against seen-events set
+   - Dispatches via `gh workflow run ai-pr-loop.yml --repo "$GITHUB_REPOSITORY" --field pr_number="$pr" --field trigger_reason=agent_session_finished`
+   - Appends processed event IDs to seen-events JSON and prunes the array to the last N IDs (e.g., 500)
+   - Enforces a scan budget (e.g., stop at ~110 seconds) so runtime stays within 2 minutes; remaining PRs are handled in subsequent runs
+   - Emits structured logs: `event_id=X pr_number=Y action=dispatched|skipped reason=...`
+   - Isolates per-PR scan failures so one PR does not block others, records whether any PR scan
+     errors occurred (for example via a step output or error flag file), and completes the step
+     without exiting non-zero before cache persistence
+
+4. **Step: Save cache** — use `actions/cache/save@v4` with:
+   - `if: always()`
+   - `key: agent-monitor-seen-events-${{ github.run_id }}`
+   - Path: `.cache/seen-events.json`
+
+5. **Step: Surface partial-cycle failure after cache save** — final bash step that runs after the
+   cache save, checks the recorded scan-error flag/output, and exits non-zero if any PR scan
+   errors prevented full completion of the cycle.
+
+6. **No additional trigger-emitter integration** — monitor relies on `*/2` schedule + manual
+   `workflow_dispatch`; no `repository_dispatch` emitter or external trigger plumbing is required.
+
+7. **Per-PR error isolation with surfaced failure** — isolate each PR scan so one failure does
+   not block others, preserve updated deduplication state by always saving the cache, and then
+   fail the job in a final step if any PR scan errors prevented full completion of the cycle.
+
+### Phase 2: Guard Checks in Monitor
+
+**Deliverable**: FR-004 compliance — skip ineligible PRs before dispatch.
+
+#### Tasks
+
+1. **Fork detection** — handled by `gh pr list --json isCrossRepository`; skip PRs where `isCrossRepository` is true.
+2. **Label filtering** — check for `ai-pr-loop-ignore` in PR labels JSON.
+3. **PR state check** — `gh pr list` only returns open PRs by default, satisfying the "currently open" requirement.
+4. **Closed/merged race** — if a PR is closed between list and dispatch, the `ai-pr-loop.yml` orchestrator handles this gracefully (existing behavior).
+
+### Phase 3: Observability & Logging
+
+**Deliverable**: NFR-004 structured logging.
+
+#### Tasks
+
+1. **Structured output format** — each action line as `key=value` pairs:
+
+   ```text
+   ts=2026-05-27T11:30:00Z pr_number=42 event_id=123456 event_type=copilot_work_finished action=dispatched
+   ts=2026-05-27T11:30:00Z pr_number=43 event_id=789012 action=skipped reason=already_seen
+   ts=2026-05-27T11:30:01Z pr_number=44 action=skipped reason=label_excluded
+   ```
+
+2. **Summary output** — workflow summary via `$GITHUB_STEP_SUMMARY` with total PRs scanned, events found, dispatches issued.
+3. **Error logging and exit policy** — API failures are logged with structured context, processing
+   continues for other PRs, and the run exits non-zero if any scan failure prevented full cycle
+   completion (aligned with the observability acceptance scenario).
+
+### Phase 4: Testing & Validation
+
+**Deliverable**: Confidence in correctness before merge.
+
+#### Tasks
+
+1. **Deduplication validation** — verify correctness via `DRY_RUN` mode (item 3) with a
+   pre-seeded `.cache/seen-events.json` fixture; no Python unit tests needed (pure bash
+   implementation with no Python code changes).
+2. **Manual validation** — trigger `workflow_dispatch` on the monitor to verify it scans and dispatches correctly.
+3. **Dry-run mode** — add `DRY_RUN` env var that logs dispatches without executing `gh workflow run`.
+4. **Integration verification** — confirm `ai-pr-loop.yml` processes the dispatch correctly (existing `workflow_dispatch` path already handles this).
+
+## Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+| --- | --- | --- | --- |
+| Cache eviction causes re-dispatch | Medium | Low | Concurrency group (added in Phase 1) serializes runs and reduces overlap; retained seen-event cache reduces duplicate dispatches within the cache window, with occasional re-dispatch after eviction accepted as low impact |
+| API rate limiting with many open PRs | Low | Medium | Process PRs by `updatedAt` descending, cap each run to ~110s within `timeout-minutes: 2`, and keep per-PR error isolation so one failing PR does not abort the run |
+| Monitor overlapping with itself | Low | Low | Concurrency group `agent-session-monitor` with `cancel-in-progress: false` (defined in Phase 1) serializes scheduled runs; `timeout-minutes: 2` as a secondary safeguard |
+| `gh workflow run` fails silently | Low | Medium | Check exit code; log failures as `::error::` |
+| Cache grows unbounded | Low | Low | Retain only the last N event IDs (e.g., 500) in `.cache/seen-events.json`; use the Phase 1 per-run cache key `agent-monitor-seen-events-${{ github.run_id }}` with restore prefix matching so the restored payload stays bounded without introducing an undefined bucket variable |
+
+## Dependencies
+
+- **External**: GitHub Actions cache (`actions/cache@v4`), GitHub Issues Events API, `gh` CLI
+- **Internal**: `ai-pr-loop.yml` `workflow_dispatch` inputs (already exist, no changes needed)
+- **Secrets**: `AGDT_PR_APPROVER_PAT` (same as squash-wait-scheduler)
+- **No changes to**: `ai-pr-loop.yml`, `orchestrator.py`, `session_detector.py`, or any Python code
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*

agentic_devtools-0.2.126/specs/1587-feature-webhook-event-driven/tasks.md

@@ -0,0 +1,140 @@
+# Tasks: Event-Driven Trigger for AI PR Loop on Agent Session Completion
+
+**Feature Branch**: `speckit/1587/phase-4-tasks`
+**Source Issue**: [#1587](https://github.com/ayaiayorg/agentic-devtools/issues/1587)
+
+---
+
+## Phase Mapping: Plan → Tasks
+
+| Tasks Phase | Plan Phase(s) | Description |
+| --- | --- | --- |
+| Phase 1: Setup | Phase 1: Core Monitor Workflow | Create the monitor workflow scaffold and baseline trigger/permission structure. |
+| Phase 2: Foundational — Cache & Job Structure | Phase 1: Core Monitor Workflow | Establish timeout, cache persistence, and dry-run support used by all stories. |
+| Phase 3: User Story 1 — Immediate Post-Agent PR Processing (P1) | Phase 1: Core Monitor Workflow | Add US1 validations and implement PR scanning plus workflow dispatch behavior. |
+| Phase 4: User Story 2 — Idempotent Event Processing (P1) | Phase 1: Core Monitor Workflow | Add US2 validations and implement event-id deduplication and cache fallback behavior. |
+| Phase 5: User Story 3 — Graceful Coexistence with Existing Triggers (P2) | Phase 2: Guard Checks | Validate and document coexistence with existing trigger paths and shared concurrency. |
+| Phase 6: User Story 4 — Monitor Workflow Observability (P3) | Phase 3: Observability & Logging | Implement structured logs, summary output, and error isolation/failure signaling. |
+| Phase 7: Testing & Validation | Phase 4: Testing & Validation | Execute cross-story negative and integration validations. |
+| Phase 8: Polish & Cross-Cutting | Phase 4: Testing & Validation | Final documentation, full checks, and completion review. |
+
+---
+
+## Phase 1: Setup
+
+- [ ] T001 Create feature branch `feature/1587/webhook-event-driven` from `main`
+- [ ] T002 Create workflow file scaffold at `.github/workflows/agent-session-monitor.yml` with name, triggers (`on: schedule: - cron: '*/2 * * * *'`,
+  `workflow_dispatch`), permissions (`contents: read`, `pull-requests:
+  read`, `actions: write`, `issues: read`), and empty job skeleton
+
+---
+
+## Phase 2: Foundational — Cache & Job Structure
+
+- [ ] T003 Add concurrency group `agent-session-monitor` with `cancel-in-progress: false` to the monitor job in `.github/workflows/agent-session-monitor.yml`
+- [ ] T004 Add `timeout-minutes: 2` to the monitor job in `.github/workflows/agent-session-monitor.yml`
+- [ ] T005 Add cache restore step using `actions/cache/restore@v4` with key `agent-monitor-seen-events-${{ github.run_id }}` and `restore-keys: agent-monitor-seen-events-` targeting
+  `.cache/seen-events.json`
+- [ ] T006 Add cache save step using `actions/cache/save@v4` with `if: always()` and key `agent-monitor-seen-events-${{ github.run_id }}` targeting `.cache/seen-events.json` (FR-002: deduplication
+  persistence via GitHub Actions cache with restore-keys prefix and per-run save key)
+- [ ] T007 Add `DRY_RUN` environment variable support — when set, log dispatch commands without executing `gh workflow run`
+
+---
+
+## Phase 3: User Story 1 — Immediate Post-Agent PR Processing (P1)
+
+- [ ] T008 [US1] Dry-run test for FR-001 — verify monitor generates a dispatch command for each new terminal event (success path) (FR-001)
+- [ ] T009 [US1] Dry-run test for FR-003 — verify `--field pr_number` is correctly set in the generated dispatch command (success path) (FR-003)
+- [ ] T010 [US1] Dry-run test for FR-005 — verify `--field trigger_reason=agent_session_finished` is correctly set in the generated dispatch command (success path) (FR-005)
+- [ ] T011 [US1] Dry-run test for FR-007 — verify both `copilot_work_finished` and `copilot_work_finished_failure` events trigger dispatch (success path) (FR-007)
+- [ ] T012 [US1] Manual happy-path success test — trigger `workflow_dispatch` on `agent-session-monitor.yml` and verify structured logs, cache creation,
+  and dispatch behavior for eligible open PRs (FR-004)
+- [ ] T013 [US1] Write the main "Scan and dispatch" bash step skeleton in `.github/workflows/agent-session-monitor.yml` setting `GH_TOKEN: ${{ secrets.AGDT_PR_APPROVER_PAT }}`, initializing
+  `.cache/seen-events.json` to `[]` if missing, and loading the seen-events array (FR-001: scheduled monitor workflow running `*/2`)
+- [ ] T014 [US1] Implement open PR listing via `gh pr list --repo $GITHUB_REPOSITORY --json number,labels,isCrossRepository,updatedAt --limit 500` sorted by `updatedAt` descending in the scan step
+  (FR-004: only open, non-fork PRs without `ai-pr-loop-ignore` label)
+- [ ] T015 [US1] Implement per-PR event fetching via `gh api /repos/{owner}/{repo}/issues/{pr}/events --paginate` filtering for `copilot_work_finished` and `copilot_work_finished_failure` event types
+  (FR-007: handles both successful and failed terminal events)
+- [ ] T016 [US1] Implement dispatch logic via `gh workflow run ai-pr-loop.yml --repo "$GITHUB_REPOSITORY" --field pr_number="$pr" --field trigger_reason=agent_session_finished` for new terminal events
+  (FR-001: triggers AI PR loop within 120s; FR-003: passes `pr_number` input; FR-005: sets `trigger_reason` to `agent_session_finished`)
+- [ ] T017 [US1] Add scan budget enforcement (~110 seconds elapsed time check) to prioritize recently-active PRs and defer remaining to next cycle (NFR-001)
+
+---
+
+## Phase 4: User Story 2 — Idempotent Event Processing (P1)
+
+- [ ] T018 [US2] Create a test fixture `.github/test-fixtures/seen-events-sample.json` with pre-seeded event IDs for deduplication validation in dry-run mode (FR-002)
+- [ ] T019 [US2] Validate deduplication by running monitor with `DRY_RUN=true` and pre-seeded seen-events fixture, confirming already-seen events are skipped (FR-002)
+- [ ] T020 [US2] Implement event ID deduplication check against the loaded seen-events JSON array before dispatching (FR-002: at most one dispatch per unique event ID)
+- [ ] T021 [US2] Implement appending dispatched event IDs to seen-events array and pruning to last 500 entries after each cycle (FR-002: bounded cache size)
+- [ ] T022 [US2] Add handling for missing/evicted cache — treat as empty set, allow re-dispatch with concurrency group as secondary defense (FR-002 graceful degradation)
+
+---
+
+## Phase 5: User Story 3 — Graceful Coexistence with Existing Triggers (P2)
+
+- [ ] T023 [US3] Validate coexistence by exercising an existing `ai-pr-loop.yml` trigger path alongside monitor-issued dispatch and verifying shared
+  `ai-pr-loop-{pr_number}` concurrency serializes runs without conflict (FR-006)
+- [ ] T024 [US3] Document in workflow comments that the monitor supplements existing triggers and relies on `ai-pr-loop-{pr_number}` concurrency group in `ai-pr-loop.yml` to serialize concurrent runs
+  (FR-006)
+
+---
+
+## Phase 6: User Story 4 — Monitor Workflow Observability (P3)
+
+- [ ] T025 [P] [US4] Implement structured `key=value` log output for each action (`ts=... pr_number=... event_id=... event_type=... action=dispatched|skipped reason=...`) in the scan step (NFR-004)
+- [ ] T026 [P] [US4] Add `$GITHUB_STEP_SUMMARY` output with total PRs scanned, events found, dispatches issued, and errors encountered
+- [ ] T027 [US4] Implement per-PR error isolation — wrap each PR scan in error handling so one failure does not block others; record scan-error flag for final step
+- [ ] T028 [US4] Add final step after cache save that checks scan-error flag and exits non-zero if any PR scan errors occurred (surfaces failure in Actions UI after cache is persisted)
+
+---
+
+## Phase 7: Testing & Validation
+
+- [ ] T029 [US1] Negative validation for FR-004 — confirm forked, closed/merged, or `ai-pr-loop-ignore` PRs are skipped, logged with skip reason, and do not issue `workflow_dispatch` commands
+- [ ] T030 Integration verification — confirm dispatched `workflow_dispatch` is received by `ai-pr-loop.yml` and PR number is correctly resolved in its concurrency group
+
+---
+
+## Phase 8: Polish & Cross-Cutting
+
+- [ ] T031 [P] Add inline documentation comments in `.github/workflows/agent-session-monitor.yml` explaining design decisions, FR traceability, and relationship to `squash-wait-scheduler.yml`
+- [ ] T032 [P] Update `PR_DESCRIPTION.md` or create PR description documenting the feature, referencing #1587
+- [ ] T033 Run existing CI checks (`bash scripts/run-pr-checks.sh`) to confirm no regressions introduced
+- [ ] T034 Final review — verify all FRs are addressed and all implementation checklist items are complete
+
+---
+
+## Dependency Graph
+
+```text
+T001 → T002 → T003, T004, T005, T006 (parallel)
+T005, T006 → T007
+T007 → T008, T009, T010, T011, T012 (parallel)
+T007 → T013 → T014 → T015 → T016 → T017
+T007, T016 → T018 → T019
+T016 → T020 → T021 → T022
+T016 → T023 → T024
+T013 → T025, T026, T027 (parallel)
+T027 → T028
+T014 → T029
+T016, T023 → T030
+T030 → T031, T032 (parallel) → T033 → T034
+```
+
+---
+
+## FR Traceability Matrix
+
+| FR | Tasks |
+| --- | --- |
+| FR-001 | T013, T016, T008 |
+| FR-002 | T006, T018, T019, T020, T021, T022 |
+| FR-003 | T016, T009 |
+| FR-004 | T014, T012, T029 |
+| FR-005 | T016, T010 |
+| FR-006 | T023, T024, T030 |
+| FR-007 | T015, T011 |
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*